Tag 4: Lint und Rulesets
Ziel: golangci-lint als eigenen Job einbauen, mit einem Ruleset festlegen, dass nichts ohne grüne Checks auf
mainlandet, und erleben, wie GitHub einen Merge verweigert. · Dauer: ca. 60 min · Voraussetzung: Tag 3
Briefing
- golangci-lint bündelt Dutzende Go-Linter. Die offizielle Action installiert ihn, nutzt einen Cache und schreibt Fundstellen als Annotationen in den Lauf.
- Ein Ruleset schützt Branches: nur per Pull-Request, nur mit grünen Required Checks, kein Force-Push, nicht löschen. Rulesets lösen die älteren „Branch protection rules“ ab.
- Ein Required Check heißt wie der Job im Lauf, z. B.
lintodertest (ubuntu-24.04).
PR ──► ci: test (x2), lint ──► Ruleset: alle grün? ──ja──► Merge erlaubt
└─nein─► Merge gesperrt
Drill 1: golangci-lint
Erst die Konfiguration, im Format von golangci-lint 2:
cd ~/gha-lab/notes-actions
cat > .golangci.yml <<'EOF'
version: "2"
linters:
enable:
- misspell
EOF- Ohne weitere Angabe laufen die Standard-Linter:
errcheck,govet,ineffassign,staticcheckundunused. misspellfindet falsch geschriebene englische Wörter in Kommentaren und Texten.
Dann der Job, angehängt an ci.yml:
cat >> .github/workflows/ci.yml <<'EOF'
lint:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7
- uses: actions/setup-go@v7
with:
go-version-file: go.mod
- uses: golangci/golangci-lint-action@v9
with:
version: v2.15.0
EOF
git add .golangci.yml
git commit -qam "ci: golangci-lint"
git push -q
gh run list --limit 1version: pinnt golangci-lint selbst. Ohne Angabe nimmt
die Action die neueste Version – und ein neuer Linter kann über Nacht
einen roten Lauf auslösen.
Mit der ID, sobald der Lauf fertig ist:
gh run view <ID> --log-failed | grep -E 'Z \* [a-z]+: 'Erwartet (Zeitstempel gekürzt):
lint Run golangci/golangci-lint-action@v9 2026-11-03T09:45:34Z * errcheck: 11
lint Run golangci/golangci-lint-action@v9 2026-11-03T09:45:34Z * staticcheck: 3
Rot – so geht es fast jedem, der Lint auf bestehenden Code loslässt. Die Funde im Einzelnen:
gh run view <ID> --log-failed | grep -o '##\[error\].*' | head -3Erwartet:
##[error]main.go:124:16: Error return value of `db.Close` is not checked (errcheck)
##[error]main.go:169:17: Error return value of `db.Close` is not checked (errcheck)
##[error]main.go:217:15: Error return value of `fmt.Fprintln` is not checked (errcheck)
errcheckbemängelt ungeprüfte Fehler vonClose()undFprintln(). Bei diesen Aufrufen ignorieren Go-Projekte den Fehler üblicherweise bewusst.staticcheckmeldet dreimalST1005: error strings should not be capitalized. Die Regel stammt aus dem Englischen – deutsche Fehlermeldungen wie „Token abgelaufen“ beginnen nun mal groß.
Beides ist eine Entscheidung des Teams, und sie gehört in die Konfiguration, nicht in hundert Kommentare im Code:
cat > .golangci.yml <<'EOF'
version: "2"
linters:
enable:
- misspell
exclusions:
presets:
- std-error-handling
rules:
- linters: [staticcheck]
text: "ST1005"
EOF
git commit -qam "lint: Ausnahmen für Close/Print und deutsche Fehlermeldungen"
git push -qstd-error-handlingist eine fertige Ausnahmeliste fürClose,Flush,Print…und Co.- Die Regel unter
rules:schaltet genau eine Prüfung eines Linters ab.
Mit der neuen ID, sobald der Lauf fertig ist:
gh run view <ID> --log | grep -E 'lint.*Z 0 issues'Erwartet (Zeitstempel gekürzt):
lint Run golangci/golangci-lint-action@v9 2026-11-03T09:55:20Z 0 issues.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Das Ruleset
Ein Ruleset legst du im Browser an (Settings → Rules → Rulesets) oder per API. Die Regeln als JSON:
cat > ~/gha-lab/ruleset-main.json <<'EOF'
{
"name": "main schützen",
"target": "branch",
"enforcement": "active",
"conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
"bypass_actors": [
{ "actor_type": "RepositoryRole", "actor_id": 5, "bypass_mode": "always" }
],
"rules": [
{ "type": "deletion" },
{ "type": "non_fast_forward" },
{ "type": "pull_request",
"parameters": { "required_approving_review_count": 0,
"dismiss_stale_reviews_on_push": false,
"require_code_owner_review": false,
"require_last_push_approval": false,
"required_review_thread_resolution": false } },
{ "type": "required_status_checks",
"parameters": { "strict_required_status_checks_policy": false,
"required_status_checks": [
{ "context": "test (ubuntu-24.04)" },
{ "context": "test (ubuntu-24.04-arm)" },
{ "context": "lint" } ] } }
]
}
EOF~DEFAULT_BRANCHmeint den Default-Branch, alsomain.deletionundnon_fast_forward:maindarf weder gelöscht noch per Force-Push überschrieben werden.pull_requestmit 0 Reviews: Jede Änderung braucht einen Pull-Request, aber keine Freigabe – allein im Repository gibt es niemanden, der freigeben könnte.required_status_checks: Diese drei Jobs müssen grün sein.bypass_actors: Die Rolle 5 ist „Admin“. Als Besitzer darfst du die Regeln umgehen – das brauchst du, damit du in den nächsten Tagen weiter direkt aufmainpushen kannst. Was dabei passiert, zeigt Drill 4.
gh api -X POST repos/{owner}/{repo}/rulesets --input ~/gha-lab/ruleset-main.json \
--jq '.name, .enforcement'Erwartet:
main schützen
active
gh ruleset check mainErwartet (gekürzt):
6 rules apply to branch main in repo <du>/notes-actions
- deletion: [ruleset: main schützen]
- non_fast_forward: [ruleset: main schützen]
- pull_request: [ruleset: main schützen] ...
- required_status_checks: [ruleset: main schützen] ...
Fortschritt speichern? Kostenlos registrieren
Drill 3: Ein Merge, der nicht geht
Ein Pull-Request mit einem Tippfehler im Kommentar:
git switch -c tippfehler
cat > doc.go <<'EOF'
// Package main is notes-api. Notes are recieved via POST /notes.
package main
EOF
git add doc.go
git commit -qm "Paketdoku"
git push -q -u origin tippfehler
gh pr create --fillNach ein paar Sekunden:
gh pr checks --watchErwartet (am Ende, gekürzt):
Some checks were not successful
0 cancelled, 1 failing, 5 successful, 0 skipped, and 0 pending checks
NAME DESCRIPTION ELAPSED URL
X ci/lint (pull_request) 15s https://github.com/<du>/...
✓ ci/build (amd64) (pull_r... 34s https://github.com/<du>/...
✓ ci/build (arm64) (pull_r... 26s https://github.com/<du>/...
✓ ci/smoke (pull_request) 10s https://github.com/<du>/...
✓ ci/test (ubuntu-24.04) (... 17s https://github.com/<du>/...
✓ ci/test (ubuntu-24.04-ar... 15s https://github.com/<du>/...
build und smoke laufen auch, sind aber
keine Required Checks – das Ruleset verlangt nur test und
lint.
Die Fundstelle:
gh run view <ID> --log-failed | grep misspellErwartet (gekürzt):
... ##[error]doc.go:1:41: `recieved` is a misspelling of `received` (misspell)
Trotzdem zusammenführen?
gh pr merge --squashErwartet:
X Pull request <du>/notes-actions#3 is not mergeable: the base branch policy prohib...
To have the pull request merged after all the requirements have been met, add the `...
To use administrator privileges to immediately merge the pull request, add the `--a...
Ausgeschrieben: the base branch policy prohibits the merge –
die Regeln für main verbieten den Merge.
--auto würde automatisch mergen, sobald alles grün ist;
--admin setzt sich über die Regeln hinweg.
Das Ruleset greift. Mit --admin ginge es – genau dafür
steht die Ausnahme im Ruleset. Besser: den Fehler beheben.
sed -i 's/recieved/received/' doc.go
git commit -qam "Tippfehler"
git push -qNach ein paar Sekunden:
gh pr checks --watch >/dev/null; echo "Exit: $?"
gh pr merge --squash --delete-branchErwartet (gekürzt):
Exit: 0
✓ Squashed and merged pull request <du>/notes-actions#3 (Paketdoku)
...
create mode 100644 doc.go
✓ Deleted local branch tippfehler and switched to branch main
✓ Deleted remote branch tippfehler
Nach git push sieht gh pr checks ein paar
Sekunden lang noch den alten, roten Stand. Endet es zu früh mit
Exit: 1, starte es einfach noch einmal.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Direkt auf main – mit Ausnahme
echo 0.5.1 > VERSION
git commit -qam "VERSION 0.5.1"
git pushErwartet (gekürzt):
remote: Bypassed rule violations for refs/heads/main:
remote:
remote: - Changes must be made through a pull request.
remote:
remote: - 3 of 3 required status checks are expected.
...
GitHub lässt den Push durch, weil du Admin bist – und sagt dir genau,
welche Regeln du umgangen hast. Ohne Ausnahme stünde dort
GH013: Repository rule violations found, und der Push wäre
abgelehnt.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
gh ruleset listErwartet (ID weicht ab):
Showing 1 of 1 rulesets in <du>/notes-actions and its parents
ID NAME SOURCE STATUS RULES
26438562 main schützen <du>/notes-actions (repo) active 4
gh pr view 3 --json state,mergedAt --jq .stateErwartet:
MERGED
Challenge
golangci-lint 2 prüft auch die Formatierung. Schalte den Formatter
gofmt ein und zeige mit einem Pull-Request, dass eine
falsch eingerückte Datei den Merge blockiert. Behebe es mit
gofmt -w.
Hinweis: Der Abschnitt heißt
formatters: mit enable:. Go hast du auf der VM
nicht –
docker run --rm -v "$PWD":/src -w /src golang:1.27-alpine gofmt -w .
übernimmt das.
Lösung
git switch -c gofmt
cat > .golangci.yml <<'EOF'
version: "2"
linters:
enable:
- misspell
exclusions:
presets:
- std-error-handling
rules:
- linters: [staticcheck]
text: "ST1005"
formatters:
enable:
- gofmt
EOF
cat > doc.go <<'EOF'
// Package main is notes-api. Notes are received via POST /notes.
package main
EOF
git commit -qam "lint: gofmt"
git push -q -u origin gofmt
gh pr create --fillpackage main mit drei Leerzeichen ist gültiges Go,
aber nicht so formatiert, wie gofmt es will.
Nach ein paar Sekunden:
gh pr checks --watch >/dev/null; echo "Exit: $?"Erwartet:
Exit: 1
Mit der ID des roten Laufs aus
gh run list --limit 1:
gh run view <ID> --log-failed | grep gofmtErwartet (gekürzt):
... ##[error]doc.go:2:1: File is not properly formatted (gofmt)
docker run --rm -u "$(id -u)" -v "$PWD":/src -w /src golang:1.27-alpine gofmt -w .
git diff --stat
git commit -qam "gofmt"
git push -qErwartet:
doc.go | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
Nach ein paar Sekunden:
gh pr checks --watch >/dev/null; echo "Exit: $?"
gh pr merge --squash --delete-branchErwartet (gekürzt):
Exit: 0
✓ Squashed and merged pull request <du>/notes-actions#4 (lint: gofmt)
...
-u "$(id -u)" lässt den Container als dein Benutzer
schreiben – sonst gehörte die geänderte Datei root.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Rulesets auf Organisationsebene: Ein Ruleset in der
Organisation gilt für viele Repositorys auf einmal, z. B. „jedes
Repository mit Topic
prod“. Teams können die Regeln nicht abschalten, nur Admins der Organisation. - Reviews: Im Team gehört
required_approving_review_count: 1(oder mehr) dazu, plusCODEOWNERSfür Pfade, die bestimmte Teams freigeben müssen. - Merge Queue: Bei vielen Pull-Requests pro Tag
testet eine Merge Queue jeden Kandidaten gegen den neuesten Stand von
main, bevor er landet. Workflows brauchen dafür den Triggermerge_group. - Bypass sparsam: Jede Umgehung steht im Audit-Log (Insights → Rule Insights). In Produktion haben meist nur wenige Notfallkonten eine Ausnahme.