Operational release gate

The CodeGraph release gate combines security, quality, test, compliance, and review results into one release report. Select a project, version, and profile to compare results with configured thresholds. Use JSON and the exit code in your pipeline, and use history to compare runs.

Before a check

Prepare the local Python environment and configuration using the CLI guide. Run the examples in PowerShell from the CodeGraph repository root. Replace all quoted angle-bracket placeholders before execution; quote values that contain spaces. Use a new output path so that a report from an earlier run cannot be mistaken for the current result.

1. Identify the exact project, version and Git base reference.
2. Confirm that the CPG and upstream check inputs belong to that revision.
3. List the profiles available in the installed configuration.
4. Use an operator identity authorized by the selected profile when it requires one.
5. Decide where the immutable report and related evidence will be stored.

Check definitions and thresholds are configured in release_gate.profiles. Store the configuration used for a run alongside its report.

List profiles

python -m src.cli release profiles

The command lists each profile’s name and description, check identifiers, and severity levels: blocker, warning, or info. Choose a name for --profile; read its parameters and thresholds in the profile configuration.

Run a check

python -m src.cli release check --project "<project>" --version "<version>" --base-ref "<git-ref>" --profile "<profile>" --operator-id "<operator-id>" --format json --language en --output "<release-gate.json>"

--project defaults to unknown; production automation should pass it explicitly. --profile defaults to the configured default. --db passes a CPG path into the check execution context.

The decision contains its status, project, profile, version, timestamp, passed and total counts, blockers, warnings and individual check results. Store it with the exact source revision and freshness evidence.

After the command, retain its exit code and inspect the same output file:

$gateExit = $LASTEXITCODE
$decision = Get-Content "<release-gate.json>" -Raw | ConvertFrom-Json
$decision | Select-Object status, project, profile, version, passed, total, blockers, warnings
$decision.checks | Select-Object id, passed, severity, message, value, threshold
"CLI exit code: $gateExit"

Replace the report path with the path passed to --output. Confirm that the project, profile, and version match the request, and inspect failed checks and missing input messages. --output writes the report even when the gate fails. If the invocation fails before reporting, an older file can remain; use a new path and verify that this invocation created it.

CLI exit codes

The exit code corresponds to the report’s status. For each check, read its message, measured value, and threshold: these fields explain the result and whether the input data was available.

View history

python -m src.cli release history --project "<project>" --limit 20

History helps compare release decisions. Before relying on an older record, verify its project, version, and timestamp against the saved report and revision-specific evidence.

Accept a finding risk

A suppression accounts for the approved risk of a specific finding during a release check. The operator records the reason, approver, expiry date, and ticket:

python -m src.cli release suppress --finding-id "<finding-id>" --reason "<reason>" --approved-by "<approver>" --expires "<iso-8601>" --ticket "<ticket>" --project "<project>"

List the project’s active suppressions:

python -m src.cli release suppressions list --project "<project>"

To remove one, use the administrative route DELETE /api/v1/admin/runtime/release-gate/suppressions/{finding_id} in the same project context. Successful removal returns HTTP 204; HTTP 404 means that the selected project has no suppression with that identifier. List the suppressions again to verify the result.

Keep the decision rationale in the ticket. The finding remains recorded, and the suppression determines how it is treated during the approved period. Use the linked review workflow to change the code and verify the fix.

Administrative REST API

The authenticated admin router is mounted under /api/v1/admin/runtime/release-gate:

Example check body:

{
  "profile": "standard",
  "version": "1.2.3",
  "base_ref": "origin/main"
}

The REST check can also return pre/post dashboard snapshot identifiers and a snapshot diff when capture is enabled. Check upstream evidence currency through its revisions, timestamps, and sources.

Use the result

This operational gate produces a release report. Passing it does not complete product acceptance or close a delivery task. Record the required review, test, security and approval evidence through your delivery process before closure.

The report combines check results for the selected profile and supplied context. Compare each value with its threshold, and inspect the message, blockers, and warnings. Keep the report, profile configuration, and exact source revision alongside test results. Together, these records explain the release decision and let you repeat the check after fixes.

Recovery

• If the profile is unknown, run python -m src.cli release profiles and fix the caller configuration.
• If project inputs are stale, refresh them through their owning workflow and rerun the exact check.
• If a warning must block CI, add --fail-on-warn; do not reinterpret exit code 2 downstream.
• If a suppression is expired or unjustified, remove it and rerun the check.
• If history and the current report disagree, trust a fresh revision-bound run and investigate the stored scope.