Skip to main content
By the end of this guide, every pull request runs the same gate you run locally: lint, build, tests, vulnerability and license scans, and a check that generated code matches its inputs. The gate prints one table, and any failed or skipped row fails the pull request. Forge writes the GitHub workflows, but each job only calls a 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 --version inside 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
Every check runs even after another fails, and each one’s output is in 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:
A proto change committed without reliant forge generate:
Both exit 1, and the gate runs this check as its 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:
terminal
The 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-tests and reliant forge ci test-budget are not gate rows. How Forge tests work shows both.
  • No browser end-to-end tests. e2e.yml runs only on pull requests labelled run-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=1 forces the whole suite.

Troubleshooting

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