Day 4: Lint and Rulesets
Goal: Add golangci-lint as a job of its own, use a ruleset to make sure that nothing lands on
mainwithout green checks, and experience GitHub refusing a merge. · Duration: approx. 60 min · Prerequisite: Day 3
Briefing
- golangci-lint bundles dozens of Go linters. The official action installs it, uses a cache and writes findings into the run as annotations.
- A ruleset protects branches: only via pull request, only with green required checks, no force push, no deletion. Rulesets replace the older “branch protection rules”.
- A required check is named like the job in the run,
e.g.
lintortest (ubuntu-24.04).
PR ──► ci: test (x2), lint ──► Ruleset: all green? ──yes─► merge allowed
└─no──► merge blocked
Drill 1: golangci-lint
First the configuration, in the format of golangci-lint 2:
cd ~/gha-lab/notes-actions
cat > .golangci.yml <<'EOF'
version: "2"
linters:
enable:
- misspell
EOF- Without further settings, the standard linters run:
errcheck,govet,ineffassign,staticcheckandunused. misspellfinds misspelled English words in comments and strings.
Then the job, appended to 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: pins golangci-lint itself. Without it, the
action takes the newest version – and a new linter can cause a red run
overnight.
With the ID, as soon as the run is finished:
gh run view <ID> --log-failed | grep -E 'Z \* [a-z]+: 'Expected (timestamps shortened):
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
Red – that happens to almost everyone who unleashes lint on existing code. The findings in detail:
gh run view <ID> --log-failed | grep -o '##\[error\].*' | head -3Expected:
##[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)
errcheckcomplains about unchecked errors fromClose()andFprintln(). For these calls, Go projects usually ignore the error on purpose.staticcheckreportsST1005: error strings should not be capitalizedthree times. The rule comes from English – German error messages such as “Token abgelaufen” simply start with a capital letter.
Both are a team decision, and it belongs in the configuration, not in a hundred comments in the 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-handlingis a ready-made exclusion list forClose,Flush,Print…and co.- The rule under
rules:turns off exactly one check of one linter.
With the new ID, as soon as the run is finished:
gh run view <ID> --log | grep -E 'lint.*Z 0 issues'Expected (timestamp shortened):
lint Run golangci/golangci-lint-action@v9 2026-11-03T09:55:20Z 0 issues.
Save your progress? Sign up for free
Drill 2: The ruleset
You create a ruleset in the browser (Settings → Rules → Rulesets) or via the API. The rules as 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_BRANCHmeans the default branch, i.e.main.deletionandnon_fast_forward:mainmay neither be deleted nor overwritten by force push.pull_requestwith 0 reviews: every change needs a pull request, but no approval – alone in the repository, there is nobody who could approve.required_status_checks: these three jobs must be green.bypass_actors: role 5 is “Admin”. As the owner you may bypass the rules – you need that so you can keep pushing directly tomainover the next days. Drill 4 shows what happens then.
gh api -X POST repos/{owner}/{repo}/rulesets --input ~/gha-lab/ruleset-main.json \
--jq '.name, .enforcement'Expected:
main schützen
active
gh ruleset check mainExpected (shortened):
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] ...
Save your progress? Sign up for free
Drill 3: A merge that doesn’t go through
A pull request with a typo in the comment:
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 --fillAfter a few seconds:
gh pr checks --watchExpected (at the end, shortened):
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 and smoke run too, but are not
required checks – the ruleset only requires test and
lint.
The finding:
gh run view <ID> --log-failed | grep misspellExpected (shortened):
... ##[error]doc.go:1:41: `recieved` is a misspelling of `received` (misspell)
Merge anyway?
gh pr merge --squashExpected:
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...
Spelled out: the base branch policy prohibits the merge –
the rules for main forbid the merge. --auto
would merge automatically as soon as everything is green;
--admin overrides the rules.
The ruleset takes effect. With --admin it would work –
that is exactly what the exception in the ruleset is for. Better: fix
the error.
sed -i 's/recieved/received/' doc.go
git commit -qam "Tippfehler"
git push -qAfter a few seconds:
gh pr checks --watch >/dev/null; echo "Exit: $?"
gh pr merge --squash --delete-branchExpected (shortened):
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
After git push, gh pr checks still sees the
old, red state for a few seconds. If it ends too early with
Exit: 1, simply start it again.
Save your progress? Sign up for free
Drill 4: Directly to main – with an exception
echo 0.5.1 > VERSION
git commit -qam "VERSION 0.5.1"
git pushExpected (shortened):
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 lets the push through because you are an admin – and tells you
exactly which rules you bypassed. Without the exception it would say
GH013: Repository rule violations found, and the push would
be rejected.
Save your progress? Sign up for free
Checkpoint
gh ruleset listExpected (ID differs):
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 .stateExpected:
MERGED
Challenge
golangci-lint 2 also checks formatting. Turn on the
gofmt formatter and show with a pull request that a badly
indented file blocks the merge. Fix it with gofmt -w.
Hint: The section is called formatters:
with enable:. You don’t have Go on the VM –
docker run --rm -v "$PWD":/src -w /src golang:1.27-alpine gofmt -w .
takes care of that.
Solution
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 with three spaces is valid Go, but not
formatted the way gofmt wants it.
After a few seconds:
gh pr checks --watch >/dev/null; echo "Exit: $?"Expected:
Exit: 1
With the ID of the red run from
gh run list --limit 1:
gh run view <ID> --log-failed | grep gofmtExpected (shortened):
... ##[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 -qExpected:
doc.go | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
After a few seconds:
gh pr checks --watch >/dev/null; echo "Exit: $?"
gh pr merge --squash --delete-branchExpected (shortened):
Exit: 0
✓ Squashed and merged pull request <du>/notes-actions#4 (lint: gofmt)
...
-u "$(id -u)" makes the container write as your user –
otherwise the changed file would belong to root.
Save your progress? Sign up for free
Enterprise Note
- Rulesets at the organization level: A ruleset in
the organization applies to many repositories at once, e.g. “every
repository with the topic
prod”. Teams cannot turn the rules off, only organization admins can. - Reviews: In a team,
required_approving_review_count: 1(or more) is part of it, plusCODEOWNERSfor paths that specific teams must approve. - Merge queue: With many pull requests per day, a
merge queue tests every candidate against the latest state of
mainbefore it lands. Workflows need themerge_grouptrigger for that. - Bypass sparingly: Every bypass is recorded in the audit log (Insights → Rule Insights). In production, usually only a few emergency accounts have an exception.