Docker Impl Cicd

docker-impl-cicd

Quick Reference

GitHub Actions Docker Toolkit

Registry Authentication Comparison

Cache Strategy Decision Tree

Is this a GitHub Actions workflow?
├── YES → Use type=gha (fastest, no registry auth needed)
│   └── ALWAYS set mode=max for full intermediate layer caching
├── NO → Is a container registry available?
│   ├── YES → Use type=registry with a dedicated cache tag
│   │   └── ALWAYS use mode=max for CI builds
│   └── NO → Use type=local with mounted volume
└── Need to share cache across forks/PRs?
    └── Use type=registry (gha cache is scoped to branch)

Image Tagging Conventions

Critical Warnings

NEVER hardcode registry credentials in workflow files or Dockerfiles. ALWAYS use GitHub Secrets or OIDC for authentication.

NEVER use docker login with plaintext passwords in CI. ALWAYS use docker/login-action which handles credential storage securely.

NEVER push images without cache configuration in CI. Without --cache-from/--cache-to, every CI build starts from scratch, wasting minutes.

NEVER use type=gha cache with mode=min (the default). ALWAYS set mode=max to cache all intermediate layers, not just exported layers.

NEVER build multi-platform images with --load. Multi-platform manifests can only be pushed to a registry (--push) or exported to a file.

ALWAYS pin GitHub Action versions to major tags (e.g., @v3) at minimum. Pin to SHA for maximum security in production workflows.

Complete Build-and-Push Workflow

name: Build and Push Docker Image

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

permissions:
  contents: read
  packages: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to Docker Hub
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Log in to GHCR
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata (tags, labels)
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: |
            user/myapp
            ghcr.io/${{ github.repository }}
          tags: |
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=semver,pattern={{major}}
            type=ref,event=branch
            type=ref,event=pr
            type=sha,prefix=sha-

      - name: Build and push
        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

Multi-Platform Build Setup

Platform Support Matrix

Cross-Compilation Pattern (Faster than QEMU)

For compiled languages, cross-compile on the native platform instead of emulating:

# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:1.22 AS build
ARG TARGETOS TARGETARCH
WORKDIR /src
COPY go.* ./
RUN go mod download
COPY . .
RUN GOOS=$TARGETOS GOARCH=$TARGETARCH CGO_ENABLED=0 \
    go build -o /app ./cmd

FROM alpine:3.21
COPY --from=build /app /usr/bin/app
USER 1001
ENTRYPOINT ["/usr/bin/app"]

ALWAYS use --platform=$BUILDPLATFORM on the build stage and cross-compile with TARGETOS/TARGETARCH. This avoids QEMU emulation for the compilation step, reducing build time by 5-10x.

Cache Strategies in CI

GitHub Actions Cache (type=gha)

- uses: docker/build-push-action@v6
  with:
    cache-from: type=gha
    cache-to: type=gha,mode=max

• Uses GitHub Actions cache service (same as actions/cache).
• Scoped to the current branch; falls back to the default branch.
• 10 GB limit per repository. Old entries are evicted automatically.
• ALWAYS use mode=max to cache all intermediate layers.

Registry Cache (type=registry)

- uses: docker/build-push-action@v6
  with:
    cache-from: type=registry,ref=user/myapp:buildcache
    cache-to: type=registry,ref=user/myapp:buildcache,mode=max

• Stored as a separate image manifest in the registry.
• Shared across all branches, PRs, forks, and CI providers.
• Requires registry authentication.
• ALWAYS use a dedicated cache tag (e.g., :buildcache), not :latest.

Multi-Branch Cache Strategy

cache-from: |
  type=registry,ref=user/myapp:cache-${{ github.ref_name }}
  type=registry,ref=user/myapp:cache-main
cache-to: type=registry,ref=user/myapp:cache-${{ github.ref_name }},mode=max

This pattern caches per-branch with a fallback to main, ensuring feature branches benefit from the main branch cache.

Docker Scout in CI

- name: Docker Scout CVE scan
  uses: docker/scout-action@v1
  with:
    command: cves
    image: ${{ steps.meta.outputs.tags }}
    only-severities: critical,high
    exit-code: true

• exit-code: true fails the workflow if critical/high vulnerabilities are found.
• ALWAYS run Scout after building but before deploying to production.
• Use sarif output format for GitHub Security tab integration.

metadata-action Tag Types

Security Best Practices for CI/CD

Reference Links

• references/github-actions.md -- Complete GitHub Actions workflow examples for all registry types
• references/examples.md -- Multi-platform builds, registry auth, cache strategies
• references/anti-patterns.md -- CI/CD mistakes and how to avoid them

Official Sources

• https://docs.docker.com/build/ci/github-actions/
• https://github.com/docker/build-push-action
• https://github.com/docker/metadata-action
• https://github.com/docker/login-action
• https://github.com/docker/setup-buildx-action
• https://docs.docker.com/build/cache/backends/gha/
• https://docs.docker.com/build/building/multi-platform/
• https://docs.docker.com/scout/integrations/ci/gha/