Docker in CI/CD
Build, tag, and push Docker images to GHCR in GitHub Actions — with layer caching, multi-platform builds, and secure secrets
Skills taught: cicd.docker-build, cicd.ghcr, cicd.build-cache, cicd.multi-platform, cicd.build-secrets
Build and push to GitHub Container Registry
name: Build and Push Docker Image
on:
push:
branches: [main]
tags: ['v*'] # also build on version tags
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write # required to push to GHCR
steps:
- uses: actions/checkout@v4
# Set up BuildKit (Docker's modern build engine — faster, more features)
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
# Log in to GitHub Container Registry using GITHUB_TOKEN
# No secret setup needed — GITHUB_TOKEN works automatically
- name: Log in to GHCR
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
# Generate image tags:
# - ghcr.io/owner/repo:main (branch name)
# - ghcr.io/owner/repo:sha-abc1234 (commit SHA)
# - ghcr.io/owner/repo:v1.2.3 (semver tag)
# - ghcr.io/owner/repo:latest (only on tagged releases)
- name: Extract metadata
id: meta
uses: docker/metadata-action@v5
with:
images: ghcr.io/${{ github.repository }}
tags: |
type=ref,event=branch
type=sha,prefix=sha-,format=short
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=raw,value=latest,enable=${{ github.ref_type == 'tag' }}
# Build and push with GitHub Actions cache
- name: Build and push
uses: docker/build-push-action@v6
with:
context: .
# Only push on main/tags, not on PR builds
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
# GitHub Actions cache — reuse layers between runs
cache-from: type=gha
cache-to: type=gha,mode=max
Layer caching explained
Without caching, every CI run downloads base images and reinstalls all dependencies from scratch — a Node.js app might take 3-4 minutes. With type=gha (GitHub Actions cache), BuildKit stores each Dockerfile layer after the first run. Subsequent runs that hit the cache take 30 seconds. The cache key is the layer content hash — if you change package.json, only the npm install layer and everything after it is rebuilt.
Multi-platform builds
# Why: Apple Silicon Macs, AWS Graviton, Raspberry Pi all use ARM64
# Building multi-platform on GitHub's AMD64 runners uses QEMU emulation
- name: Set up QEMU
uses: docker/setup-qemu-action@v3
# QEMU allows running ARM64 code on AMD64 runners (slower but compatible)
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Build and push
uses: docker/build-push-action@v6
with:
context: .
platforms: linux/amd64,linux/arm64
push: true
tags: ghcr.io/myorg/myapp:latest
cache-from: type=gha
cache-to: type=gha,mode=max
# Creates a single image manifest that works on both architectures
# docker pull ghcr.io/myorg/myapp:latest → gets the right architecture automatically
Passing build secrets securely
- name: Build with secret
uses: docker/build-push-action@v6
with:
context: .
push: true
tags: ghcr.io/myorg/myapp:latest
secrets: |
npm_token=${{ secrets.NPM_TOKEN }}
github_token=${{ secrets.GITHUB_TOKEN }}
# In Dockerfile, use the secret without it being stored in layers:
# RUN --mount=type=secret,id=npm_token \
# npm config set //registry.npmjs.org/:_authToken=$(cat /run/secrets/npm_token) && \
# npm ci && \
# npm config delete //registry.npmjs.org/:_authToken
Tip: Don't push on pull request builds. The workflow uses push: ${{ github.event_name != 'pull_request' }}. On PRs, the image is built and verified (you catch Dockerfile errors) but not pushed to the registry. This prevents untrusted code from PRs writing to your image registry, and avoids polluting the registry with thousands of PR build images.
Frequently Asked Questions
Should I use Docker Hub or GHCR for my images?
GHCR (ghcr.io) is the better default for GitHub-hosted projects: it's free, uses GITHUB_TOKEN (no separate secret setup), is colocated with your source code, and has no rate limits on pulls from GitHub Actions runners. Use Docker Hub if you need images accessible to non-GitHub users, or if you have existing infrastructure that already pulls from Docker Hub.