> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Gate pull requests on lint, tests and generated-code drift

> Run one CI gate on your machine and in GitHub Actions that fails a pull request on lint errors, failing tests or stale generated code, one table row per check.

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](https://docs.reliantlabs.io/guides/forge/add-table-crud-api-pages.md).
* 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/`:

| Workflow | Runs on | What it does |
| - | - | - |
| `ci.yml` | pull requests and pushes to `main` | `checks` job (`task ci:checks`), `test` job (`task test`), `integration-test` (`task test:integration`, when the repo has integration tests) and an image build with a Trivy scan |
| `pre-commit.yml` | pull requests and pushes to `main` | the `.pre-commit-config.yaml` hooks, gitleaks included |
| `proto-breaking.yml` | pull requests that touch `proto/` | `buf breaking` against the base branch |
| `e2e.yml` | pull requests labelled `run-e2e` | the end-to-end suite |
| `build-images.yml`, `release.yml` | pushes to `main` | build, sign and deploy |

The workflows are yours to edit. `reliant forge generate` never rewrites one that exists. `reliant forge ci gate --list` prints the gate's rows:

```bash terminal theme={null}
reliant forge ci gate --list
```

```text theme={null}
checks       setup        deps-web                     no-cache
checks       static       verify-generated             heavy; after deps-web
checks       static       golangci-lint                heavy
checks       static       buf-lint
checks       static       migration-safety
checks       static       lint-web                     heavy; after deps-web
checks       static       typecheck-web                heavy; after deps-web
...
checks       kcl          validate-kcl                 heavy
checks       kcl          deployability                heavy
test         test         unit-tests                   heavy; after deps-web
integration  integration  integration-tests            heavy; n/a: no //go:build integration test files
```

**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:

```yaml forge.yaml theme={null}
ci:
  gate:
    extra_checks:
      - name: forge-lint
        command: [task, lint]
        heavy: true
```

`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**

```bash terminal theme={null}
task ci
```

```text theme={null}
CI gate summary (all)
  CHECK              RESULT      TIME  NOTE
  deps-web           PASS           -  already installed
  verify-generated   PASS        4.9s
  golangci-lint      PASS        1.3s
  buf-lint           PASS       300ms
  migration-safety   PASS       100ms
  lint-web           PASS       43.8s
  typecheck-web      PASS        2.8s
  css-health-web     PASS       800ms
  go-build           PASS        2.5s
  build-web          PASS       21.5s
  vuln-go            PASS        3.8s
  vuln-npm           FAIL       300ms  exit status 1; log: tmp/ci/all/vuln-npm.log
  license-check      PASS       800ms
  validate-kcl       PASS        3.6s
  deployability      FAIL        3.6s  exit status 1; log: tmp/ci/all/deployability.log
  forge-lint         PASS       57.3s
  unit-tests         PASS        7.2s  full suite: no origin/<default branch> to diff against
  integration-tests  N/A            -  no //go:build integration test files

FAIL — 15 passed, 2 FAILED, 1 n/a, in 57s
head: 0d143d5
```

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](https://docs.reliantlabs.io/guides/forge/scan-dependencies-vulnerabilities.md) fixes, and `deployability` is covered under [Troubleshooting](#troubleshooting). A check that could not run is `SKIPPED` and fails the gate unless you name it in `CI_SKIP=<check>` ([why](https://docs.reliantlabs.io/deep-dives/how-forge-tests-work.md#skip-is-not-pass)). 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:

```bash terminal theme={null}
reliant forge lint --quiet
```

```text theme={null}
❌ tracing lint — 1 error
   ✗ internal/handlers/catalog/handlers_crud.go:103 [forge-tracing-log-without-ctx] slog.Info logs without the context in scope, so the line carries no trace_id and cannot be joined to its request; use slog.InfoContext(ctx, …)
      → `forge lint --tracing --fix` rewrites every such call to its …Context form
forge lint: 1 gating linter(s) failed: tracing lint. Fix: address the findings above under each ❌ lane; re-run 'forge lint' to confirm.
```

`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](https://docs.reliantlabs.io/forge/linting/rollout.md).

**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`:

```text theme={null}
Error: 1 generated file(s) were hand-edited after forge wrote them:
  - internal/handlers/catalog/handlers_crud_ops_gen.go
Move the edits to a user-owned extension point (then regenerate), or `forge project disown <path> --reason "<why>"` to take ownership.
generated files failed self-certification
```

A proto change committed without `reliant forge generate`:

```text theme={null}
Error: generated code is out of date — 2 file(s) changed when forge generate re-ran:
   M frontends/web/src/gen/services/catalog/v1/catalog_pb.ts
   M gen/services/catalog/v1/catalog.pb.go
Run 'forge generate' and commit the changes.
```

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:

```bash terminal theme={null}
gh pr checks <number>
```

```text theme={null}
Checks               fail      17m35s
pre-commit           fail      2m19s
Docker Build         skipping  0
Test                 pass      6m27s
Integration Tests    skipping  0
Detect what changed  pass      4s
buf breaking         pass      4s
e2e                  skipping  0
```

The `Checks` job's log ends in the same table as the local run, with the same two failures:

```text theme={null}
  vuln-npm          FAIL       500ms  exit status 1; log: tmp/ci/checks/vuln-npm.log
  license-check     PASS       900ms
  validate-kcl      PASS        1.4s
  deployability     FAIL        1.6s  exit status 1; log: tmp/ci/checks/deployability.log
  forge-lint        PASS     1m31.1s

FAIL — 14 passed, 2 FAILED, in 4m52s
```

`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](https://docs.reliantlabs.io/deep-dives/how-forge-tests-work.md#limits-and-what-it-does-not-do) 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

> [accordion] 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.

> [accordion] 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.

> [accordion] 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

> [card] [Scan dependencies for vulnerabilities](https://docs.reliantlabs.io/guides/forge/scan-dependencies-vulnerabilities.md)
>
> Fix the `vuln-npm` and `vuln-go` rows, or accept an advisory with a reason and an expiry date.

> [card] [What forge lint checks](https://docs.reliantlabs.io/forge/linting/overview.md)
>
> Lanes, flags, the verdict line and how to silence a rule.

> [card] [How Forge tests work](https://docs.reliantlabs.io/deep-dives/how-forge-tests-work.md)
>
> The two test tiers, the embedded Postgres, and why skipped work fails.

> [card] [ci gate reference](https://docs.reliantlabs.io/reference/cli.md#reliant-forge-ci-gate)
>
> Every flag and environment variable of `reliant forge ci gate`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.