Gate AI Coding Agent Pull Requests With Security Scans and SARIF Evidence

Last reviewed: 2026-08-08

An AI coding agent can produce a useful patch quickly, but speed does not tell you whether the patch is safe to merge. A security scan gate gives every proposed change a repeatable checkpoint: analyze the pull request revision, preserve the scanner result, publish machine-readable SARIF evidence, and make a human decision on any alert that remains. The gate is strongest when a failed scan, a failed evidence upload, and a real security finding are treated as different states with different owners.

Direct answer

Run the security scan against the exact pull request commit produced by the agent, then require both a successful analysis and a successful SARIF publication before merge. GitHub’s code scanning configuration guidance describes repository setup choices for scanning. Select the setup that matches the languages, build steps, and runner constraints in your repository, and make the pull request event and target revision explicit.

After the scan finishes, treat the SARIF upload as its own contract. The GitHub SARIF upload documentation explains how an existing tool result is sent to code scanning and identifies upload troubleshooting paths. A green scanner process with no uploaded result is not a green security gate: reviewers cannot inspect evidence that was never attached to the pull request. Record the upload outcome, the commit it represents, and the tool identity before reporting the check as passed.

Finally, inspect the alerts in the pull request and apply a written policy. GitHub’s pull request alert triage guide covers reviewing and resolving code scanning alerts in that review surface. Your policy can block on every new alert, or only on selected severities and protected paths, but it must say who may document an exception and what evidence is required. Merge only when the scan completed, the result belongs to the current revision, the upload succeeded, and every blocking alert has a recorded disposition.

Think of the gate as four separate assertions:

  • The intended revision was analyzed.
  • A valid result was published for that revision.
  • The pull request alerts were reviewed under a known rule.
  • Any exception has an owner, rationale, and expiry.

If any assertion is unknown, keep the pull request blocked. This is an operational recommendation, so verify the exact behavior of your scanner and repository platform before making it a required check.

Who this is for

This workflow is for teams that let an AI coding agent modify application code, infrastructure, tests, or dependency files and then open a pull request. It is useful whether the agent runs in a hosted coding environment, a local terminal, or a CI job. The central problem is the same: a generated diff can look plausible while introducing an unsafe data flow, an overly broad permission, or a vulnerable dependency.

It is also for platform and security engineers who own repository checks. They need a gate that is deterministic enough for automation but legible enough for a reviewer who did not run the agent session. A scan status alone is not an audit trail. The reviewer needs to know which revision was analyzed, which tool produced the result, whether SARIF was accepted, and what happened to each blocking alert.

This guide assumes your repository already has a pull request workflow and a scanner that can emit SARIF, or that you are evaluating one. It does not prescribe a particular scanner, severity threshold, hosting plan, or programming language. Those choices belong in your repository policy and must be verified against the capabilities documented for your selected setup.

Key takeaways

  • Bind the gate to a commit SHA, not to a mutable branch name. When an agent pushes a follow-up fix, the previous scan is evidence for the previous revision only.
  • Separate three outcomes: analysis completed, SARIF upload completed, and alerts were accepted or remediated. Collapsing them into one boolean hides the reason a pull request is blocked.
  • Use a predictable policy for new findings. A severity threshold is useful only when the team also defines treatment for findings in changed lines, findings in untouched code, and documented false positives.
  • Keep logs sanitized. Store identifiers, statuses, counts, and timings; do not copy prompts, source files, environment dumps, or request bodies into a central log.
  • Re-run after every material agent change. A clean result on an earlier commit cannot clear a later revision.
  • Make the evidence easy to review alongside the diff. A reviewer should be able to move from the check to the pull request alert and then to the disposition without asking the agent to reconstruct its own history.

For handoff context, pair this gate with review handoffs for coding agent pull requests . For a durable run record, use an agent evidence ledger and attach the scan and upload statuses to the same run entry.

A happy-path operator workflow

  1. Freeze the input. When the agent opens or updates a pull request, capture the repository, pull request number, head commit SHA, base commit SHA, and workflow run identifier. Do not accept a result that names only a branch.
  2. Run the configured scan. Start the repository code scanning setup on that revision. Confirm that the languages and build steps expected by the repository were actually analyzed. If the tool exits with an error, mark analysis as failed and stop the merge path.
  3. Check the result before upload. Confirm that the scanner produced a SARIF file for this run and that its tool metadata identifies the scanner. Keep the file in the workflow’s protected artifact location long enough for an authorized reviewer to inspect it.
  4. Upload SARIF. Send the result through the documented code scanning integration. Capture a pass or fail from the upload step. Do not convert an upload error into an empty result.
  5. Review pull request alerts. Open the alerts attached to the pull request. Compare each new or changed alert with the diff, identify the affected path, and assign one disposition: remediate, accept with a documented exception, or escalate to a security owner.
  6. Release or return. If analysis and upload passed and no blocking alert lacks a disposition, the security check can pass. Otherwise, return the pull request to the agent or developer with the alert identifier, affected path, and a narrow remediation request.
  7. Repeat on updates. A new push creates a new evidence point. Recheck the head SHA and repeat the scan, upload, and triage steps before merging.

A compact implementation sketch looks like this:

pull_request_head -> scan(head_sha) -> SARIF produced?
  no  -> block, retain sanitized error metadata
  yes -> upload SARIF(head_sha) -> upload accepted?
           no  -> block, investigate integration
           yes -> review PR alerts -> blocking alerts resolved?
                    no  -> remediate or approve documented exception
                    yes -> allow the repository's normal merge checks

The error path is deliberate. If scanning fails, preserve the failure class and stop. If the upload fails, do not infer safety from a successful scanner process. If an alert remains, ask for a remediation or a documented exception. Each branch leaves an operator with a specific next action instead of a generic retry loop.

Sources checked

The workflow is grounded in three public GitHub Docs pages that were refetched for this article. The Configure code scanning page describes repository scanning setup and the available setup path. The Upload SARIF file page covers sending SARIF results to GitHub and identifies common upload troubleshooting cases. The Triage alerts in pull requests page covers examining code scanning alerts in the pull request review flow.

These sources support the mechanics of configuring scanning, publishing results, and triaging alerts. The threshold rules, logging fields, and handoff sequence in this guide are operating recommendations. Validate them against your repository risk model, scanner behavior, and merge controls before enforcing them broadly.

Contract details to verify

Treat the scan gate as an interface between four components: the agent workflow, the scanner, the SARIF publisher, and the pull request policy. Write down the contract before you turn on a required check.

Revision identity. Require the head SHA, base SHA, pull request number, repository name, and workflow run ID. A result without revision identity should be considered unverifiable. If the agent rebases or force-pushes, invalidate the old result and start again. Check the current head immediately before upload and again immediately before merge.

Analysis scope. List the languages, directories, generated-code rules, and build commands that the scan is expected to cover. A successful process can still be the wrong check if a language was skipped or a build step was unavailable. Keep exclusions narrow and review them like code. Record the effective scope in the run metadata so a reviewer can spot an accidental omission.

SARIF handoff. Verify that the scanner emits a file the integration accepts, that the upload step runs after analysis, and that the uploaded result is associated with the same revision. The upload guide’s troubleshooting list includes missing authorization for the upload, invalid SARIF, result-count limits, oversized result files, and code scanning availability problems. Exercise one known-good file and one intentionally malformed file in a non-production test repository so operators know which failure they should see.

Alert policy. Define what blocks, such as any new high-confidence finding in changed code or any finding in an authentication or authorization path. Define who can approve an exception, where its rationale lives, and when it expires. Do not silently dismiss an alert because the agent says it is harmless; the reviewer should verify the code path and record the reason.

Sanitized logging. Keep an event record that helps correlate a check without duplicating sensitive content:

repository=example/service
pull_request=184
head_sha=abc1234
base_sha=def5678
workflow_run=run-42
scanner=repository-scanner
analysis_status=passed
sarif_upload_status=passed
alert_count=0
blocking_alert_count=0
gate_decision=allow
duration_ms=48200
recorded_at=2026-08-08T10:15:00Z

Keep the log schema stable, but redact or omit prompts, source excerpts, environment variables, command output that may contain sensitive values, and the SARIF payload itself unless it is stored in an access-controlled evidence store. The example identifiers are deliberately short placeholders; replace them with your own non-secret correlation IDs. A log should tell a reviewer what happened and where to look, not reproduce the agent’s entire working context.

Ownership and retention. Assign an owner for scan failures, upload failures, and alert dispositions. Retain the minimum metadata needed to explain a merge decision, and link to the protected workflow artifact rather than copying its contents into chat or a ticket. Test access to that artifact with the same role a pull request reviewer uses. Decide how long an exception remains valid and what event forces reapproval.

Merge behavior. Confirm which check name is required, whether a new push invalidates the previous status, and whether a canceled or skipped job is treated as failure. Test these cases in a low-risk repository before applying the policy to a critical service. A gate that can be bypassed by a skipped workflow is a reporting feature, not a security control.

Failure modes

The scan never ran. Event filters, path filters, skipped workflows, or an unavailable runner can leave a pull request looking green while no analysis occurred. Make the check required and emit an explicit not-run failure that names the missing precondition.

The scanner failed before producing SARIF. Compilation errors, unsupported language features, or an unavailable dependency can stop analysis. Preserve the exit status and a short sanitized error class. Do not upload a fabricated empty file; send the change to an operator who can repair the environment or narrow the task.

SARIF was rejected. The upload documentation calls out invalid files, missing authorization, result limits, oversized files, and disabled code scanning availability among its troubleshooting paths. Treat each as an integration failure, not as evidence that the code is safe. Check the file, permissions, repository settings, and tool output, then rerun on the same commit.

Evidence belongs to the wrong revision. Caches, retries, or an agent push between analysis and upload can attach a valid result to the wrong head. Compare the recorded SHA with the pull request current head immediately before upload and immediately before merge. If they differ, discard the result and rerun.

A finding is dismissed without context. An agent may describe a finding as a false positive, but dismissal without a reviewer, rationale, and scope makes the gate unverifiable. Require a disposition record and an owner; revisit exceptions when the code path changes.

The fix introduces a second issue. A follow-up patch can remove one alert while changing a nearby data flow. Always rerun the full gate after the agent pushes a fix, and review the new diff rather than relying on the prior alert closed state.

The check is too noisy to be trusted. Blocking every historical alert can train teams to bypass the gate. Start with findings introduced by the pull request and a small set of high-impact paths, measure false-positive rates, and expand coverage deliberately. Keep the policy visible so a temporary threshold does not become permanent by accident.

The artifact is unavailable to the reviewer. A scan may pass and upload successfully while retention or permissions prevent the assigned reviewer from opening the run evidence. Test access as part of the gate, and retain a compact correlation record even when the full artifact is kept separately.

FAQ

Should every code scanning alert block an AI-generated pull request?

Not necessarily. The important requirement is a written, reviewable rule. Many teams block new severe findings in changed code while routing lower-confidence or pre-existing findings to a backlog. Whatever threshold you choose, apply it consistently to agent and human changes and document exceptions.

What should happen when the scanner is green but the SARIF upload fails?

Block the security gate. The analysis result may be useful for debugging, but a failed upload means the pull request review surface does not have the promised evidence. Fix the integration and rerun the upload for the exact same revision, or rerun the complete scan if the artifact cannot be trusted.

Can a cached result satisfy the check after the agent pushes again?

Only if you can prove that the cached result was generated for the current head SHA and the same analysis scope. In practice, a new agent push should create a new run record and a new upload. A branch name or timestamp alone is not sufficient identity.

Where should a reviewer look first?

Start with the pull request alerts, then open the affected lines and compare them with the agent diff. Use the run record to confirm the scanner, revision, and upload status. If the alert is unclear, escalate with that compact evidence rather than pasting a full prompt or environment dump.

How do I test the gate safely?

Use a non-production repository or a test pull request. Exercise a clean result, a known finding, a scanner failure, and an invalid SARIF upload. Verify that each state produces the intended check result, sanitized log entry, owner notification, and retry path before making the check required on critical repositories.

What belongs in an exception record?

Record the alert identifier, affected path, reviewer, reason for the decision, compensating control if any, and expiration or review date. Keep the record tied to the pull request revision. When the code moves substantially, require a new review rather than carrying the old exception forward automatically.

Reader next step

Choose one small repository where an AI coding agent already opens pull requests. Add a required check that records the head SHA, runs the configured scan, uploads SARIF, and exposes the pull request alerts. Then run four test cases: clean change, intentional finding, scanner failure, and upload failure. Write down the blocking rule and exception owner, and link the resulting run record from the pull request handoff. The review handoff checklist can help structure that reviewer packet; use the evidence-ledger workflow to preserve the decision trail.