Pull request scan workflow

The workflow proceeds from enabling the gate, through verifying that the gate fires, to investigating a specific block and restoring a gate that has gone silent.

Enable pull request scanning on a repository

Pull request scanning is configured per repository. A repository with pull request scanning disabled never gates a merge, regardless of which policies are enabled at the tenant level.

Prerequisites

An active VCS integration with the repository onboarded, and the Data Sources (View/Edit) permission. See Reference I: Permissions.

Steps

1. Navigate to Settings > Data Sources & Integrations, and search for the provider.
2. Select the provider. The provider view displays all instances and the status of each instance.
3. Select an instance. The instance view displays the connected repositories, the status of each repository, and the scan coverage of each repository.
4. Right-click the target repository and select Scan Configuration.
5. Confirm Active Scanners. Pull request scanning evaluates the diff with the scanners enabled here. A scanner disabled in this configuration never contributes a finding to a pull request scan and never blocks a merge.
6. Configure PR Scanning:

   • Scan PR: Trigger a security scan automatically when a pull request opens or receives a new commit. Enable this setting for every repository whose branches reach production
   • Fail PR on scan error: Fail the pull request automatically when a scanner fails, rather than allowing the merge on the strength of a scan that did not run. This setting is disabled by default, which means an errored scan does not block the merge until you enable the setting
7. Select Save.
8. Configure the status check as a required check on the target branch, in the version control system. Cortex Cloud reports the merge decision as a status check named Cortex AppSec - Code analysis; the version control system decides whether a failing check stops a merge. Without this step the gate records violations and does not enforce them.
9. Verify the configuration. Open a pull request against the repository — or push a commit to an open pull request — and confirm that the pull request receives the Cortex AppSec - Code analysis status check and that a corresponding row appears in the Pull Request Scans inventory. A pull request scan cannot be triggered from Cortex Cloud, so a pull request is the only way to exercise the configuration.

Result: Pull requests opened against the repository trigger a scan, receive a status check that links back to the scan result in Cortex Cloud, and — once the status check is required on the target branch — cannot merge while the check fails.

Important: If no status check and no inventory row appear for a pull request you opened, the gate is not running. Do not interpret the absence as a clean result — an unscanned pull request produces no row, no status check, and no warning. Follow Diagnose a gate that stopped firing.

Important: Enabling Scan PR produces findings and pull request comments, and does not by itself block any merge. Blocking requires an enabled Unified Application Security Policy with the PR Scan trigger and the Block PR action. Two policy properties determine who is affected and when: the policy scope, which limits enforcement to an asset or application boundary, and the grace period, which defers the Block PR action for a configured interval after the policy is enabled. Review both before a rollout — and before concluding that a silent gate is broken, because a policy inside its grace period blocks nothing by design. See Unified Application Security Policies.

Caution: Enabling Fail PR on scan error converts every scanner failure into a blocked merge. The setting closes the gap where a broken scanner silently permits an unscanned change, and it also stops merges during a provider outage. Enable the setting for repositories serving business-critical applications, and pair the change with a monitored path for diagnosing scan failures.

Note: For the complete scan configuration surface, including the settings shared with branch periodic scans, see Reference F: Pull request scan configuration settings.

Verify that scans are active across all projects

A configured gate and an enforcing gate are different states. Establish which repositories are actually returning pull request scan results before reporting prevention coverage.

Prerequisites: The Application Security PR Scans View permission to read the inventory, and an API key to establish the gated population in step 2. Enabling the gate on a repository the assessment identifies as ungated additionally requires the Data Sources (View/Edit) permission, which none of the scan-viewing permissions grant — confirm the assignee holds that permission before delegating remediation.

Important: The repositories absent from this inventory matter more than the rows present in it. A repository with pull request scanning disabled, a repository receiving only forked contributions, and a repository whose webhook subscription is failing all produce the same empty result as a repository with no pull request activity. Never infer coverage from row counts alone. Step 2 establishes the disabled population; the integration health view described in Diagnose a gate that stopped firing establishes the failing-webhook population.

1. Navigate to Application Security > Scans > Pull Request Scans.
2. Establish the gated population — the repositories where Scan PR is enabled. The inventory does not report this, and no console view lists pull request scanning state across repositories. Retrieve it programmatically

   1. List the onboarded repositories with GET /public_api/appsec/v1/repositories
   2. Read prScanning.isEnabled for each returned asset with GET /public_api/appsec/v1/repositories/{assetId}/scan-configuration. The repositories returning false are ungated and produce no rows in this inventory. See Repository as an asset.
3. Use the filter bar to filter by repository, organization, scanned branch, pull request ID, PR status, and scan health. Bound the assessment to the period under review, so the returned rows are the commit scans of that period rather than every merge the inventory has accumulated. Where the inventory exposes a Scan Date range filter, apply it — see Scan Date filter for the availability caveat and for what the filter can and cannot establish.
4. Filter PR Status to Failed over the same period you use for posture review. The returned rows are the merges the gate actually stopped. and several rows can belong to one pull request — count distinct Pull Request ID values, not rows, to establish how many pull requests the gate stopped. Zero Blocked rows for a gated, actively developed repository is not self-interpreting: the cause is either that no risk was introduced, that no policy carries the Block PR action for the finding types that repository produces, or that a matching policy is still inside its grace period. Resolve the ambiguity against the policy set rather than by adjusting the date range. The rows that remain are not a clean population — Passed covers both a scan that found nothing and a scan whose issues matched no blocking policy, and the column does not separate them. Read the Issues count on a Passed row to distinguish the two.
5. Enable the Blocking Policies column from the column settings icon in the inventory toolbar, then review which policies appear. Compare the policies that fired against the policies enabled for the PR Scan trigger — an enabled Block PR policy that never appears is either well-targeted or scoped away from the repositories that need it. Select a blocking policy name to open the policy in Policy Management.
6. Filter Scan Health to Error and to Partially (completed). These rows are merges evaluated on incomplete evidence. Treat every one of them as ungoverned regardless of the PR status the row reports.
7. Filter Business Application Names to one business-critical application at a time, and address the returned rows before moving to the next application. The inventory carries application names but not application criticality, and the column supports neither sorting nor grouping because a repository can belong to several applications. Establish the criticality ordering outside this inventory first: navigate to Application Security > Application Management > Business Applications, sort the table by the Business Criticality column, and record the application names in descending criticality order. The criticality tiers that qualify as business-critical are a governance decision — confirm the threshold with the AppSec Manager rather than setting the threshold at the filter. A repository that is not mapped to a business application returns an empty value — treat an empty value as unknown criticality requiring mapping, not as low criticality. To map repositories to applications, see Criteria.

Result: You hold the gated repository population, the set of commit scans the gate stopped, the policies that stopped them, and the merges that passed on incomplete evidence.

Verify the assessment is complete. Confirm all of the following before reporting prevention coverage:

• Every repository returned by step 2 with prScanning.isEnabled set to false is either assigned for enablement or recorded as an accepted gap
• Every gated, actively developed repository returning zero Blocked rows has been resolved against the policy set, rather than left ambiguous
• Every reported count of blocked pull requests is a count of distinct Pull Request ID values, not a count of Blocked rows
• Every row returned in step 6 is treated as ungoverned, regardless of the PR status the row reports
• The repositories that appear in no row at all have been accounted for through step 2 or through the integration health view — an absent repository is not a passing repository

Verify closure of an enablement handover by repeating step 2 and confirming that prScanning.isEnabled returns true for the repositories handed over.

Note: Prevention Rate is a Cortex Cloud metric reported in the ASPM Command Center, computed over a defined window and scope — see ASPM Command Center. Read the metric there rather than deriving a competing figure. To compute prevention across a custom period, use the method in Public APIs for code security issues; the underlying PR scan endpoint and its blocking policy fields are documented in Public APIs for scan management.

Note: For the inventory columns and the underlying fields, see Reference B: Inventory columns.

Investigate a blocked pull request

Open a scan result to determine what the scan found, which policy blocked the merge, and where each detection is resolved.

1. Select a scan row in the Pull Request Scans inventory. The side panel opens, titled with the pull request title rather than the repository name.
2. Review the Overview tab to establish the scope of the result:

   • Organization, Repository, and Scanned Branch identify the source branch of the pull request.
   • PR Status reports the policy evaluation result that determined the merge outcome.
   • Scan Health reports execution health. No Rescan control is present for a pull request scan.
   • Commit ID identifies the commit that triggered the scan. A pull request that received several commits produces several scan results, one for each commit.
   • Scan Date records when the scan started.
   • Issues and Issues By Type report the actionable records by severity and by scanner category.
   • Findings and Findings By Type report the raw detections by severity and by scanner category.
3. Identify the blocking policy from the Blocking Policy column on the inventory row, and select the policy name to open the policy in Policy Management. The policy defines the condition that stopped the merge and is the only place to change that condition.
4. Select the issue category tab that matches the detection you are investigating — Vulnerabilities, Configurations, Secrets, Package Integrity or Malicious Packages. The Package Integrity tab presents two tables, Licenses and Package Operational Risk; see Reference G: Scanner to issue category mapping.
5. Select an issue in the table to open the issue side card within the scan management context, then select the Findings tab to review the underlying evidence.
6. Route the issue to the inventory that owns resolution for the issue category, using Reference E: Issue category routing.
7. Confirm the fix on the next commit. Remediating a pull request scan issue means changing the code in the source branch and pushing the change — the new commit triggers a new scan, and the status check updates. There is no rescan action and no suppression path inside the scan inventory.

Caution: Blocking a merge does not undo an exposure the push already created. Treat a secret detected by a pull request scan as a containment task with a rotation deadline, not as a code-cleanup task that the block resolved.

Result: The block is attributed to a specific policy and a specific finding, and the path to clearing the gate is a commit rather than an override.

Important: An automatic fix pull request is not offered for a pull request scan issue, because the branch a fix would target is the branch already under review. Apply the change directly in the source branch of the pull request under review.

Note: The developer who opened the pull request does not need access to Cortex Cloud to act on the result. Cortex Cloud posts the findings as a pull request comment in the version control system, and the status check links back to the full scan result. See Reference H: Pull request comment feedback.

Diagnose a gate that stopped firing

A pull request scan that never runs produces no error and no row. Diagnose the silence by working from the most common cause to the least.

1. Confirm that Scan PR is enabled for the repository. Navigate to Settings > Data Sources & Integrations, select the provider and instance, right-click the repository, and select Scan Configuration.
2. Confirm the pull request source. A pull request opened from a forked repository is ignored and produces no scan. Enforce forked contributions with branch protection rules in the version control system.
3. Review the health of the integration instance. Select the instance, then select Review health. Errors are reported per repository with a specific Error Type.
4. Correct the cause identified by the Error Type value. A Webhook subscription error stops pull request scanning specifically, while periodic scanning continues on its schedule — which is why a repository can show healthy periodic scans and no pull request scans at the same time. For the full error type reference, see Branch periodic scans.
5. Verify recovery by opening a new pull request, or by pushing a commit to an open pull request, and confirming that a new row appears in the Pull Request Scans inventory with a status check on the pull request.

Result: The gate is either restored and confirmed by a fresh scan result, or the cause is attributed to a specific integration error awaiting correction.

Caution: A repository whose webhook subscription has failed continues to report healthy branch periodic scans while every pull request merges ungated. The periodic baseline then grows with risk that the gate should have stopped. Treat a webhook subscription error as an enforcement outage, not as a reporting inconvenience.

Note: The ERROR and IN_PROGRESS wire values resolve differently in the console. IN_PROGRESS renders as In Progress and is available as a PR Status filter option. ERROR renders as no PR Status value at all — the console surfaces no Error PR status and offers no Error option in the PR Status filter, and an errored scan reports Error under Scan Health instead. ERROR nevertheless remains a valid API scan-status value. Automation must handle it without assuming a corresponding console PR Status value exists.