Skip to main content
Build and Push Docker Images in GitHub Actions

Build and Push Docker Images in GitHub Actions

KU
· Founder & Chief Editor
• 7 min read•Updated •72 views

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.

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-container driver. That unlocks cache export, multi-arch, and RUN --mount. Skip it and you get the default docker driver, 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 build and 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:

YAML
# .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:

YAML
# .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 a scope overwrite each other, so give each image in a repo its own scope=. The default scope is buildkit.
  • type=registry: pushes cache layers to a tag such as ghcr.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:

YAML
# .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

React
Share this post
Cite this article
Plain text

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

Markdown

[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)

KU

Kiril Urbonas

Founder & Chief Editor

586 articles
View all articles by Kiril Urbonas

You might have missed

Evergreen posts worth revisiting.