Using the gate in CI

The forgecroft-gate command is designed to drop into any continuous-integration system — GitHub Actions, GitLab CI, CircleCI, Buildkite, or a bare shell script. The pattern is always the same: evaluate the pull-request diff against your Controls and fail the job on a no_go verdict.

1. Create a scoped API key

Create an API key in the Forgecroft console under Settings → API keys, scoped to just what the pipeline needs — evaluate a change and read the verdict. It cannot approve changes, manage API keys, or touch other resources. Store the key in your continuous-integration secret store (for example, a secret named FORGECROFT_API_KEY in GitHub Actions).

See API Keys for the full scope reference.

2. Evaluate the diff in the job

.github/workflows/forgecroft-gate.yml

- name: Checkout
  uses: actions/checkout@v4
  with:
    fetch-depth: 0   # the gate diffs the PR base against HEAD

- name: Install the Forgecroft gate
  run: curl -sSfL https://install.forgecroft.com | sh

- name: Evaluate change against Controls
  env:
    FORGECROFT_API_KEY: ${{ secrets.FORGECROFT_API_KEY }}
  run: forgecroft-gate --range origin/${{ github.base_ref }}...HEAD

forgecroft-gate evaluates the diff and exits 0 unless the verdict is no_go or a finding is a blocker (then it exits 1). That alone is enough to gate a job. It fails open if Forgecroft is unreachable; add --strict to fail closed instead.

3. Use the GitHub Action for a turn-key pull-request gate

Rather than hand-writing the workflow, use the Forgecroft Gate GitHub Action. The starter workflow at examples/forgecroft-gate.yml evaluates every pull request and posts a sticky verdict comment. Copy it to .github/workflows/forgecroft-gate.yml and add a FORGECROFT_API_KEY repository secret. See CI Gate for the full setup.

To run the gate as a local git hook instead, wire forgecroft-gate --pre-push into a .git/hooks/pre-push script. The hook reads the pushed refs from stdin and evaluates the outgoing diff before the push leaves your machine.

4. JSON output for downstream steps

forgecroft-gate accepts --json for machine-readable output:

VERDICT=$(forgecroft-gate --json | jq -r '.decision.verdict')
if [ "$VERDICT" = "no_go" ]; then
  echo "Change violates a Control: $VERDICT" >&2
  exit 1
fi

Key hygiene

• Rotate continuous-integration keys on a schedule — create a replacement in the console, deploy it, then revoke the old key.
• Suspend, don’t delete, if you want to temporarily revoke access; suspension is instant and reversible.
• Keep a gate key scoped to evaluate and read only — it never needs to approve or administer.
• Manage every key from the Forgecroft console under Settings → API keys.