Skip to content
Hands-on IT IT Drills

Day 6: Building Images and Pushing to GHCR

Goal: Use Buildx to build an image of notes-api for amd64 and arm64, push it to the GitHub Container Registry with sensible tags, use GitHub’s build cache and start the image on the VM. · Duration: approx. 75 min · Prerequisite: Day 5

Briefing

  • GHCR (ghcr.io) is GitHub’s container registry. Images are named ghcr.io/<owner>/<name>:<tag> – all in lowercase.
  • In the workflow, docker/login-action logs in with the GITHUB_TOKEN, a token that GitHub issues anew for every run. You don’t need a password.
  • docker/metadata-action derives tags and labels from Git, docker/build-push-action builds with Buildx and pushes the result.
  • The Dockerfile of notes-api compiles Go itself for the target architecture (--platform=$BUILDPLATFORM). That is why no QEMU is needed.
 push main ─► image.yml: checkout ─► buildx ─► login ghcr ─► metadata ─► build+push
                                                                         │
                         ghcr.io/<du>/notes-api:main, :sha-1a2b3c4 ◄──────┘
                         (amd64 + arm64, one tag for both)

Drill 1: Building without pushing

cd ~/gha-lab/notes-actions
cat > .github/workflows/image.yml <<'EOF'
name: image
on:
  push:
    branches: [main]
    paths-ignore: ['**.md']
  workflow_dispatch:

jobs:
  image:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v7
      - uses: docker/setup-buildx-action@v4
      - uses: docker/build-push-action@v7
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: false
EOF
git add .github
git commit -qm "image: bauen"
git push -q
gh run list --workflow image.yml --limit 1
  • setup-buildx-action sets up a Buildx builder that can build several platforms at once.
  • context: . takes the files from the checkout. Without it, the action builds directly from the Git repository and ignores local changes made by earlier steps.
  • push: false: build only. This is how you check whether the Dockerfile builds.

With the ID, as soon as the run is finished:

gh run view <ID> --log | grep -oE '#[0-9]+ \[[^]]*build 1/1\]' | sort -u

Expected:

#14 [linux/amd64->arm64 build 1/1]
#15 [linux/amd64 build 1/1]

The build stage runs twice, once per target platform. linux/amd64->arm64 means: built on amd64, for arm64. grep -o prints only the matching part of the line, sort -u removes duplicate lines – Buildx reports every step when it starts and when it ends.

Save your progress? Sign up for free

Drill 2: Pushing to GHCR

cat > .github/workflows/image.yml <<'EOF'
name: image
on:
  push:
    branches: [main]
    paths-ignore: ['**.md']
  workflow_dispatch:

permissions:
  contents: read
  packages: write

jobs:
  image:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v7
      - uses: docker/setup-buildx-action@v4
      - uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: meta
        uses: docker/metadata-action@v6
        with:
          images: ghcr.io/${{ github.repository_owner }}/notes-api
          tags: |
            type=ref,event=branch
            type=sha
      - uses: docker/build-push-action@v7
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          build-args: |
            VERSION=${{ steps.meta.outputs.version }}
            REVISION=${{ github.sha }}
EOF
git commit -qam "image: nach GHCR"
git push -q
  • permissions: defines what the GITHUB_TOKEN may do. New repositories give it read permissions only. packages: write allows the push to the registry. More on that on Day 9.
  • type=ref,event=branch turns the branch main into the tag main, type=sha into the tag sha- plus seven characters of the commit.
  • steps.meta.outputs.labels sets OCI labels such as org.opencontainers.image.source. Via this label, GitHub links the package to your repository.
  • VERSION becomes main – the first tag from metadata-action. On Day 7 it turns into a real version number.

With the ID from gh run list --workflow image.yml --limit 1, as soon as the run is finished:

gh run view <ID> --log | grep -oE 'pushing manifest for [^@]+' | sort -u

Expected (the commit differs):

pushing manifest for ghcr.io/<du>/notes-api:main
pushing manifest for ghcr.io/<du>/notes-api:sha-57b78f0

Two tags, one image. The package in GitHub:

gh api /user/packages/container/notes-api \
  --jq '.name, .visibility, .repository.full_name'

Expected:

notes-api
public
<du>/notes-actions

The package is public: a package that a workflow creates with the GITHUB_TOKEN is linked to its repository and inherits its visibility. Packages from private repositories stay private.

Save your progress? Sign up for free

Drill 3: The image on the VM

Docker pulls a public image without logging in:

docker buildx imagetools inspect ghcr.io/<du>/notes-api:main | grep -E 'Platform'

Expected:

  Platform:    linux/amd64
  Platform:    linux/arm64
  Platform:    unknown/unknown
  Platform:    unknown/unknown

One tag, two images. The two unknown/unknown entries are the attestations that Buildx attaches on its own (provenance – more on Day 8).

docker run -d --name notes-gha -p 8091:8080 -e NOTES_API_KEY=lab-api-key-123 \
  ghcr.io/<du>/notes-api:main
curl -s localhost:8091/version

Expected:

main

Before that, Docker reports the pull and the ID of the new container.

docker rm -f notes-gha

Save your progress? Sign up for free

Drill 4: The build cache

So far every run builds from scratch: go mod download and go build for two platforms. Buildx can store its cache in the GitHub Actions cache. In image.yml, two lines are added to the last action:

cat > .github/workflows/image.yml <<'EOF'
name: image
on:
  push:
    branches: [main]
    paths-ignore: ['**.md']
  workflow_dispatch:

permissions:
  contents: read
  packages: write

jobs:
  image:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v7
      - uses: docker/setup-buildx-action@v4
      - uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: meta
        uses: docker/metadata-action@v6
        with:
          images: ghcr.io/${{ github.repository_owner }}/notes-api
          tags: |
            type=ref,event=branch
            type=sha
      - uses: docker/build-push-action@v7
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          build-args: |
            VERSION=${{ steps.meta.outputs.version }}
            REVISION=${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
EOF
git commit -qam "image: Build-Cache"
git push -q
  • cache-to: type=gha,mode=max stores the layers of all stages, not just those of the final image. Only then does the cache pay off for multi-stage builds.
  • cache-from: type=gha reads them on the next run.

The first run fills the cache. A second run with workflow_dispatch:

gh workflow run image.yml

With the ID, as soon as the run is finished:

gh run view <ID> --log | grep -c ' CACHED$'

Expected (the number may differ):

8
gh run list --workflow image.yml --limit 2 --json event,startedAt,updatedAt \
  --jq '.[] | .event + " " + .startedAt + " " + .updatedAt'

Expected (times differ):

workflow_dispatch 2026-11-03T10:18:32Z 2026-11-03T10:19:04Z
push 2026-11-03T10:15:52Z 2026-11-03T10:17:00Z

Start and end of each run: the run from the cache takes 32 seconds instead of 68.

Save your progress? Sign up for free

Checkpoint

docker buildx imagetools inspect ghcr.io/<du>/notes-api:main \
  --format '{{json .Manifest.MediaType}}'

Expected:

"application/vnd.oci.image.index.v1+json"

An index: a list that points to a separate image per platform.

gh api /user/packages/container/notes-api/versions --jq '.[0].metadata.container.tags'

Expected (the commit differs):

["sha-631ce39","main"]

Challenge

Pull requests should build the image too – so that a broken Dockerfile shows up before the merge – but not push anything to the registry.

Hint: The pull_request trigger, and push: of the build action can be an expression. docker/login-action needs an if:.

Solution

cat > .github/workflows/image.yml <<'EOF'
name: image
on:
  push:
    branches: [main]
    paths-ignore: ['**.md']
  pull_request:
  workflow_dispatch:

permissions:
  contents: read
  packages: write

jobs:
  image:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v7
      - uses: docker/setup-buildx-action@v4
      - if: github.event_name != 'pull_request'
        uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: meta
        uses: docker/metadata-action@v6
        with:
          images: ghcr.io/${{ github.repository_owner }}/notes-api
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=sha
      - uses: docker/build-push-action@v7
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          build-args: |
            VERSION=${{ steps.meta.outputs.version }}
            REVISION=${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
EOF
git switch -c image-pr
git commit -qam "image: auch in Pull-Requests bauen"
git push -q -u origin image-pr
gh pr create --fill

After a few seconds:

gh pr checks --watch | grep image

Expected (the last line, shortened):

✓  image/image (pull_request)                52s      https://github.com/<du>/...

--watch prints the table anew on every refresh; that is why grep shows several lines, first with *, at the end with ✓.

gh api /user/packages/container/notes-api/versions \
  --jq '[.[].metadata.container.tags[] | select(startswith("pr-"))]'
gh pr merge --squash --delete-branch >/dev/null

Expected:

[]

type=ref,event=pr would have created the tag pr- plus the number of the pull request – but it is not in the registry, because push is false in the pull request.

Save your progress? Sign up for free

Enterprise Note

  • Packages belong to the organization: In organizations you define which repositories may write to which package (Package settings → Manage Actions access). Otherwise every repository with packages: write can overwrite every package.
  • Tags are mutable: main points to a different image tomorrow. Deployments reference the image by digest (@sha256:…) or by an immutable tag such as sha-… or a version number (Day 7).
  • Cleaning up: GHCR deletes nothing on its own. actions/delete-package-versions or a policy keeps untagged versions in check.
  • Cache limits: The gha cache shares the 10 GB per repository with all other caches. For large images, type=registry with a cache tag of its own is often the better choice.