Skip to main content

Operational release gate

Run, inspect and administer the CodeGraph operational release gate without confusing it with governed SDLC closure.

User Guides

The CodeGraph release gate aggregates configured security, quality, test, compliance and review checks into an operational decision for a selected project and profile. It is useful in a release pipeline, but it is not the authoritative SDLC reducer and does not close a task, story or PRD.

Before a check

  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.

Do not infer a profile’s checks from its name. Configuration can change between releases.

List profiles

python -m src.cli release profiles

The output lists every configured profile and its current checks. A guide must not freeze the profile count or claim that a particular profile exists in every installation.

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 can select an existing CPG for CLI operation when project resolution is insufficient.

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.

CLI exit codes

CLI exit codes
Code Meaning
0 Gate status is pass.
1 Gate status is fail, or warn was promoted with --fail-on-warn.
2 Gate status is warn and --fail-on-warn was not used.

A skipped or unavailable upstream signal must remain visible in the report. A zero exit code covers the facts checked by the selected profile; record every required upstream signal in the release package.

View history

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

History helps compare operational decisions. Cite an older record only after validating the project, version, and timestamps against the immutable evidence store.

Accept a finding risk

Creating a suppression is a governed administrative action. It changes the release decision for the finding; it does not change the source-level condition:

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

Inspect and remove active suppressions with:

python -m src.cli release suppressions list --project <project>
python -m src.cli release suppressions remove --finding-id <finding-id>

Use a traceable human approver, bounded reason, expiry and ticket. A suppression changes the operational gate’s treatment of a finding; the finding and every other evidence lane remain recorded separately.

Administrative REST API

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

Administrative REST API
Method and route Purpose
POST /api/v1/admin/runtime/release-gate/check Run a check for the active project context.
GET /api/v1/admin/runtime/release-gate/profiles List configured profiles.
GET /api/v1/admin/runtime/release-gate/history Read decision history.
POST /api/v1/admin/runtime/release-gate/suppress Create an approved suppression.
GET /api/v1/admin/runtime/release-gate/suppressions List active suppressions.
DELETE /api/v1/admin/runtime/release-gate/suppressions/{finding_id} Remove a suppression.

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.

Operational gate versus authoritative SDLC

The two decisions answer different questions:

Operational gate versus authoritative SDLC
Decision Question answered
operational gate Did the selected release profile pass its configured runtime checks for this invocation?
authoritative SDLC Are revision-bound requirements, acceptance criteria, tests, evidence lanes, traceability and finance complete under the governed reducer?

Never map a CLI pass or REST status=pass directly to task/story/PRD Done. Full closure still requires the authoritative carrier and every mandatory lane. A release pipeline may require both decisions.

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.

Maintained sources

  • src/cli/governance_suite/release_gate_commands.py defines CLI commands, parameters and exit codes.
  • src/api/routers/query_suite/release_gate.py defines the admin REST request and response contracts.
  • src/api/app_routers.py defines the mounted REST prefix.
  • src/release/ and the release_gate section of config.yaml define checks, profiles, reports, history and suppressions.

Current source, configuration and CLI help are authoritative when this guide differs from the installed revision.

Report a documentation issue