Skip to content
Hands-on IT IT Drills

Day 14: Releases – shipping urlcheck

Goal: Give urlcheck from Day 8 a version, build it for four platforms, package it with GoReleaser, describe it as a distroless image, and test and publish it via GitHub Actions · Duration: approx. 120 min · Prerequisite: Day 8, Day 13

Briefing

  • Go builds for any target system from your Mac: set GOOS/GOARCH, CGO_ENABLED=0 – done.
  • The version gets into the binary via -ldflags -X; without it, the program reads the Git data from the build info.
  • GoReleaser turns a Git tag into archives, checksums and a GitHub release.
  • The image contains only the static binary on distroless/static – no shell, no package manager, nonroot.
  • CI checks every push; a tag v* triggers the release.
git tag v0.1.0 --> CI: vet, test -race, lint --> goreleaser release
                                                   |-- 6 archives, 3 OS x 2 CPU
                                                   |-- checksums.txt
                                                   '-- GitHub release
Dockerfile --> golang:alpine (build) --> distroless/static:nonroot (run)

Drill 1: Version into the binary

cp -r ~/go-lab/tag08-urlcheck ~/go-lab/tag14-urlcheck
cd ~/go-lab/tag14-urlcheck
cat > cmd/urlcheck/version.go <<'EOF'
package main

import (
    "runtime"
    "runtime/debug"
)

// Set by the build via -ldflags "-X main.version=1.2.3 -X main.commit=abc1234".
var (
    version = "dev"
    commit  = ""
)

// versionString takes the ldflags values, otherwise the VCS data that go build
// embeds automatically when building inside a Git repo.
func versionString() string {
    c := commit
    if bi, ok := debug.ReadBuildInfo(); ok && c == "" {
        for _, s := range bi.Settings {
            if s.Key == "vcs.revision" && len(s.Value) >= 7 {
                c = s.Value[:7]
            }
        }
    }
    if c == "" {
        c = "unbekannt"
    }
    return version + " (" + c + ", " + runtime.Version() + ")"
}
EOF
cat > cmd/urlcheck/version_test.go <<'EOF'
package main

import (
    "bytes"
    "context"
    "strings"
    "testing"
)

func TestVersionFlag(t *testing.T) {
    var out bytes.Buffer
    code := run(context.Background(), []string{"-version"}, nil, &out, &out)
    if code != 0 || !strings.HasPrefix(out.String(), "urlcheck dev (") {
        t.Fatalf("exit %d, Ausgabe %q", code, out.String())
    }
}
EOF

In cmd/urlcheck/main.go, run gets the flag. Insert after the line with asJSON:

    asJSON := fl.Bool("json", false, "JSON-Ausgabe")
    showVersion := fl.Bool("version", false, "Version anzeigen")

And right after fl.Parse:

    if err := fl.Parse(args); err != nil {
        return 2
    }
    if *showVersion {
        fmt.Fprintln(stdout, "urlcheck", versionString())
        return 0
    }
go test -count=1 ./cmd/urlcheck
go run ./cmd/urlcheck -version

Expected:

ok      example.com/urlcheck/cmd/urlcheck   0.252s
urlcheck dev (unbekannt, go1.26.9)

Why? At link time, -X main.version=... overwrites the value of a string variable – it has to be a variable, not a constant. Without ldflags it stays dev; go run embeds no Git data, hence unbekannt (“unknown”).

Save your progress? Sign up for free

Drill 2: Cross-compiling

for p in linux/amd64 linux/arm64 darwin/arm64 windows/amd64; do
  os=${p%/*} arch=${p#*/} ext=""
  [ "$os" = windows ] && ext=.exe
  CGO_ENABLED=0 GOOS=$os GOARCH=$arch go build -trimpath \
    -ldflags "-s -w -X main.version=0.1.0 -X main.commit=lab1234" \
    -o "bin/urlcheck-$os-$arch$ext" ./cmd/urlcheck
done
ls -lh bin/ | awk 'NR > 1 {print $5, $9}'
file bin/* | cut -d, -f1-2
./bin/urlcheck-darwin-arm64 -version

Expected:

5,5M urlcheck-darwin-arm64
5,9M urlcheck-linux-amd64
5,4M urlcheck-linux-arm64
6,0M urlcheck-windows-amd64.exe
bin/urlcheck-darwin-arm64:      Mach-O 64-bit executable arm64
bin/urlcheck-linux-amd64:       ELF 64-bit LSB executable, x86-64
bin/urlcheck-linux-arm64:       ELF 64-bit LSB executable, ARM aarch64
bin/urlcheck-windows-amd64.exe: PE32+ executable (console) x86-64, for MS Windows
urlcheck 0.1.0 (lab1234, go1.26.9)

Why? cut -d, -f1-2 shortens the file output; in full, the Linux binaries say statically linked. CGO_ENABLED=0 forces pure Go: statically linked, runs on any Linux without a matching glibc. -s -w removes the symbol and debug tables (smaller, but pprof and debuggers see less), -trimpath removes your local paths from the binary. go tool dist list shows all of the more than 40 target platforms.

Save your progress? Sign up for free

Drill 3: Git repo and tag

GoReleaser works with Git: version = latest tag, commit = HEAD. The remote URL is a placeholder – check and snapshot builds don’t contact it.

cat > .gitignore <<'EOF'
dist/
bin/
EOF
git init -q && git add . && git commit -qm "urlcheck 0.1.0"
git tag v0.1.0
git remote add origin https://github.com/example/urlcheck.git
go build -o bin/urlcheck ./cmd/urlcheck && ./bin/urlcheck -version

Expected (commit hash varies):

urlcheck dev (0db9958, go1.26.9)

Why? Inside a Git repo, go build automatically embeds vcs.revision, vcs.time and vcs.modified; versionString reads them with debug.ReadBuildInfo. The version stays dev because no -X is set – GoReleaser takes care of that in a moment.

Save your progress? Sign up for free

Drill 4: GoReleaser

Like golangci-lint on Day 0, GoReleaser runs through a wrapper with a pinned version:

cat > ~/go-lab/bin/goreleaser <<'EOF'
#!/usr/bin/env bash
# GoReleaser at a pinned version – without a global installation
exec go run github.com/goreleaser/goreleaser/[email protected] "$@"
EOF
chmod +x ~/go-lab/bin/goreleaser
cat > .goreleaser.yaml <<'EOF'
# GoReleaser configuration for urlcheck – check with: goreleaser check
version: 2

before:
  hooks:
    - go mod tidy
    - go test ./...

builds:
  - id: urlcheck
    main: ./cmd/urlcheck
    binary: urlcheck
    env:
      - CGO_ENABLED=0
    goos: [linux, darwin, windows]
    goarch: [amd64, arm64]
    flags:
      - -trimpath
    ldflags:
      - -s -w -X main.version={{.Version}} -X main.commit={{.ShortCommit}}
    mod_timestamp: "{{ .CommitTimestamp }}" # reproduzierbare Builds

archives:
  - formats: [tar.gz]
    format_overrides:
      - goos: windows
        formats: [zip]

checksum:
  name_template: checksums.txt

changelog:
  sort: asc
  filters:
    exclude: ["^docs:", "^test:"]
EOF
~/go-lab/bin/goreleaser check

Expected (the first call takes about 2 minutes to build):

  • checking                                  path=.goreleaser.yaml
  • 1 configuration file(s) validated
  • thanks for using GoReleaser!

A snapshot builds everything locally, without requiring a tag and without uploading:

~/go-lab/bin/goreleaser release --snapshot --clean 2>&1 | grep -o 'release succeeded.*'
ls dist/*.tar.gz dist/*.zip dist/checksums.txt
./dist/urlcheck_darwin_arm64_v8.0/urlcheck -version

Expected (abbreviated):

release succeeded after 2s
dist/checksums.txt
dist/urlcheck_0.1.0-SNAPSHOT-0db9958_darwin_amd64.tar.gz
dist/urlcheck_0.1.0-SNAPSHOT-0db9958_darwin_arm64.tar.gz
dist/urlcheck_0.1.0-SNAPSHOT-0db9958_linux_amd64.tar.gz
dist/urlcheck_0.1.0-SNAPSHOT-0db9958_linux_arm64.tar.gz
dist/urlcheck_0.1.0-SNAPSHOT-0db9958_windows_amd64.zip
dist/urlcheck_0.1.0-SNAPSHOT-0db9958_windows_arm64.zip
urlcheck 0.1.0-SNAPSHOT-0db9958 (0db9958, go1.26.9)

Why v2.17.1 and not the latest? From GoReleaser 2.18 on, the module requires Go 1.27 – a pinned wrapper makes such dependencies visible instead of letting them catch you by surprise. mod_timestamp sets the file times to the commit time so that archives become reproducible.

Tip: An SBOM basis without extra tools: go version -m dist/urlcheck_linux_amd64_v1/urlcheck lists the Go version, all modules and the build settings. For SPDX/CycloneDX files, add an sboms: block to .goreleaser.yaml (uses syft).

Save your progress? Sign up for free

Drill 5: Distroless image

cat > Dockerfile <<'EOF'
# Build stage: compiles a static binary
FROM golang:1.26.9-alpine AS build
WORKDIR /src
COPY go.mod ./
RUN go mod download
COPY . .
ARG VERSION=dev
RUN CGO_ENABLED=0 go build -trimpath \
    -ldflags "-s -w -X main.version=${VERSION}" -o /out/urlcheck ./cmd/urlcheck

# Runtime: only the binary, CA certificates and a nonroot user
FROM gcr.io/distroless/static-debian13:nonroot
COPY --from=build /out/urlcheck /urlcheck
USER nonroot:nonroot
ENTRYPOINT ["/urlcheck"]
EOF
cat > .dockerignore <<'EOF'
dist/
.git/
EOF
docker build --check .

Expected (abbreviated):

#4 [internal] load .dockerignore
#4 transferring context: 52B done
#4 DONE 0.0s
Check complete, no warnings found.

Why? The build stage needs Go, the runtime image only the binary: distroless/static contains CA certificates, time zones and a nonroot user (UID 65532) – nothing else. --check only checks the Dockerfile; nothing is built. If you have hadolint, hadolint Dockerfile additionally checks best practices.

Warning: The tags golang:1.26.9-alpine and static-debian13:nonroot can change. In production you pin both by digest (@sha256:...) and let Renovate or Dependabot update them.

Save your progress? Sign up for free

Drill 6: GitHub Actions

mkdir -p .github/workflows
cat > .github/workflows/ci.yml <<'EOF'
name: ci
on:
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:

permissions:
  contents: read # Minimalrechte; der Release-Job erweitert sie

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v7
        with:
          go-version-file: go.mod
      - run: go vet ./...
      - run: go test -race -count=1 ./...
      - uses: golangci/golangci-lint-action@v9
        with:
          version: v2.14.0

  release:
    if: startsWith(github.ref, 'refs/tags/v')
    needs: test
    runs-on: ubuntu-latest
    permissions:
      contents: write # Release anlegen und Archive hochladen
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0 # GoReleaser braucht alle Tags für den Changelog
      - uses: actions/setup-go@v7
        with:
          go-version-file: go.mod
      - uses: goreleaser/goreleaser-action@v7
        with:
          version: "v2.17.1"
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
EOF
cat > ~/go-lab/bin/actionlint <<'EOF'
#!/usr/bin/env bash
# actionlint at a pinned version – without a global installation
exec go run github.com/rhysd/actionlint/cmd/[email protected] "$@"
EOF
chmod +x ~/go-lab/bin/actionlint
~/go-lab/bin/actionlint && echo "Workflow ok"
sed 's/secrets.GITHUB/secret.GITHUB/' .github/workflows/ci.yml > /tmp/kaputt.yml
~/go-lab/bin/actionlint /tmp/kaputt.yml | head -1 | cut -c1-80; rm /tmp/kaputt.yml

Expected:

Workflow ok
../../../../tmp/kaputt.yml:43:29: undefined variable "secret". available variabl
exit status 1

Why? actionlint checks syntax, expressions, contexts and shell snippets before GitHub does. permissions: contents: read as the default and write only in the release job follows the principle of least privilege; GitHub issues the GITHUB_TOKEN per run.

Save your progress? Sign up for free

Drill 7: The tool is done

Commit everything, tag a new version, run through the complete release locally and check the Linux archive:

git add . && git commit -qm "Release-Pipeline: GoReleaser, Dockerfile, CI"
git tag v0.2.0
~/go-lab/bin/goreleaser release --snapshot --clean 2>&1 | grep -o 'release succeeded.*'
tar -tzf dist/urlcheck_0.2.0-SNAPSHOT-*_linux_amd64.tar.gz
grep linux_amd64 dist/checksums.txt | cut -c1-16
./dist/urlcheck_darwin_arm64_v8.0/urlcheck -c 4 urls.txt | tail -1

Expected (hash, times and network result vary):

release succeeded after 1s
urlcheck
464be36be522c600
10 URLs, 3 fehlerhaft, 4 Worker, 966ms

With a real GitHub repo instead of the placeholder remote, the rest is one command; the release job from Drill 6 then runs on GitHub:

git push origin main --tags

Expected (not tested live, abbreviated, may differ depending on the version):

To github.com:DEIN-USER/urlcheck.git
 * [new branch]      main -> main
 * [new tag]         v0.1.0 -> v0.1.0
 * [new tag]         v0.2.0 -> v0.2.0

Save your progress? Sign up for free

Checkpoint

#!/usr/bin/env bash
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
cd ~/go-lab/tag14-urlcheck
check "gofmt sauber" "test -z \"\$(gofmt -l .)\""
check "go vet" "go vet ./..."
check "golangci-lint" "~/go-lab/bin/lint run ./..."
check "Tests mit -race" "go test -race -count=1 ./..."
check "GoReleaser-Konfig gültig" "~/go-lab/bin/goreleaser check"
check "Workflow gültig" "~/go-lab/bin/actionlint"
check "Dockerfile ohne Warnung" "docker build --check ."
check "Linux-Binary statisch" \
  "file dist/urlcheck_linux_amd64_v1/urlcheck | grep -q 'statically linked'"
check "Version eingebaut" \
  "./dist/urlcheck_darwin_arm64_v8.0/urlcheck -version | grep -q '^urlcheck 0.2.0'"

Expected:

✔ gofmt sauber
✔ go vet
✔ golangci-lint
✔ Tests mit -race
✔ GoReleaser-Konfig gültig
✔ Workflow gültig
✔ Dockerfile ohne Warnung
✔ Linux-Binary statisch
✔ Version eingebaut

Challenge

An auditor asks: “Can I rebuild exactly this binary from your source code?” Show that two builds from different directories are bit-for-bit identical – and which flag is decisive for that.

Hint: Copy the repo to /tmp and compare the SHA-256 sums with and without -trimpath.

Solution

rm -rf /tmp/urlcheck-kopie && cp -r . /tmp/urlcheck-kopie
b() { (cd "$1" && CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build $2 \
  -ldflags "-s -w -X main.version=0.2.0" -o /tmp/urlcheck-bin ./cmd/urlcheck) \
  && shasum -a 256 /tmp/urlcheck-bin | cut -c1-16; }
echo "mit -trimpath:  $(b . -trimpath) $(b /tmp/urlcheck-kopie -trimpath)"
echo "ohne -trimpath: $(b . '') $(b /tmp/urlcheck-kopie '')"
rm -rf /tmp/urlcheck-kopie /tmp/urlcheck-bin

Expected (hashes vary):

mit -trimpath:  e55d97ca8fe64009 e55d97ca8fe64009
ohne -trimpath: 477b456e02401b38 753a100b79552628

Why? Without -trimpath, absolute paths (/Users/..., /tmp/...) end up in the debug and panic information. With -trimpath, the same Go version, the same commit and the same ldflags, Go builds bit-for-bit identical binaries – even on a different machine. GoReleaser already implements this via flags: [-trimpath] and mod_timestamp.

Save your progress? Sign up for free

Enterprise Note

  • Sign artifacts (cosign, keyless via OIDC from GitHub Actions) and generate SLSA provenance; customers verify the signature and checksum before deployment.
  • Attach an SBOM (SPDX or CycloneDX) to every release and run govulncheck ./... as a CI step – it only reports vulnerabilities in code that is actually called.
  • Pin actions by commit SHA instead of tag (actions/checkout@<sha> # v7), base images by digest; automate updates with Renovate.
  • Air-gapped customers get archives plus checksums.txt, and images as a docker save tarball or mirrored into their registry via oras.
  • Regulated environments: a FIPS build with GOFIPS140 and a clear version policy (which Go version, which support period).