task target, so task ci on your machine gives the same answer as CI.
Before you begin
- A Forge Go project in a git repository, such as the one from Add a database table with a CRUD API and pages.
- Forge v1.6.1 or later (
reliant forge --versioninside the project). - For the last step, the project pushed to a GitHub repository with Actions enabled.
1
See what the generated CI runs
reliant forge project new writes these workflows under .github/workflows/:The workflows are yours to edit.
reliant forge generate never rewrites one that exists. reliant forge ci gate --list prints the gate’s rows:terminal
2
Add forge lint to the gate
The gate’s lint rows are golangci-lint,
buf lint, the migration-safety lint and each frontend’s lint and typecheck. Forge’s own rules, such as tracing, conventions and write policy, are not in it. With a slog.Info call that drops the request context in a handler, reliant forge lint failed while reliant forge ci gate checks reported PASS — 13 passed. Add the whole sweep as an extra check:forge.yaml
task lint runs the forge version your project pins, on your machine and on the runner. A plain forge command fails under Reliant, where only reliant forge is on your PATH: exec: "forge": executable file not found in $PATH.3
Run the gate locally
terminal
tmp/ci/<lane>/<check>.log. Here, vuln-npm found a real high-severity advisory, which Scan dependencies for vulnerabilities fixes, and deployability is covered under Troubleshooting. A check that could not run is SKIPPED and fails the gate unless you name it in CI_SKIP=<check> (why). On a committed tree, a check that already passed on that exact tree reads PASS (cached <sha>).4
Read the lint verdict
The verdict is the last line of
reliant forge lint, so never pipe it through head. --quiet prints only the failing lanes and the verdict:terminal
reliant forge lint --tracing --fix rewrote the call to slog.InfoContext(ctx, "listing products"), and a clean run is one line: ✅ All 29 gating linters passed.When a forge release adds or tightens a rule, its findings are warnings until the release after, depending on the forge_version you pin. The verdict line counts them, so a green run tells you what a pin bump will turn red. See Lint rollout.5
Catch hand edits and stale generated code
reliant forge ci verify-generated regenerates a scratch copy of your tree and fails if anything differs. It first checks the hash every generated file carries. A hand edit to handlers_crud_ops_gen.go:reliant forge generate:verify-generated row.6
Verify it on a pull request
Push a branch and open a pull request. The project above, opened as a pull request against a GitHub repository:The
terminal
Checks job’s log ends in the same table as the local run, with the same two failures:Docker Build waits for Checks to pass, pre-commit failed on buf format (see Troubleshooting), and most of the Checks time on a first run is installing forge and the pinned tools. The gate’s table is also written to the run’s summary page. To block merging on red, make the Checks and Test jobs required status checks in your branch protection rules. Forge does not configure branch protection.What this does not do
- It does not merge or block merges by itself. It reports. Required status checks are a GitHub setting you add.
- Forge’s own lint rules are not in the gate until you add them, as in step 2.
- Slow-test checks are opt-in.
reliant forge lint --slow-testsandreliant forge ci test-budgetare not gate rows. How Forge tests work shows both. - No browser end-to-end tests.
e2e.ymlruns only on pull requests labelledrun-e2e, and it checks the built server, not a browser. - Unit tests are affected-only on a branch. The gate tests only the Go packages your change reaches, and runs the whole suite when anything other than Go source changed.
CI_FULL=1forces the whole suite.
Troubleshooting
deployability: Payload Limits … request and response payloads are unbounded
deployability: Payload Limits … request and response payloads are unbounded
On forge v1.6.1 and on forge’s current main,
reliant forge project doctor --signal deploy reports this for a freshly scaffolded service, which turns the deployability row red. The scaffolded server does cap payloads: cmd/<name>/cmd/serve.go calls skCfg.Normalize(), which sets 4 MiB limits. The check looks only for connect.WithReadMaxBytes calls under cmd/. It is a known defect and has been reported to forge. Run reliant forge project doctor --signal deploy to see the check on its own.exec: "forge": executable file not found in $PATH
exec: "forge": executable file not found in $PATH
An extra check named
forge as its command, but only reliant forge is installed. Use command: [task, lint], which runs the forge your project pins.pre-commit: buf format … Failed
pre-commit: buf format … Failed
The
buf-format hook found .proto files that are not buf-formatted. Proto that reliant forge scaffold adds for an entity can trip it. That is reported to forge. Run buf format -w, then reliant forge generate, and commit both.Next steps
Scan dependencies for vulnerabilities
Fix the
vuln-npm and vuln-go rows, or accept an advisory with a reason and an expiry date.What forge lint checks
Lanes, flags, the verdict line and how to silence a rule.
How Forge tests work
The two test tiers, the embedded Postgres, and why skipped work fails.
ci gate reference
Every flag and environment variable of
reliant forge ci gate.