Connect Your Repository
Connecting a repository means dropping the gate into its CI so every pull request is evaluated against your organization’s Controls before it merges. Your source tree never leaves your runner — only the changed diff is sent to the Forgecroft API over TLS.
Get an API key
Section titled “Get an API key”Create a key with evaluate:read scope in the console under Settings → API Keys, then store it as a repository or organization secret named FORGECROFT_API_KEY. The key is read from the environment only — never echoed to logs or placed in command arguments.
If you only want to try the gate first, skip the key and run --offline against the embedded best-practice packs — see Evaluate Your First Change.
Add the gate workflow
Section titled “Add the gate workflow”Copy the starter workflow from examples/forgecroft-gate.yml into your repository at .github/workflows/forgecroft-gate.yml. It runs the Forgecroft Gate GitHub Action on every pull request and posts a sticky verdict comment.
Optionally add a .forgecroft config file at the repository root to set api_url, key_env (the name of the secret holding your key), mode (block or warn), or severity_floor (blocker or concern). Every key is optional, and the API key itself is never stored in this file.
Commit the workflow (and .forgecroft if you added one). On the next pull request, the gate downloads the forgecroft-gate binary, computes the diff between the base and head SHAs, and POSTs only that diff to the Forgecroft API for a deterministic verdict.
Confirm it is wired up
Section titled “Confirm it is wired up”Open a pull request with any change. The gate runs inside your own CI runner and posts a sticky comment with the verdict (go / conditional_go / no_go / insufficient_context). It exits non-zero only on a no_go verdict or a blocker-severity finding; Forgecroft being unavailable is fail-open by default.
Start in mode = warn to observe verdicts without failing the build, then switch to mode = block once you are ready to enforce.
The repository is connected. Next: evaluate your first change, or read the full CI Gate guide for fail-open semantics, offline mode, and the action inputs reference.