Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 4: Lint und Rulesets

Ziel: golangci-lint als eigenen Job einbauen, mit einem Ruleset festlegen, dass nichts ohne grüne Checks auf main landet, 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. lint oder test (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, staticcheck und unused.
  • misspell findet 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 1

version: 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 -3

Erwartet:

##[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)
  • errcheck bemängelt ungeprüfte Fehler von Close() und Fprintln(). Bei diesen Aufrufen ignorieren Go-Projekte den Fehler üblicherweise bewusst.
  • staticcheck meldet dreimal ST1005: 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 -q
  • std-error-handling ist eine fertige Ausnahmeliste für Close, 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_BRANCH meint den Default-Branch, also main.
  • deletion und non_fast_forward: main darf weder gelöscht noch per Force-Push überschrieben werden.
  • pull_request mit 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 auf main pushen 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 main

Erwartet (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 --fill

Nach ein paar Sekunden:

gh pr checks --watch

Erwartet (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 misspell

Erwartet (gekürzt):

... ##[error]doc.go:1:41: `recieved` is a misspelling of `received` (misspell)

Trotzdem zusammenführen?

gh pr merge --squash

Erwartet:

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 -q

Nach ein paar Sekunden:

gh pr checks --watch >/dev/null; echo "Exit: $?"
gh pr merge --squash --delete-branch

Erwartet (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 push

Erwartet (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 list

Erwartet (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 .state

Erwartet:

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 --fill

package 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 gofmt

Erwartet (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 -q

Erwartet:

 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-branch

Erwartet (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, plus CODEOWNERS fü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 Trigger merge_group.
  • Bypass sparsam: Jede Umgehung steht im Audit-Log (Insights → Rule Insights). In Produktion haben meist nur wenige Notfallkonten eine Ausnahme.