Skip to content
Tutorials Center
My learning

Topics

Lesson 106 of 111 ยท Projects

Project: A Build and Release Pipeline

Build a complete Docker release pipeline: run tests in a build stage, tag by version and commit, smoke test, push to a registry, deploy and roll back by tag.

A release pipeline turns a commit into something running in production, and every step should be boring, repeatable and automatic. In this project you will build such a pipeline around Docker: test the code inside a container, build one small image, tag it with both a version and the commit it came from, smoke test it, push it to a registry, and deploy it, including how to roll back in seconds.

The twist is that you can run the whole thing on your own machine. A CI system such as GitHub Actions or GitLab CI is only a way to run the same shell commands on a clean computer when you push code. So we first write the pipeline as a plain script and run it against a local registry, then show the same steps as read-only CI YAML. Everything marked as a console session was run on Docker 29 with Compose v5 and buildx 0.37.

TEXT
 commit
   |
   v
 +------+   +-------+   +-------+   +------+   +----------+
 | test |-->| build |-->| smoke |-->| push |-->| deploy   |
 +------+   +-------+   +-------+   +------+   | (by tag) |
 go test    VERSION     run image,  registry    +----------+
 in a       COMMIT      curl                    compose up
 stage      tags        /healthz

The application

We reuse the tiny Go service from Project: A Tiny Go Image, slimmed down and made testable. The routes are built by a function (newMux) so tests can call it without starting a server.

TEXT
hello-api/
  go.mod
  main.go
  main_test.go
  Dockerfile
  .dockerignore
  compose.deploy.yaml
  ci.sh
Go
// main.go
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"os/signal"
	"syscall"
)

var (
	version = "dev"
	commit  = "unknown"
)

func newMux() *http.ServeMux {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "ok")
	})
	mux.HandleFunc("GET /version", func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		json.NewEncoder(w).Encode(map[string]string{"version": version, "commit": commit})
	})
	return mux
}

func main() {
	if len(os.Args) > 1 && os.Args[1] == "healthcheck" {
		resp, err := http.Get("http://127.0.0.1:8080/healthz")
		if err != nil || resp.StatusCode != 200 {
			os.Exit(1)
		}
		return
	}
	go func() {
		log.Printf("listening on :8080 (version %s, commit %s)", version, commit)
		log.Fatal(http.ListenAndServe(":8080", newMux()))
	}()
	stop := make(chan os.Signal, 1)
	signal.Notify(stop, syscall.SIGTERM, syscall.SIGINT)
	<-stop
	log.Println("shutting down")
}
Go
// main_test.go
package main

import (
	"net/http"
	"net/http/httptest"
	"strings"
	"testing"
)

func TestHealthz(t *testing.T) {
	rec := httptest.NewRecorder()
	newMux().ServeHTTP(rec, httptest.NewRequest("GET", "/healthz", nil))
	if rec.Code != http.StatusOK {
		t.Fatalf("status = %d, want 200", rec.Code)
	}
	if strings.TrimSpace(rec.Body.String()) != "ok" {
		t.Fatalf("body = %q, want ok", rec.Body.String())
	}
}

func TestVersionIsJSON(t *testing.T) {
	rec := httptest.NewRecorder()
	newMux().ServeHTTP(rec, httptest.NewRequest("GET", "/version", nil))
	if ct := rec.Header().Get("Content-Type"); ct != "application/json" {
		t.Fatalf("content type = %q", ct)
	}
	if !strings.Contains(rec.Body.String(), `"version"`) {
		t.Fatalf("body has no version: %s", rec.Body.String())
	}
}

func TestUnknownRouteIs404(t *testing.T) {
	rec := httptest.NewRecorder()
	newMux().ServeHTTP(rec, httptest.NewRequest("GET", "/nope", nil))
	if rec.Code != http.StatusNotFound {
		t.Fatalf("status = %d, want 404", rec.Code)
	}
}
TEXT
// go.mod
module hello-api

go 1.25

The Dockerfile: tests are a stage

The key idea is to give each pipeline step its own stage in one Dockerfile. A stage that only runs tests produces no files we need, but building it with --target test runs the tests, and a failed test fails the build.

DOCKERFILE
FROM golang:1.25-alpine AS base
WORKDIR /src
COPY go.mod ./
COPY *.go ./

FROM base AS test
RUN go vet ./... && go test -v ./...

FROM base AS build
ARG VERSION=dev
ARG COMMIT=unknown
RUN CGO_ENABLED=0 go build -trimpath \
    -ldflags "-s -w -X main.version=${VERSION} -X main.commit=${COMMIT}" \
    -o /out/app .

FROM gcr.io/distroless/static-debian12:nonroot AS final
ARG VERSION=dev
ARG COMMIT=unknown
LABEL org.opencontainers.image.title="hello-api" \
      org.opencontainers.image.version="${VERSION}" \
      org.opencontainers.image.revision="${COMMIT}"
COPY --from=build /out/app /app
EXPOSE 8080
HEALTHCHECK --interval=5s --timeout=3s CMD ["/app", "healthcheck"]
ENTRYPOINT ["/app"]

How the stages relate:

  • base copies the sources once; test and build both start from it.
  • test is not a dependency of final. A plain docker build . builds only the stages final needs (BuildKit skips the rest), so tests never slow down a normal build. The pipeline runs them explicitly with --target test. This also means a test failure can never produce a half-finished image that someone pushes by accident (Multi-Stage Builds).
  • VERSION and COMMIT are build arguments (ENV and ARG). They are baked into the binary with -X and into OCI labels so that any image can tell you where it came from (WORKDIR, USER, EXPOSE and LABEL). Note that ARG must be declared again in the final stage, because every stage starts with a clean slate.
  • The base is distroless static with its nonroot user (uid 65532): certificates, no shell, no root (Choosing a Base Image).

The .dockerignore keeps pipeline files out of the build context, so changing the script does not invalidate the cache:

TEXT
Dockerfile*
compose*.yaml
ci.sh
.git

Tests that fail stop the pipeline

Break the code on purpose (make /healthz print OK instead of ok) and run the test stage:

CONSOLE
$ docker build --target test --progress=plain .
...
#9 34.06 === RUN   TestHealthz
#9 34.06     main_test.go:17: body = "OK\n", want ok
#9 34.06 --- FAIL: TestHealthz (0.00s)
#9 34.06 === RUN   TestVersionIsJSON
#9 34.06 --- PASS: TestVersionIsJSON (0.00s)
#9 34.06 === RUN   TestUnknownRouteIs404
#9 34.06 --- PASS: TestUnknownRouteIs404 (0.00s)
#9 34.06 FAIL
#9 34.06 FAIL	hello-api	0.004s
#9 ERROR: process "/bin/sh -c go vet ./... && go test -v ./..." did not complete successfully: exit code: 1
...
ERROR: failed to build: failed to solve: process "/bin/sh -c go vet ./... && go test -v ./..." did not complete successfully: exit code: 1
$ echo $?
1

The command exits with code 1, so a script with set -e (or any CI system) stops right there. --progress=plain prints the output of every step; without it BuildKit's interactive display hides successful steps, and in CI logs you want to see everything. Fix the bug and the same command ends with ok hello-api 0.006s and exit code 0. (The first run takes ~30 seconds because the Go standard library compiles; later runs reuse the cache while the sources are unchanged.)

Running tests inside a build has two advantages over "run tests on the CI machine, then build an image". The tests run in the same environment the image is built from, and the CI machine needs nothing installed except Docker, so developers and CI behave identically (Dockerfile Best Practices).

A local registry to push to

A registry is just another container (Running a Private Registry). Docker treats 127.0.0.1 registries as safe without TLS, so this works out of the box:

CONSOLE
$ docker run -d --name registry -p 127.0.0.1:18156:5000 registry:2
$ curl -s http://127.0.0.1:18156/v2/
{}

An empty JSON object means "the registry API is alive".

The pipeline as a script

Terminal
#!/usr/bin/env bash
# ci.sh: a local stand-in for a CI job. Every step is a plain docker command.
set -euo pipefail

REGISTRY="${REGISTRY:-127.0.0.1:18156}"
IMAGE="$REGISTRY/tcd-b15-ci/hello"
VERSION="${VERSION:?set VERSION, e.g. 1.4.0}"
COMMIT="${COMMIT:?set COMMIT, e.g. the short git SHA}"

echo "==> 1/5 test"
docker build --target test --progress=plain .

echo "==> 2/5 build"
docker build \
  --build-arg VERSION="$VERSION" --build-arg COMMIT="$COMMIT" \
  -t "$IMAGE:$COMMIT" -t "$IMAGE:$VERSION" .

echo "==> 3/5 smoke test"
cid=$(docker run -d --rm --name ci-smoke -p 127.0.0.1:18158:8080 "$IMAGE:$COMMIT")
trap 'docker stop "$cid" >/dev/null 2>&1 || true' EXIT
for _ in $(seq 1 20); do
  curl -fsS http://127.0.0.1:18158/healthz >/dev/null 2>&1 && break
  sleep 0.5
done
curl -fsS http://127.0.0.1:18158/version
echo

echo "==> 4/5 push"
docker push "$IMAGE:$COMMIT"
docker push "$IMAGE:$VERSION"

echo "==> 5/5 done: $IMAGE:$COMMIT"

The script is short, but each line carries a practice worth knowing:

  • set -euo pipefail: stop at the first error, treat unset variables as errors, and fail a pipeline if any part fails. Without -e a failed test would be ignored and the script would push a broken image.
  • ${VERSION:?...} aborts with a message if a variable is missing, so you cannot publish an untagged release by forgetting an argument.
  • Two tags per build: the version (1.4.0, human-friendly, from your release process) and the commit (3f9c2ab, the exact source). In real CI the commit comes from git rev-parse --short=7 HEAD. See Tagging and Versioning Strategies for the reasoning.
  • A smoke test runs the image that was just built, the very thing that will ship, and checks that it starts and answers. The trap stops the container even if a check fails. --rm removes it afterwards (The Container Lifecycle).
  • Push last. Nothing reaches the registry unless every earlier step passed.

Run it for release 1.4.0. The test stage's output is long, so only the markers and the interesting lines are shown:

CONSOLE
$ VERSION=1.4.0 COMMIT=3f9c2ab ./ci.sh
==> 1/5 test
...
#9 22.41 PASS
#9 22.41 ok  	hello-api	0.006s
==> 2/5 build
...
#13 naming to 127.0.0.1:18156/tcd-b15-ci/hello:3f9c2ab done
#13 naming to 127.0.0.1:18156/tcd-b15-ci/hello:1.4.0 done
==> 3/5 smoke test
{"commit":"3f9c2ab","version":"1.4.0"}

==> 4/5 push
The push refers to repository [127.0.0.1:18156/tcd-b15-ci/hello]
990a9c434e5e: Pushed
a5789fc40e82: Pushed
...
1.4.0: digest: sha256:32e8e32d... size: 856
==> 5/5 done: 127.0.0.1:18156/tcd-b15-ci/hello:3f9c2ab

The smoke test printed the version and commit that the binary reports about itself, which proves the build arguments reached the program. Now release 1.4.1 from a new commit, then ask the registry what it holds:

CONSOLE
$ VERSION=1.4.1 COMMIT=9d1e0b4 ./ci.sh
...
==> 5/5 done: 127.0.0.1:18156/tcd-b15-ci/hello:9d1e0b4
$ curl -s http://127.0.0.1:18156/v2/tcd-b15-ci/hello/tags/list
{"name":"tcd-b15-ci/hello","tags":["1.4.1","9d1e0b4","1.4.0","3f9c2ab"]}
$ docker image inspect 127.0.0.1:18156/tcd-b15-ci/hello:1.4.1 --format '{{json .Config.Labels}}'
{"org.opencontainers.image.revision":"9d1e0b4","org.opencontainers.image.title":"hello-api","org.opencontainers.image.version":"1.4.1"}
$ docker image ls 127.0.0.1:18156/tcd-b15-ci/hello --format 'table {{.Tag}}\t{{.Size}}'
TAG       SIZE
1.4.1     15.1MB
9d1e0b4   15.1MB
1.4.0     15.1MB
3f9c2ab   15.1MB

Four tags, two images: the version and commit tags of one release point to the same image, so they cost no extra space (the registry stores each layer once). A year from now, docker image inspect on any running container's image tells you the exact commit through the label.

Deploying by tag

The "deployment" is a Compose file whose image tag comes from a variable:

YAML
# compose.deploy.yaml
name: tcd-b15-ci-deploy

services:
  app:
    image: 127.0.0.1:18156/tcd-b15-ci/hello:${IMAGE_TAG:?set IMAGE_TAG}
    ports:
      - "127.0.0.1:18157:8080"
    restart: unless-stopped

On the server (here: the same machine), the deploy step is pull, then up. To prove the images really come from the registry, delete the local copies first:

CONSOLE
$ docker rmi 127.0.0.1:18156/tcd-b15-ci/hello:{3f9c2ab,1.4.0,9d1e0b4,1.4.1}
$ IMAGE_TAG=3f9c2ab docker compose -f compose.deploy.yaml pull
 Image 127.0.0.1:18156/tcd-b15-ci/hello:3f9c2ab Pulled
$ IMAGE_TAG=3f9c2ab docker compose -f compose.deploy.yaml up -d --wait
 Container tcd-b15-ci-deploy-app-1 Started
 Container tcd-b15-ci-deploy-app-1 Waiting
 Container tcd-b15-ci-deploy-app-1 Healthy
$ curl -s http://127.0.0.1:18157/version
{"commit":"3f9c2ab","version":"1.4.0"}

--wait makes up return only when the container is healthy (the HEALTHCHECK from the Dockerfile), and exit non-zero if it never becomes healthy, which is exactly what a deploy step needs (Startup Order and Health). Now ship the new release:

CONSOLE
$ IMAGE_TAG=9d1e0b4 docker compose -f compose.deploy.yaml up -d --pull always --wait
 Container tcd-b15-ci-deploy-app-1 Starting
 Container tcd-b15-ci-deploy-app-1 Started
 Container tcd-b15-ci-deploy-app-1 Waiting
 Container tcd-b15-ci-deploy-app-1 Healthy
$ curl -s http://127.0.0.1:18157/version
{"commit":"9d1e0b4","version":"1.4.1"}

Suppose 1.4.1 turns out to be bad. A rollback is the same command with the previous tag, because the old image is still in the registry:

CONSOLE
$ IMAGE_TAG=3f9c2ab docker compose -f compose.deploy.yaml up -d --wait
$ curl -s http://127.0.0.1:18157/version
{"commit":"3f9c2ab","version":"1.4.0"}

This is the practical payoff of immutable, commit-addressed tags: deploy and rollback are the same operation, with no rebuild. A mutable tag such as latest would give you no way to say "the previous one". Forgetting the variable is safe too, thanks to :?:

CONSOLE
$ docker compose -f compose.deploy.yaml ps
error while interpolating services.app.image: required variable IMAGE_TAG is missing a value: set IMAGE_TAG

Promoting an image without rebuilding

After testing a release in staging you often want to mark that exact image as stable or production. Do not rebuild; add a tag in the registry:

CONSOLE
$ docker buildx imagetools create -t 127.0.0.1:18156/tcd-b15-ci/hello:stable 127.0.0.1:18156/tcd-b15-ci/hello:1.4.1
$ curl -s http://127.0.0.1:18156/v2/tcd-b15-ci/hello/tags/list
{"name":"tcd-b15-ci/hello","tags":["1.4.1","9d1e0b4","1.4.0","3f9c2ab","stable"]}

The bytes the testers approved are the bytes that run in production. A rebuild could differ (new base image, new dependency versions) even from the same commit.

The same pipeline in GitHub Actions (read-only example)

On a real CI service the steps are the same, spread over a few ready-made actions. This file was written from knowledge and not executed here; check the current versions of each action before using it.

YAML
# .github/workflows/release.yml  (read-only example)
name: release

on:
  push:
    tags: ["v*"]

permissions:
  contents: read
  packages: write

jobs:
  release:
    runs-on: ubuntu-latest
    env:
      IMAGE: ghcr.io/${{ github.repository }}
    steps:
      - uses: actions/checkout@v4

      - uses: docker/setup-buildx-action@v3

      - name: Run the tests
        run: docker buildx build --target test --progress=plain .

      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Work out the tags
        id: meta
        run: |
          echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
          echo "commit=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          build-args: |
            VERSION=${{ steps.meta.outputs.version }}
            COMMIT=${{ steps.meta.outputs.commit }}
          tags: |
            ${{ env.IMAGE }}:${{ steps.meta.outputs.version }}
            ${{ env.IMAGE }}:${{ steps.meta.outputs.commit }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

What maps to what:

  • The first docker buildx build --target test is our step 1. Because the job fails on a non-zero exit code, a failing test stops the workflow before anything is pushed.
  • docker/login-action replaces docker login; the token is the workflow's own temporary GITHUB_TOKEN, never a password in the repository (Working with Registries).
  • The two tags: lines are our version and commit tags. The workflow runs when you push a git tag like v1.4.0.
  • cache-from/cache-to store BuildKit's layer cache in GitHub's cache service, so a clean CI machine does not start from zero each time (Docker in CI, Build Performance).
  • The smoke test from our script is omitted here for brevity. In a real workflow you would build with load: true first, run the container, and push only after it passes.

Steps worth adding (read-only)

Three more stages are common in production pipelines. None of them can run in this lesson, so treat them as sketches:

Terminal
# Scan the image for known vulnerabilities and fail on serious ones (read-only example)
trivy image --exit-code 1 --severity HIGH,CRITICAL "$IMAGE:$COMMIT"

# Deploy over SSH (read-only example): the server pulls and restarts by tag
ssh deploy@server "cd /srv/hello && IMAGE_TAG=$COMMIT docker compose pull && IMAGE_TAG=$COMMIT docker compose up -d --wait"

# Sign the pushed image by digest (read-only example)
cosign sign "$IMAGE@sha256:<digest>"

Scanning belongs before the push so a vulnerable image never reaches the registry; read Image Security and Scanning. Deploy credentials should be a restricted account that can only run the deploy command, never a general admin login (Deploying on a Single Host).

Clean up

CONSOLE
$ IMAGE_TAG=x docker compose -f compose.deploy.yaml down
 Network tcd-b15-ci-deploy_default Removed
$ docker rm -fv registry
$ docker rmi 127.0.0.1:18156/tcd-b15-ci/hello:{3f9c2ab,1.4.0,9d1e0b4,1.4.1,stable}

The -v in docker rm -fv also deletes the registry's anonymous data volume (the registry:2 image declares /var/lib/registry as a volume). If you want the pushed images to survive between sessions, start the registry with a named volume instead: -v registry-data:/var/lib/registry.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the Dockerfile make test a separate stage that final does not depend on?

    BuildKit only builds the stages the requested target needs. Keeping tests in their own stage means they run when the pipeline asks for them, and their non-zero exit code fails that build step.
  2. 2. What does docker build --target test return when a Go test fails?

    A failing RUN instruction fails the build with a non-zero exit code. That is what lets CI systems and set -e scripts stop the pipeline.
  3. 3. Why tag every image with both a version (1.4.0) and a commit (3f9c2ab)?

    Both tags point to the same image at no extra cost. Versions communicate releases; commit tags tell you precisely what is running.
  4. 4. How do you roll back to the previous release in this setup?

    Deploying is compose up with a tag. With immutable tags, going back is the same command with an older tag, and no rebuild is needed.
  5. 5. What is the advantage of docker buildx imagetools create -t repo:stable repo:1.4.1 over rebuilding the image as stable?

    Promotion is just a new name for an existing image in the registry. A rebuild could pick up a changed base image or dependency and produce something different.

Summary

  • Run tests in a dedicated Dockerfile stage with --target test; a failing test exits non-zero and stops the pipeline.
  • Pass VERSION and COMMIT as build arguments and store them in the binary and in OCI labels, so every image can say where it came from.
  • Tag each release twice: by version and by commit. Deploy by tag, and roll back by deploying an older tag.
  • Smoke test the image you are about to ship, and push only after every earlier step passed (set -euo pipefail).
  • Use docker compose up -d --wait as a deploy step: it fails when the healthcheck never passes.
  • Promote images by adding tags in the registry instead of rebuilding.
  • CI services such as GitHub Actions only run the same commands on a clean machine; add scanning, signing and a restricted deploy account in real pipelines.

Next: Docker Cheat Sheet