Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 14: Releases – urlcheck ausliefern

Ziel: urlcheck aus Tag 8 mit Version versehen, für vier Plattformen bauen, mit GoReleaser paketieren, als distroless-Image beschreiben und per GitHub Actions testen und veröffentlichen · Dauer: ca. 120 min · Voraussetzung: Tag 8, Tag 13

Briefing

  • Go baut für jedes Zielsystem vom Mac aus: GOOS/GOARCH setzen, CGO_ENABLED=0 – fertig.
  • Die Version kommt per -ldflags -X ins Binary; ohne sie liest das Programm die Git-Daten aus den Build-Infos.
  • GoReleaser macht aus einem Git-Tag Archive, Prüfsummen und ein GitHub-Release.
  • Das Image enthält nur das statische Binary auf distroless/static – keine Shell, kein Paketmanager, nonroot.
  • CI prüft jeden Push; ein Tag v* löst das Release aus.
git tag v0.1.0 --> CI: vet, test -race, lint --> goreleaser release
                                                   |-- 6 Archive, 3 OS x 2 CPU
                                                   |-- checksums.txt
                                                   '-- GitHub-Release
Dockerfile --> golang:alpine (build) --> distroless/static:nonroot (run)

Drill 1: Version ins 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"
)

// Setzt der Build per -ldflags "-X main.version=1.2.3 -X main.commit=abc1234".
var (
    version = "dev"
    commit  = ""
)

// versionString nimmt die ldflags-Werte, sonst die VCS-Daten, die go build
// automatisch einbettet, wenn im Git-Repo gebaut wird.
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 bekommt run das Flag. Nach der Zeile mit asJSON einfügen:

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

Und direkt nach 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

Erwartet:

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

Warum? -X main.version=... überschreibt beim Linken den Wert einer string-Variablen – sie muss eine Variable sein, keine Konstante. Ohne ldflags bleibt dev; go run bettet keine Git-Daten ein, daher unbekannt.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Cross-Compile

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

Erwartet:

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)

Warum? cut -d, -f1-2 kürzt die file-Ausgabe; vollständig steht bei den Linux-Binaries statically linked. CGO_ENABLED=0 erzwingt reines Go: statisch gelinkt, läuft auf jedem Linux ohne passende glibc. -s -w entfernt Symbol- und Debug-Tabellen (kleiner, aber pprof und Debugger sehen weniger), -trimpath entfernt deine lokalen Pfade aus dem Binary. go tool dist list zeigt alle über 40 Zielplattformen.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Git-Repo und Tag

GoReleaser arbeitet mit Git: Version = letzter Tag, Commit = HEAD. Die Remote-URL ist ein Platzhalter – check und Snapshot-Builds sprechen sie nicht an.

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

Erwartet (Commit-Hash variiert):

urlcheck dev (0db9958, go1.26.9)

Warum? go build bettet in einem Git-Repo automatisch vcs.revision, vcs.time und vcs.modified ein; versionString liest sie mit debug.ReadBuildInfo. Die Version bleibt dev, weil kein -X gesetzt ist – das übernimmt gleich GoReleaser.

Fortschritt speichern? Kostenlos registrieren

Drill 4: GoReleaser

Wie golangci-lint in Tag 0 läuft GoReleaser über einen Wrapper in fester Version:

cat > ~/go-lab/bin/goreleaser <<'EOF'
#!/usr/bin/env bash
# GoReleaser in fester Version – ohne globale Installation
exec go run github.com/goreleaser/goreleaser/[email protected] "$@"
EOF
chmod +x ~/go-lab/bin/goreleaser
cat > .goreleaser.yaml <<'EOF'
# GoReleaser-Konfiguration für urlcheck – prüfen mit: 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

Erwartet (der erste Aufruf baut ca. 2 Minuten):

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

Ein Snapshot baut alles lokal, ohne Tag-Pflicht und ohne Upload:

~/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

Erwartet (gekürzt):

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)

Warum v2.17.1 und nicht die neueste? Ab GoReleaser 2.18 verlangt das Modul Go 1.27 – ein fester Wrapper macht solche Abhängigkeiten sichtbar statt sie zu überraschen. mod_timestamp setzt die Dateizeiten auf den Commit-Zeitpunkt, damit Archive reproduzierbar werden.

Tipp: SBOM-Grundlage ohne Zusatzwerkzeug: go version -m dist/urlcheck_linux_amd64_v1/urlcheck listet Go-Version, alle Module und die Build-Einstellungen. Für SPDX/CycloneDX-Dateien ergänzt du in .goreleaser.yaml einen sboms:-Block (nutzt syft).

Fortschritt speichern? Kostenlos registrieren

Drill 5: Distroless-Image

cat > Dockerfile <<'EOF'
# Build-Stage: kompiliert ein statisches 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

# Laufzeit: nur das Binary, CA-Zertifikate und ein 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 .

Erwartet (gekürzt):

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

Warum? Die Build-Stage braucht Go, das Laufzeit-Image nur das Binary: distroless/static enthält CA-Zertifikate, Zeitzonen und einen nonroot-User (UID 65532) – sonst nichts. --check prüft das Dockerfile nur, gebaut wird nichts. Hast du hadolint, prüft hadolint Dockerfile zusätzlich Best Practices.

Achtung: Die Tags golang:1.26.9-alpine und static-debian13:nonroot können sich ändern. In Produktion pinnst du beide per Digest (@sha256:...) und lässt Renovate oder Dependabot aktualisieren.

Fortschritt speichern? Kostenlos registrieren

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 in fester Version – ohne globale 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

Erwartet:

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

Warum? actionlint prüft Syntax, Ausdrücke, Kontexte und Shell-Schnipsel, bevor GitHub es tut. permissions: contents: read als Default und write nur im Release-Job folgt dem Least-Privilege-Prinzip; das GITHUB_TOKEN stellt GitHub pro Lauf aus.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Das Tool ist fertig

Alles committen, neue Version taggen, den kompletten Release lokal durchspielen und das Linux-Archiv prüfen:

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

Erwartet (Hash, Zeiten und Netzergebnis variieren):

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

Mit einem echten GitHub-Repo statt der Platzhalter-Remote ist der Rest ein Befehl; der Release-Job aus Drill 6 läuft dann in GitHub:

git push origin main --tags

Erwartet (nicht live getestet, gekürzt, kann je nach Version abweichen):

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

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

#!/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'"

Erwartet:

✔ 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

Ein Auditor fragt: „Kann ich aus eurem Quellcode exakt dieses Binary nachbauen?” Zeige, dass zwei Builds aus verschiedenen Verzeichnissen bitgleich sind – und welches Flag dafür entscheidend ist.

Hinweis: Kopiere das Repo nach /tmp und vergleiche die SHA-256-Summen mit und ohne -trimpath.

Lösung

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

Erwartet (Hashes variieren):

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

Warum? Ohne -trimpath stehen absolute Pfade (/Users/..., /tmp/...) in den Debug- und Panic-Informationen. Mit -trimpath, gleicher Go-Version, gleichem Commit und gleichen ldflags baut Go bitgleich – auch auf einem anderen Rechner. GoReleaser setzt das über flags: [-trimpath] und mod_timestamp schon um.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Artefakte signieren (cosign, keyless über OIDC aus GitHub Actions) und Provenance nach SLSA erzeugen; Kunden prüfen Signatur und Prüfsumme vor dem Einsatz.
  • SBOM (SPDX oder CycloneDX) an jedes Release hängen und govulncheck ./... als CI-Schritt laufen lassen – findet nur Schwachstellen in tatsächlich aufgerufenem Code.
  • Actions per Commit-SHA statt Tag pinnen (actions/checkout@<sha> # v7), Basis-Images per Digest; Updates automatisiert per Renovate.
  • Air-Gap-Kunden bekommen Archive plus checksums.txt, Images als docker save-Tarball oder per oras in ihre Registry gespiegelt.
  • Regulierte Umgebungen: FIPS-Build mit GOFIPS140 und klare Versions-Policy (welche Go-Version, welcher Support-Zeitraum).