AI Release Guardian Human Control Guide
Define AI release guardian human control boundaries for recommendations, waivers, approvals, protected branches, deployment gates, and audit records.
AI release guardian human control means an agent may read a diff, run allowed checks, sort proof, and advise GO or NO-GO. It may not approve, merge, tag, deploy, accept its own waiver, or weaken team rules. A named person must judge doubt and approve each release act that cannot be undone.
The AI Release Guardian skill sets this limit as its first firm rule. Use the release readiness scorecard for choice inputs, the risk-based testing strategy to match tests with risk, and QASkills for more proof skills. None of those guides gives release rights to an agent.
What Is a Recommendation-Only Release Gate?
A guardian is a proof and advice tool. It maps changed files to user behavior, picks useful tests, finds changed-line gaps, checks committed gates, and writes a report. Those tasks help a person make a choice but never become that choice.
This split should exist in access rights, screens, logs, and words. A button named "Apply guardian advice" can turn review into reflex even when a person clicks it. Show proof and open assumptions first, then require a separate act from the allowed release owner.
| Capability | Guardian may perform it? | Human control required |
|---|---|---|
| Read a committed diff | Yes | Repository grants read scope |
| Run approved test commands | Yes | Commands and environments are preauthorized |
| Classify risks and coverage gaps | Yes | Human reviews medium and high surfaces |
| Recommend GO, GO WITH WAIVERS, or NO-GO | Yes | Recommendation cites every gate |
| Accept a waiver | No | Named owner records acceptance |
| Approve or merge a pull request | No | Branch protection or repository rulesets enforce review and merge permissions |
| Create a release tag | No | Authorized release process owns tags |
| Deploy to production | No | Environment protection rules and an authorized reviewer control deployment |
| Change gate thresholds | Propose only | Policy owner reviews a separate change |
This limit is stronger than asking a model to behave. The review job token should lack write, merge, release, and live deploy rights. If the tool cannot take a banned action, a bad prompt cannot turn straight into that action.
AI release guardian human control also shapes the report wording. It may say each set gate passed for a named SHA. It must not claim the release is safe for sure, since tests and review cannot prove that no bug exists.
The human release scorecard workflow helps because it shows the rules before urgent work begins. Advice is easier to question when each input has an owner, state, and proof link.
Why Does CI/CD Separation of Duties Matter?
Separation of duties reduces the risk that one hacked or mistaken actor can review, approve, and run the same release. The guardian should work as a low-rights proof job. Branch rules, review rules, and deploy locks must live in systems it cannot rewrite during the run.
OWASP's CI/CD Security Cheat Sheet treats repos, build servers, deploy steps, and pipeline jobs as parts of security. Trusting one agent across that whole path ignores distinct attack points. Access limits should match the real tools and jobs.
A practical actor model looks like this:
| Actor | Reads | Writes | Must not control |
|---|---|---|---|
| Guardian job | Source, gate config, test artifacts | Its own evidence artifact | Branch rules, waivers, tags, deployment |
| CI test jobs | Checked-out source and fixtures | Test outputs | Repository policy and production credentials |
| Code reviewer | Diff, evidence, conversations | Review decision | Guardian evidence content |
| Waiver owner | Failed gate and compensating evidence | Signed acceptance record | Underlying test result |
| Release owner | Complete current report | Release decision | Historical evidence alteration |
| Deployment job | Approved artifact and environment config | Target environment | Source review outcome |
The guardian may start a preapproved test run if that fits its read-and-check role. It must not start any workflow with high-risk inputs. Keep an allowlist of workflows and record each command in the proof pack.
GitHub describes protected branches that can require reviews, checks, conversation resolution, successful deployments, and limited pushes. Use those platform rules to enforce the report. Do not rely on a comment that says "NO-GO" to block merge.
For AI release guardian human control, ask one key question: can a false GO change the live system without another allowed person? The answer should be no at each repo and deploy boundary.
How Does Gate Policy Preserve Human Release Approval?
The repo skill reads team rules from release-gates.yaml. That file lists proof needs, not rights for the guardian to take release steps. Keep it committed, reviewed, and safe from edits made inside the same untrusted review path.
gates:
tests:
required_suites: [unit, integration, e2e-smoke]
flake_policy: quarantine-lane
max_new_skips: 0
coverage:
changed_line_blockers: 0
static:
lint_errors: 0
type_errors: 0
new_security_findings: 0
data:
migration_rollback_documented: true
destructive_migration_requires_waiver: true
process:
risk_map_reviewed: true
max_diff_lines: 2000
The risk_map_reviewed field is for a person on purpose. A named reviewer must read the changed behavior and blast radius instead of trusting a table from the agent. Store that sign-off in the pull request or another system with access checks.
Gate changes need their own review. If one pull request adds a migration and sets migration_rollback_documented to false, use the last approved rule until a person accepts the new one on its own. If not, code can lower the bar used to grade itself.
An agent can draft a rule change with reasons. It should keep that draft outside the current verdict and not rerun under an unapproved rule. This stops it from grading its own work with a bar it just lowered.
The maximum diff size guide shows this rule for max_diff_lines. The guardian counts and stops. A rule owner then chooses a split, keeps NO-GO, or accepts a named exception.
Use repo owners for key files such as workflows, release gates, deploy config, and owner rules. Code ownership does not replace tool rights. It does give the review system a clear human path when those controls change.
How Should GO, Waiver, and NO-GO Advice Work?
The skill defines three advice states. GO means each set gate passed with cited proof. GO WITH WAIVERS means only items that may be waived remain, and a named owner accepted each one. NO-GO means a blocker, missing proof, or failed required suite remains.
These are report terms, not tool rights. A GO does not merge code. A NO-GO does not stop an allowed person from making an emergency choice outside the guardian, though repo rules may require a separate override record.
The final gate should derive its advice from named gate rows and accepted waivers. This sample rejects nameless or unaccepted waivers; real code must separately verify that the accepting actor is authorized and is not the guardian.
type GateResult = { gate: string; status: 'pass' | 'fail'; evidence: string };
type Waiver = { item: string; owner: string | null; accepted: boolean };
export function recommendVerdict(gates: GateResult[], waivers: Waiver[]) {
const failed = gates.filter((gate) => gate.status === 'fail');
if (failed.length === 0) return 'GO' as const;
const acceptedItems = new Set(
waivers
.filter((waiver) => waiver.owner && waiver.accepted)
.map((waiver) => waiver.item),
);
const everyFailureWaived = failed.every((gate) => acceptedItems.has(gate.gate));
return everyFailureWaived ? ('GO_WITH_WAIVERS' as const) : ('NO_GO' as const);
}
Real code should tell blocker failures from findings that may be waived by using the committed schema. It should also prove that each result belongs to the current head and an allowed person accepted the waiver. The function shows verdict math, not an access system.
Never let urgent free text change this math. "Customer waiting" and "release train closing" give context to the owner, not proof that changes a failed test. The report can show urgency beside the gate state without softening either one.
AI release guardian human control requires visible disagreement. If a person ships despite NO-GO, keep both the advice and the human choice with its reasons. Rewriting the report to GO would ruin the audit trail and teach teams not to trust later reports.
How Does Release Waiver Governance Work?
A waiver accepts a known and limited exception. It does not mean missing facts. The skill allows only gaps that may be waived, such as one named low-risk uncovered line, to support GO WITH WAIVERS. A missing required suite or blocker gap stays NO-GO.
Use this waiver procedure:
- Keep the original failing or waiverable finding unchanged in the report.
- State the affected behavior, scope, evidence gap, and reason it is considered waiverable.
- Name an authorized owner who is independent from the guardian process.
- Record explicit acceptance, compensating controls, expiration, and follow-up location.
- Recompute the recommendation without granting the guardian any execution permission.
A waiver with an end point stops a short-term exception from becoming a silent rule. It can end on a date, release, issue fix, or next deploy based on team rules. The owner should be a person or named role that can judge the affected behavior.
Do not accept a waiver from the same service account that made the report. A name typed in a comment does not prove who acted. Use the signed-in actor from the review or change system, then keep its link or record ID.
| Waiver field | Required value | Reject when |
|---|---|---|
| Finding | Exact report item | It paraphrases away severity |
| Owner | Authenticated named person or role | Null, agent, or generic team inbox |
| Acceptance | Explicit recorded action | Inferred from silence or prior release |
| Scope | Commit, release, and affected gate | It applies indefinitely to all changes |
| Compensating control | Specific check or rollout action | It says only "monitor closely" |
| Expiration | Concrete condition | No end or review point exists |
The binding evidence to HEAD guide matters here. A waiver for one commit must not follow a branch after a new push. New code needs a fresh report and, when the issue still applies, new approval under repo rules.
How Do Protected Branch Reviews and a Deployment Approval Gate Work?
Code review and a live deploy are linked but distinct control points. A reviewer may approve a pull request design, while a release owner checks timing, service health, and current incidents. The guardian gives proof to both but owns neither act.
Protected branches can require current checks and review before merge. Protected GitHub environments can hold a job for required reviewers. GitHub's deployment review documentation explains how to approve or reject waiting jobs and how config can block self-approval.
A GitHub Actions testing pipeline can link these jobs while keeping review and deploy rights apart. Job links carry status, while repo and deploy locks hold the right to act.
A workflow may name a protected GitHub environment, but the guardian must not bypass its protection rules. Scope live credentials to the deploy job so review and test jobs cannot read them.
jobs:
guardian:
permissions:
contents: read
actions: read
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: node scripts/build-release-report.mjs
deploy:
needs: guardian
if: needs.guardian.result == 'success'
environment: production
permissions:
contents: read
id-token: write
runs-on: ubuntu-latest
steps:
- run: ./scripts/deploy-approved-artifact.sh
This shape is safe only when the production environment has the right protection rules and the deploy script uses an approved, checked file. A job link alone is not human approval. Set required reviewers in repository settings and test that the job waits.
Keep the built file ID apart from the source SHA as well. A person should approve the exact digest that passed the checks, not a moving tag such as latest. The guardian can show the SHA-to-digest link but cannot approve its promotion.
How Do You Keep an AI Release Audit Trail?
Human control works only when choices can be reviewed later. Store the guardian report, gate files, judged SHA, rule commit, waivers, reviewer IDs, final choice, and deployed file digest. Keep and guard those records as team needs require.
An override record should not call the guardian wrong just because a release went ahead. It should name the advice, reason, actor, backup checks, and needed follow-up. A later review can compare the stated risk with what happened.
Missing proof must stay in view. The skill treats unknown coverage and tests that did not run as NO-GO. A person may accept that risk, but the record must never change "not measured" into "passed."
Use audit records to improve gates, not punish people. If many overrides concern one safe built file, improve its path rule. If urgent releases often skip a slow suite, fix the tests or write a narrow emergency rule instead of teaching the guardian to ignore failure.
The schema authority guide and constraint mapping guide use the same owner rule for test data. An agent can show clashes and build cases, while schema owners choose which rule should change.
The test data management guide also helps when release proof depends on fixtures. A green suite tied to loose or copied live data can mislead reviewers even when its commit SHA is right.
How Should You Threat-Model the Guardian?
An AI release guardian human control design must assume that inputs can be incomplete, false, or hostile. Pull request text, file names, test output, logs, and built reports can all hold text that must never grant rights. Treat them as proof inputs, not commands that can rewrite team rules.
The guardian should read gate config from a protected, reviewed place. A pull request may propose new config, but the current report must name the approved commit that set its rules. If not, changed app code can lower its own limits or remove required suites.
Tool output needs shape checks and size limits. A bad coverage file should create missing proof, not make the model guess from nearby logs. A report with an unknown suite can add context, but it must not satisfy a required suite with a close name.
| Threat or failure | Potential consequence | Enforced response |
|---|---|---|
| Prompt-like text in a changed file | Agent follows repository content as instruction | Keep system policy and tool allowlist authoritative |
| Forged green report in source tree | Stale or fabricated evidence satisfies gate | Accept only current workflow producers with identity checks |
| Pull request changes gate config | Release grades itself against weaker policy | Use previously approved policy until separate acceptance |
| Oversized logs or artifacts | Important evidence truncated or ignored | Apply documented limits and fail closed when required fields are missing |
| Test command writes repository state | Analysis changes its judged input | Run on clean checkout and verify HEAD and worktree afterward |
| Guardian token has write access | Recommendation becomes direct action | Remove write, approval, release, and deployment permissions |
Commands also need limits. The skill lists known Git diff, Jest, Playwright, and pytest commands, but repo rules decide which may run. Never let pull request text build shell parts, target names, or deploy targets.
Run the review in a throwaway worktree when possible. Check that tracked source stays clean after tools finish, aside from declared proof paths outside source. If a formatter or test edits code, report that change and wait for a person before rerunning.
OWASP's CI/CD guide treats build tools and runner nodes as attack points. Apply least privilege to the network, secrets, caches, and file stores, not only Git rights. A read-only Git token does not protect a live secret that the same job can read.
The AI release guardian human control limit should survive model failure. If the model writes bad JSON, conflicts with gate rows, misses a file, or times out, fixed gate code returns NO-GO. A fallback must never turn a parse failure into a pass.
Test this threat model with false file names, fake report text, command-like comments, wrong SHAs, duplicate jobs, and changed rule files. Fix the expected result before an agent sums it up. This keeps key controls in code and access rights instead of persuasive text.
How Do You Keep a Manual Fallback Honest?
Tools can go down during a release, but human control does not allow a hidden bypass. Write a manual proof plan that keeps the same gate names, commit SHA, owners, and final choice record. It may take more time, yet it must answer the same questions.
A manual fallback starts with a clean checkout of the exact judged SHA. Reviewers run each required suite, store run IDs and files, check changed-line coverage, read the risk map, and check migration and lint gates. Missing access or a down tool remains missing proof.
Use this fallback sequence:
- Declare the guardian outage and freeze the judged head for the review window.
- Assign an evidence coordinator who is not authorized to approve their own waivers.
- Reproduce each configured gate with commands and artifacts named in repository policy.
- Record blockers, waiverable findings, owners, and explicit acceptance in one packet.
- Let the authorized release owner decide without rewriting failed technical results.
- Reconcile the manual packet with automated output after service restoration.
| Automation failure | Manual substitute | What cannot be inferred |
|---|---|---|
| Report generator unavailable | Reviewed gate table built from original artifacts | A GO without every required row |
| Test orchestration unavailable | Approved commands run by named operator | Success from an older commit |
| Coverage aggregator unavailable | Raw coverage and changed hunks reviewed directly | Untested-line status without intersection |
| Artifact service unavailable | Access-controlled local evidence with digests | Provenance from filenames alone |
| Model analysis unavailable | Human file classification and risk mapping | Low risk from small line count alone |
Emergency rules should name who may start this path and when it ends. They should also name controls that no one may waive, such as an unknown source SHA or missing required approval. Broad phrases such as "use best judgment" give no clear audit limit.
Practice the fallback before an incident. A tabletop drill should expose missing commands, blocked files, unclear owners, and deploy needs. Fix those process gaps while normal release pressure is low.
An AI release guardian human control plan is stronger when people can work without blind trust in the agent. The agent speeds up proof collection and review. Committed rules, fixed checks, and trained owners keep the choice sound when tools fail.
When the service returns, compare the tool and human risk groups. Differences can improve prompts, parsers, or rules, but they do not rewrite the old release choice. Keep both proof packs and the reasons used at that time.
How Do You Enforce Human Control in Practice?
Start by listing each secret and action that the guardian job can use. Remove repo write, review, release, tag, deploy, and live-secret access. Then place required checks, current review, and deploy locks outside files the job can edit while it runs.
Test the limit with denied-action cases. Prove the guardian token cannot merge, tag, edit branch locks, approve a deploy, read live secrets, or accept its own waiver. A written rule without a failed access test is not fully enforced.
Review the report words and screen next. Show advice, blockers, missing proof, and waivers before any release control. Require a separate signed-in human act that names the exact head SHA and file digest.
Last, run drills where the guardian is wrong, down, or hacked. The team should still know how to read proof, keep NO-GO, use the emergency plan, and stop the review account from reaching the live system.
Make AI release guardian human control real with the AI Release Guardian skill. Limit its job to read-only access and evidence-collection permissions, then test one protected merge and one protected deploy. Keep the final choice with the named release owner.
Frequently Asked Questions
Can the guardian automatically merge after every gate passes?
No. The skill bans merge, deploy, tag, and approval acts by the guardian. A GO is cited advice for one named commit. Protected branch rules and an allowed person should control merge, while deploy locks and a release owner control the checked file.
May the agent create tests that close its own coverage gap?
It may draft a test and add it only after a person approves that code change. The guardian must then run again on the new head and treat the test like other reviewed proof. It cannot use unchecked code it wrote to make the old report pass.
Who should accept a release waiver?
A named, signed-in person allowed by team rules and responsible for the affected behavior. The approval should name the exact finding, commit, scope, backup checks, and end point. The agent may draft the record, but its service account cannot act as owner or approver.
Does human control mean every test needs manual approval?
No. Test runs, proof collection, risk grouping, and report writing can stay automatic. Human control applies to rule changes, unclear risk calls, waiver approval, code review, merge, tag, and deploy. Tools should cut repeat work while a named person keeps control at high-impact points.
What if a human releases despite a NO-GO recommendation?
Keep the first NO-GO and record the human override on its own with actor, reasons, scope, and backup checks. Do not rewrite failed or missing proof as passed. Later reviewers can then see both the gate state and the human choice without mixing them.
Are protected branches enough to enforce the boundary?
They cover key repo acts, but not each deploy, secret, waiver, or outside release tool. Combine current checks and reviews with low-rights tokens, deploy locks, fixed file digests, and signed-in choice records. Test each limit instead of assuming one setting guards the whole path.
Should the guardian ever receive production credentials?
No routine review task needs them. Scope live secrets to the protected deploy job and make that job use an approved, checked file. The guardian can read non-secret deploy proof and advise readiness without seeing secrets or gaining a path to the live system.