Skip to content
Hands-on IT IT Drills

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 main without 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. lint or test (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, staticcheck and unused.
  • misspell finds 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 1

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

Expected:

##[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 complains about unchecked errors from Close() and Fprintln(). For these calls, Go projects usually ignore the error on purpose.
  • staticcheck reports ST1005: error strings should not be capitalized three 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 -q
  • std-error-handling is a ready-made exclusion list for Close, 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_BRANCH means the default branch, i.e. main.
  • deletion and non_fast_forward: main may neither be deleted nor overwritten by force push.
  • pull_request with 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 to main over 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 main

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

After a few seconds:

gh pr checks --watch

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

Expected (shortened):

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

Merge anyway?

gh pr merge --squash

Expected:

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

After a few seconds:

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

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

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

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

Expected:

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

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

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

Expected:

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

Expected (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, plus CODEOWNERS for 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 main before it lands. Workflows need the merge_group trigger 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.