Day 14: Releases – shipping urlcheck
Goal: Give
urlcheckfrom 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())
}
}
EOFIn 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 -versionExpected:
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 -versionExpected:
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 -versionExpected (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 checkExpected (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 -versionExpected (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/urlchecklists the Go version, all modules and the build settings. For SPDX/CycloneDX files, add ansboms:block to.goreleaser.yaml(usessyft).
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-alpineandstatic-debian13:nonrootcan 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.ymlExpected:
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 -1Expected (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 --tagsExpected (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-binExpected (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 adocker savetarball or mirrored into their registry viaoras. - Regulated environments: a FIPS build with
GOFIPS140and a clear version policy (which Go version, which support period).