Build and Push Docker Images in GitHub Actions
A practical guide to building, tagging, caching, and pushing Docker images from GitHub Actions using buildx, GHCR, and multi-arch builds.
Key takeaways
- To build and push a Docker image from GitHub Actions, chain four official actions: setup-buildx-action, login-action, metadata-action, and build-push-action (v7 as of October 2026).
- Push to GHCR with the built-in GITHUB_TOKEN and packages write permission, cache layers with type=gha,mode=max, and skip the push on pull requests.
On this page
To build and push a Docker image in GitHub Actions, run docker/setup-buildx-action@v4, log in with docker/login-action@v4, generate tags with docker/metadata-action@v6, then build and push with docker/build-push-action@v7. For GHCR, the built-in GITHUB_TOKEN plus permissions: packages: write is all the auth you need.
Verified against
docker/build-push-action v7.4, setup-buildx-action v4.4, login-action v4.7, metadata-action v6.2, actions/checkout v7.0, against the Docker Build CI docs and GitHub Packages and Actions cache docs. Checked October 2026.
Building an image in CI is easy. Building it fast, tagging it sanely, and pushing it with the smallest permissions is where teams trip. Below is the stack the Docker org maintains, a workflow you can paste, and the errors you will hit on the way.
The four actions, and what each one does
Almost every production pipeline uses the same four official actions, in this order (latest releases as of October 2026):
- docker/setup-buildx-action@v4: boots a BuildKit builder using the
docker-containerdriver. That unlocks cache export, multi-arch, andRUN --mount. Skip it and you get the defaultdockerdriver, which cannot export a cache. - docker/login-action@v4: authenticates to your registry so the push succeeds.
- docker/metadata-action@v6: derives tags and OCI labels from Git context (branch, tag, SHA), so you never hand-write tag logic.
- docker/build-push-action@v7: runs
buildx buildand pushes.
You can shell out to docker build, but you lose the metadata wiring and the cache exporters that make these actions worth using.
The full workflow, ready to paste
This builds on every push and pull request, pushes only from main and v* tags, and caches layers in the Actions cache:
# .github/workflows/docker.yml
name: docker
on:
push:
branches: [main]
tags: ["v*"]
pull_request:
permissions:
contents: read
packages: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: docker/setup-buildx-action@v4
- id: meta
uses: docker/metadata-action@v6
with:
images: ghcr.io/${{ github.repository }}
tags: |
type=sha
type=ref,event=branch
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=raw,value=latest,enable={{is_default_branch}}
- uses: docker/login-action@v4
if: github.event_name != 'pull_request'
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v7
with:
context: .
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha,scope=app
cache-to: type=gha,scope=app,mode=max
A push of Git tag v1.4.2 on a commit produces sha-<shortsha>, 1.4.2 and 1.4 tags; a push to main produces sha-<shortsha>, main and latest. Deploy from the SHA tag, never latest, so you always know exactly what is running.
Two properties matter more than the YAML. permissions grants exactly what the job needs: read the repo, write packages. A compromised dependency in the build cannot do anything else with the token. And pull requests still build, so a broken Dockerfile fails the check, but they never log in and never push. Fork PRs with registry credentials are a classic secret leak; we cover the rest of that threat model in GitHub Actions security hardening.
Other registries: Docker Hub and Amazon ECR
For Docker Hub, store a Hub access token (not your password) as a secret and drop the registry: line:
# .github/workflows/docker.yml (login step only)
- uses: docker/login-action@v4
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
For Amazon ECR, replace login-action with aws-actions/configure-aws-credentials assuming an OIDC role, then aws-actions/amazon-ecr-login@v2. Add id-token: write to permissions and point metadata-action at the ECR repository URI. build-push-action itself does not change, and no long-lived AWS keys sit in the repo.
Layer caching: type=gha versus registry
Runners are ephemeral, so the local layer cache is gone on every run unless you export it.
type=gha: stores layers in the GitHub Actions cache. GitHub gives each repository 10 GB by default (admins can raise it, and overage is billed) and evicts entries not accessed in 7 days. Builds that share ascopeoverwrite each other, so give each image in a repo its ownscope=. The default scope isbuildkit.type=registry: pushes cache layers to a tag such asghcr.io/org/app:buildcache. No Actions cache cap and shareable across repos, at the cost of an extra tag to manage.
Use mode=max on cache-to to export intermediate stages too; the default min only caches layers in the final image, which is useless for multi-stage builds where the slow work happens in the builder stage.
Multi-arch builds
To ship one tag that resolves to amd64 on x86 servers and arm64 on Graviton or Apple Silicon, add QEMU and a platforms input:
# .github/workflows/docker.yml (changed steps only)
- uses: docker/setup-qemu-action@v4
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
with:
platforms: linux/amd64,linux/arm64
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
cache-from: type=gha,scope=app
cache-to: type=gha,scope=app,mode=max
Emulated builds are slow, especially when compiling native extensions. When ARM build time starts to hurt, build each platform on its own runner (ubuntu-24.04-arm for arm64) and merge the manifests; Docker's docs now ship reusable docker/github-builder workflows that do exactly this. The detailed tradeoffs are in multi-arch Docker builds with buildx.
Errors you will hit, and the fix for each
ERROR: Cache export is not supported for the docker driver. You set cache-to without docker/setup-buildx-action, so the build ran on the default driver. Add the buildx step before the build.
denied: installation not allowed to Write organization package (or denied: permission_denied: write_package). The package already exists and this repository has no write access to it. Open the package settings, use Manage Actions access, add the repository with the Write role, and confirm the job declares packages: write.
unauthorized: authentication required on push. The login step was skipped (often by the PR condition on a push event you did not expect) or the secret is empty in a fork. Check the step ran and that push and login share the same condition.
ERROR: failed to solve: maximum timeout reached during cache export. Docker's docs attribute this to GitHub cache API rate limiting when many lookups happen at once. Reduce parallel jobs sharing a cache, or move that image to type=registry.
exec format error in an arm64 RUN step. QEMU is not registered on the runner. Add docker/setup-qemu-action before buildx, or use a native ARM runner.
Where this breaks
This setup assumes one image per Dockerfile and a cache that fits in 10 GB. Monorepos building a dozen images will churn the Actions cache, and evictions make every build cold again; registry cache or a remote BuildKit builder is the better fit there. It also assumes public GitHub-hosted runners. On self-hosted runners with a persistent Docker daemon, the local layer cache survives between jobs and type=gha can be slower than doing nothing.
Questions people ask
Do I need a personal access token to push to GHCR from GitHub Actions?
No. The workflow's GITHUB_TOKEN can push to ghcr.io when the job declares permissions: packages: write. Log in with docker/login-action, using github.actor as the username and secrets.GITHUB_TOKEN as the password. If a push to an existing package is denied, add the repository under the package's Manage Actions access settings rather than reaching for a PAT.
Is a package pushed with GITHUB_TOKEN public or private?
A package created by a workflow using GITHUB_TOKEN inherits the visibility and permissions model of the repository where the workflow ran, per GitHub's docs, and the repository admins become its admins. A public repository therefore produces a public image. Change visibility in the package settings if you need something different.
Why is my build-push-action build not using the cache?
The first run always builds cold. After that, check that you set both cache-from and cache-to, that cache-to uses mode=max, and that each image has its own scope. Caches are also scoped by branch: a run can read its own branch and the default branch, but not a sibling feature branch.
The call we'd make
Start with the four official actions, GHCR via GITHUB_TOKEN, metadata-action for tags, and type=gha cache with mode=max and a per-image scope. Scope permissions to packages: write and nothing more. Add multi-arch only when you actually ship to ARM, and move to native runners or registry cache only when type=gha becomes the bottleneck. For dependency caching inside the runner rather than Docker layers, see caching dependencies in GitHub Actions.
Sources
Cite this article
Kiril Urbonas (2026). Build and Push Docker Images in GitHub Actions. DevOpsNess. Updated 2026-10-31. https://www.devopsness.com/blog/github-actions-docker-build-push
[Build and Push Docker Images in GitHub Actions](https://www.devopsness.com/blog/github-actions-docker-build-push) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)
More from DevOps
Explore more articles in this category
kaniko CVE-2026-105769: Lookalike ACR Hosts Get Your Azure Token. Rebuild on v1.25.20
A FROM line pointing at a host like x.azurecr.io.attacker.com is enough to make kaniko hand the build's Entra ID token to that host. Which kaniko forks and images are affected, how to find Azure identities in your build pods, and what to rotate.
Sign Container Images With Cosign: Keyless GitHub Actions Workflow, SBOM and In-Cluster Checks
One workflow that builds, signs keylessly with GitHub OIDC, attaches an SBOM and SLSA provenance, plus the Kyverno policy that refuses anything unsigned. Copy it, change three names, ship it.
GitLab CVE-2026-110264: A Second CVSS 10 RCE in Nine Days. Patch to 19.5.1
An unauthenticated regex-compiler RCE reaching back to GitLab 7.0, no workaround, and backports on older branches that fix only the critical bug. The exact version per branch and the commands to get there.
You might have missed
Evergreen posts worth revisiting.