Build and Push Docker Images in GitHub Actions

To build and push a Docker image in GitHub Actions, run docker/setup-buildx-action, log in with docker/login-action, generate tags with docker/metadata-action, 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.

Building an image in CI is easy. Building it fast, tagging it sanely, and pushing it with the right permissions is where teams trip. Below is the standard stack the Docker org maintains, plus the choices that change your build times and your blast radius.

The standard stack

Almost every production pipeline uses the same four official actions, in this order (current majors as of October 2026):

• docker/setup-buildx-action@v4: boots a BuildKit builder. This is what unlocks caching, multi-arch, and the modern --mount build features. Without it you get the classic Docker builder, which is slower and can't do most of what follows.
• docker/login-action@v4: authenticates to your registry so the push succeeds.
• docker/metadata-action@v6: generates tags and OCI labels from Git context (branch, tag, SHA) so you don't hand-write tag logic.
• docker/build-push-action@v7: runs the actual buildx build and pushes.

You can shell out to docker build yourself, but you lose the metadata wiring and the cache exporters that make these actions worth using.

Authenticating to a registry

For GHCR (GitHub Container Registry), you don't need a personal access token or any stored secret. The workflow's built-in GITHUB_TOKEN works, as long as you grant it package write access:

- uses: docker/login-action@v4
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

For Docker Hub, store a Hub access token (not your password) as a secret and log in against the default registry:

- uses: docker/login-action@v4
  with:
    username: ${{ secrets.DOCKERHUB_USERNAME }}
    password: ${{ secrets.DOCKERHUB_TOKEN }}

For Amazon ECR, skip login-action and use aws-actions/amazon-ecr-login@v2 after aws-actions/configure-aws-credentials assumes an OIDC role, so there are no long-lived AWS keys in the repo. The job then needs id-token: write.

Tagging strategy

Hand-maintained tag logic rots. Let metadata-action derive tags from context:

- 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}}

That produces a sha-<shortsha> tag on every build (immutable, great for rollbacks and deploy pinning), a branch tag, clean semver tags when you push a v1.4.2 Git tag, and latest only on your default branch. Deploy from the SHA tag, not latest, so you always know exactly what's running.

Layer caching, and why it matters

A cold Docker build reinstalls every dependency layer from scratch. On a Node or Python image that's often the bulk of your build time. GitHub Actions runners are ephemeral, so the local layer cache is gone on every run unless you export it somewhere.

Two common backends:

• type=gha: stores layers in the GitHub Actions cache. Zero extra infrastructure, scoped per repo, 10 GB per repository by default (admins can raise it, and overage is billed). Entries unused for 7 days are evicted. Best default for most teams. If one repo builds several images, give each a distinct scope= so they don't overwrite each other's cache.
• Registry cache (type=registry): pushes cache layers to a registry tag (for example ghcr.io/org/app:buildcache). No size cap beyond your registry, shared across runners and even across repos, but you manage the extra tag.

Use mode=max to cache intermediate layers, not just the final stage. The difference on a warm cache is frequently the gap between a 6-minute build and a 45-second one.

A full build-push job with gha cache

name: build
on:
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:

permissions:
  contents: read
  packages: write

jobs:
  docker:
    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=semver,pattern={{version}}
            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
          cache-to: type=gha,mode=max

Two things worth noticing. First, permissions is scoped to exactly what this job needs: read the repo, write packages. No write-all, no admin. If a dependency or a compromised action tries to do anything else, it can't. Second, PRs still build (so you catch broken Dockerfiles) but never log in and never push. Building a fork PR with push access would leak your registry credentials, so this pattern is a security property, not just a convenience.

Multi-arch builds

If your image runs on both x86 servers and ARM (Graviton, Apple Silicon dev machines, Raspberry Pi), build a single multi-arch manifest. You need QEMU for cross-architecture emulation plus buildx to assemble the manifest list:

      - uses: docker/setup-qemu-action@v4

      - uses: docker/setup-buildx-action@v4

      - uses: docker/build-push-action@v7
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          platforms: linux/amd64,linux/arm64
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

buildx builds both platforms and pushes one tag that resolves to the right architecture at pull time. Be aware that emulated builds are slow: compiling native extensions under QEMU can take several times longer than native. If ARM build time hurts, move to native ARM runners and use a matrix that builds each arch on its own runner, then merge with docker buildx imagetools create. For most images, QEMU is fine to start.

Gotchas worth knowing

• push must be conditional. Gate it on github.event_name != 'pull_request' (or on branch/tag refs) so PRs validate without publishing.
• First cached build is a wash. The cache pays off from the second run on. Don't judge the setup by the cold build.
• GHCR visibility. A freshly pushed package is private. Link it to the repo and set visibility once in the package settings.
• Pin action versions. Major tags like @v7 are convenient; commit SHAs are safer for supply-chain hardening.

For dependency-level caching inside the runner (npm, pip, Go modules) rather than Docker layers, see caching dependencies in GitHub Actions.

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 as long as 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, grant the repository write access in the package's settings rather than reaching for a PAT.

How do I push to Amazon ECR instead of GHCR?

Swap the login step. Use aws-actions/configure-aws-credentials with role-to-assume and id-token: write permission, then aws-actions/amazon-ecr-login@v2, and point metadata-action at your ECR repository URI. docker/build-push-action itself does not change.

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 multiple images in one repo use separate scope values. Caches are also scoped by branch: a feature branch can read the default branch's cache but not another feature branch's.

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. Scope permissions to packages: write and nothing more. Add multi-arch only when you actually ship to ARM, and reach for native runners or registry cache only when type=gha becomes the bottleneck. That covers the vast majority of services without over-engineering the pipeline. For more patterns like this, see our GitHub Actions recipes.

Sources

• docker/build-push-action on GitHub
• Docker Docs: GitHub Actions cache backend (type=gha)
• GitHub Docs: Publishing a package with GitHub Actions
• GitHub Docs: Dependency caching limits and eviction