CI/CD
Generate the canonical report in one job, run the policy gate in a separate fail-closed step, and treat exit codes 1 and 2 as non-green. Includes forked pull request rules.
Two jobs, two responsibilities
SecHelix is a release input, not a replacement for code review or existing security controls. Generate the canonical report in an authorized job, then run the policy gate in a separate fail-closed step.
python -m reports.report_renderer report.canonical.json --format json --output report.json
python scripts/security_gate.py report.json --policy policies/default.json --json-outputSplitting them matters: report generation may need model access, network access, or scanner artifacts. The gate needs none of that, and keeping it separate means the decision step cannot be influenced by the same credentials that produced the evidence.
An illustrative GitHub Actions fragment is available at examples/ci/security-gate.yml. It does not run scanners or models and must be adapted to your organization report production and fork-secret policy.
Exit codes
| Exit code | Outcome | CI treatment |
|---|---|---|
0 | PASS or PASS_WITH_KNOWN_RISK | Green |
1 | BLOCKED | Non-green |
2 | INCOMPLETE, malformed input, or missing policy/evidence | Non-green |
Pull-request safety
- Do not expose private policies, provider credentials, or signing identity to forked pull request code.
- Do not use pull_request_target to execute untrusted checkout content with secrets.
- Normalize external scanner artifacts as untrusted input.
- Pin third-party actions to reviewed immutable commits in production workflows.
- Set explicit minimal permissions and artifact retention.
- Require protected-environment approval for risk acceptance or signing.
Private policy packs are loaded at runtime from protected storage or a private checkout. They must not reach public build artifacts, SARIF uploads, Pages content, cache keys, or logs. CI exposes only the gate outcome and a redacted reason summary to untrusted pull requests.
Required gate tests
Verify the integration itself before trusting it. Six cases:
- Unresolved verified Critical or High produces BLOCKED.
- A fixed Critical or High with complete independent verification produces PASS when otherwise clear.
- A valid policy-approved accepted risk produces PASS_WITH_KNOWN_RISK.
- An integrity-critical unknown produces INCOMPLETE, or BLOCKED under a policy that selects it.
- A missing required tool produces INCOMPLETE.
- An empty or malformed report produces INCOMPLETE, never PASS.
Artifacts
Preserve the human-readable and JSON gate decision as an artifact, without uploading raw secrets or private policy values. The gate decision is release evidence, and the retention guidance classifies it as such: keep it for the supported release lifetime plus the organization audit window.