Docker with GitHub Actions

Workflow Anatomy

The standard pipeline chains four official actions:

- uses: actions/checkout@v4
- uses: docker/setup-buildx-action@v3
- uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v6
  with:
    context: .
    push: ${{ github.event_name != 'pull_request' }}
    cache-from: type=gha
    cache-to: type=gha,mode=max

Checkout supplies context, buildx creates the builder, login stores credentials in ~/.docker/config.json for the job, and build-push-action does the build. push conditioned on event type means pull requests verify the build without publishing.

Tags and Labels from Metadata

docker/metadata-action turns git context into tags and OCI labels:

- uses: docker/metadata-action@v5
  id: meta
  with:
    images: ghcr.io/${{ github.repository }}
    tags: |
      type=sha
      type=semver,pattern={{version}}
      type=ref,event=branch
- uses: docker/build-push-action@v6
  with:
    tags: ${{ steps.meta.outputs.tags }}
    labels: ${{ steps.meta.outputs.labels }}

One build therefore gets a branch tag, a short-SHA tag, and — on release — a version tag, while labels carry source and revision for later auditing. Enable flavor: latest=true on tags you want mirrored as latest.

Pitfalls and Interview Angles

Permissions. Pushing to GHCR needs packages: write in the job's permissions block; the default token is scoped, and a 403 on push almost always means a missing permission.

Fork PRs. Workflows from forks get a read-only token and no secrets — builds must run without pushing, which is exactly what the push: condition above does.

Token reach. GITHUB_TOKEN works inside one repository; pushing to a different repo or an external registry needs a PAT or registry user stored as a secret.

Interview: lay out the workflow, then explain how tags are derived, which event triggers a push, and how you would publish a multi-arch image from the same file.