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 namedghcr.io/<owner>/<name>:<tag>– all in lowercase. - In the workflow,
docker/login-actionlogs in with theGITHUB_TOKEN, a token that GitHub issues anew for every run. You don’t need a password. docker/metadata-actionderives tags and labels from Git,docker/build-push-actionbuilds 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 1setup-buildx-actionsets 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 -uExpected:
#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 -qpermissions:defines what theGITHUB_TOKENmay do. New repositories give it read permissions only.packages: writeallows the push to the registry. More on that on Day 9.type=ref,event=branchturns the branchmaininto the tagmain,type=shainto the tagsha-plus seven characters of the commit.steps.meta.outputs.labelssets OCI labels such asorg.opencontainers.image.source. Via this label, GitHub links the package to your repository.VERSIONbecomesmain– the first tag frommetadata-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 -uExpected (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/versionExpected:
main
Before that, Docker reports the pull and the ID of the new container.
docker rm -f notes-ghaSave 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 -qcache-to: type=gha,mode=maxstores 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=ghareads them on the next run.
The first run fills the cache. A second run with
workflow_dispatch:
gh workflow run image.ymlWith 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 --fillAfter a few seconds:
gh pr checks --watch | grep imageExpected (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/nullExpected:
[]
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: writecan overwrite every package. - Tags are mutable:
mainpoints to a different image tomorrow. Deployments reference the image by digest (@sha256:…) or by an immutable tag such assha-…or a version number (Day 7). - Cleaning up: GHCR deletes nothing on its own.
actions/delete-package-versionsor a policy keeps untagged versions in check. - Cache limits: The
ghacache shares the 10 GB per repository with all other caches. For large images,type=registrywith a cache tag of its own is often the better choice.