Docker Build & Push

~13 min · docker, ghcr, registry

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

The default container pipeline

The standard 'build a Docker image and push it to a registry' shape uses three actions: docker/setup-buildx-action (multi-platform support), docker/login-action (auth to the registry), docker/build-push-action (build + push with cache).

Where to push

ghcr.io (GitHub Container Registry) — best default. Auths via GITHUB_TOKEN; same permissions model.
Docker Hub — historical default; image rate limits on free tier.
ECR / Artifact Registry / ACR — when you're on AWS / GCP / Azure and want one bill.

Tag conventions worth using

:<sha-7> — every image traceable to a Git commit.
:v1.4.2 — release versions, on tag pushes only.
:latest — moving pointer; do not use in production manifests.
:edge — main branch tip; for staging.

Build cache

Use the GitHub Actions cache backend: cache-from: type=gha, cache-to: type=gha, mode=max. This gives layer caching across runs without configuring a separate registry cache.

Code

Build + push to GHCR with multi-arch + cache·yaml

name: docker
on:
  push:
    branches: [main]
    tags: ['v*.*.*']
  pull_request: {}

permissions:
  contents: read
  packages: write       # to push to ghcr.io
  id-token: write       # for OIDC if pushing to AWS too

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-qemu-action@v3
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/metadata-action@v5
        id: meta
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=sha,prefix=,format=short
      - uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          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

External links

Exercise

If you have a Dockerized service, wire its CI to push to ghcr.io with SHA + branch tags. Pull the image locally with docker pull ghcr.io/<org>/<repo>:<sha> and verify it runs.