This GitHub Action automates the process of building and pushing Docker images to Docker Hub and/or GitHub Container Registry (GHCR). It supports multi-platform builds, generates Open Containers Initiative (OCI) compliant metadata, and optimizes build performance with dynamic caching. Ideal for CI/CD pipelines requiring reliable Docker image publishing.
- Multi-Platform Support: Builds images for multiple architectures (e.g., linux/amd64, linux/arm64) using Docker Buildx and QEMU.
- Flexible Registry Publishing: Pushes images to Docker Hub, GHCR, or both, with conditional logic to verify repository existence.
- Dynamic Tagging: Generates tags based on branch, tag, semantic version, and commit SHA using docker/metadata-action.
- OCI Metadata: Applies labels and annotations like org.opencontainers.image.created, licenses, and version for compliance.
- Optimized Caching: Uses dynamic registry-based caching to speed up builds, with cache disabled for tag events to ensure fresh publishes.
- Environment Variables: Supports optional .env file loading for configuration.
- Debugging and Validation: Includes steps to verify tags, digests, and metadata post-push.
-
Docker Hub Credentials:
- Create a Docker Hub Personal Access Token (PAT).
- Add DOCKER_USERNAME and DOCKER_PAT as repository secrets in GitHub.
-
GitHub Container Registry (GHCR):
- Ensure the repository exists and is accessible.
- Use GITHUB_TOKEN (provided by default) or a custom token with packages:write permission.
-
Permissions:
permissions:
contents: read
packages: writeDockerfile: A valid Dockerfile in the repository root, supporting multi-stage builds if needed.
| Name | Description | Required | Default |
|---|---|---|---|
docker-username |
Docker Hub username for authentication. | Yes | - |
docker-pat |
Docker Hub Personal Access Token for authentication. | Yes | - |
image-name |
Name of the Docker image (e.g., my-app). |
Yes | - |
github-token |
GitHub token for GHCR authentication. | Yes | ${{ github.token }} |
log-level |
Log level for build process (debug, info, warn, error). |
No | debug |
authors |
Image authors (e.g., John Doe <john@example.com>). |
No | - |
licenses |
Image license (e.g., MIT, Apache-2.0). |
No | MIT |
vendor |
Image vendor (e.g., My Company). |
No | - |
maintainers |
Image maintainers (e.g., Jane Doe <jane@example.com>). |
No | - |
description |
Image description (e.g., Lightweight linter environment). |
No | - |
publish-dockerhub |
Whether to publish
9861
to Docker Hub (true or false). |
No | true |
publish-ghcr |
Whether to publish to GitHub Container Registry (true or false). |
No | false |
env-file |
Path to optional .env file for environment variables. |
No | .env |
title |
Image title (e.g., Docker Bullseye Linter). |
No | - |
version |
Image version (e.g., 1.0.0). |
No | - |
| Name | Description |
|---|---|
tags |
Comma-separated list of generated tags. |
labels |
Generated OCI labels for the image. |
Create a file at .github/workflows/build.yml:
name: Build and Push Docker Image
on:
push:
branches: [main]
tags: ['v*']
pull_request:
branches: [main]
schedule:
- cron: '0 0 * * 0' # Weekly on Sunday
workflow_dispatch:
permissions:
contents: read
packages: write
jobs:
build-and-push:
runs-on: ubuntu-latest
steps:
- name: Build and Push Docker Image
uses: afreisinger/build-push-action@v1.3.2
with:
image-name: my-app
docker-username: ${{ secrets.DOCKER_USERNAME }}
docker-pat: ${{ secrets.DOCKER_PAT }}
github-token: ${{ secrets.GITHUB_TOKEN }}
publish-dockerhub: true
publish-ghcr: trueIf using an optional .env file for configuration, create it at the repository root:
LICENSES=MIT
DESCRIPTION=Lightweight environment for my app
AUTHORS=John Doe <john@example.com>
The action automatically builds for linux/amd64 and linux/arm64. Ensure your Dockerfile is compatible with these platforms.
The action includes debugging steps that output tags, digests, and labels to the GitHub Actions logs. To verify the published image:
docker pull docker.io/your-username/my-app:latest
docker inspect docker.io/your-username/my-app:latest | grep -E 'org.opencontainers.image'
docker inspect docker.io/your-username/my-app:latest | jq '.[0].Config.Labels'Contributions are welcome! Please:
- Fork the repository.
- Create a feature branch (git checkout -b feature/my-feature).
- Commit your changes (git commit -m 'Add my feature').
- Push to the branch (git push origin feature/my-feature).
- Open a Pull Request.
See CONTRIBUTING.md for more details.
This action is licensed under the MIT License.
For issues or questions, open an issue in the repository or contact the maintainers.