Skip to content

Setting Up PR Scanning

This guide walks you through enabling PR scanning on your repositories. Once set up, Mayo ASPM will automatically scan every pull request and post findings directly on the PR.

Prerequisites

Before enabling PR scanning, verify that:

Prerequisite How to Verify
GitHub App is installed Navigate to Integrations > GitHub and confirm the app is connected with a green status badge
Repositories are synced The repositories you want to scan appear on the Assets page as integration assets
Assets are active The target repositories have their Active toggle enabled

GitHub App Required

PR scanning only works with integration assets connected via the GitHub App. Public assets (manually added) cannot receive PR webhooks. If you need PR scanning on a repository, install the GitHub App on that repository's organization.

Step-by-Step Setup

Step 1: Navigate to the PR Scanning Page

From the left sidebar, click PR Scanning. This opens the PR Scanning management page showing all integration assets in your organization.

Step 2: Locate Your Repository

Use the search bar to find the repository you want to enable PR scanning for. The table displays:

Column Description
Repository The full owner/repo-name
PR Scanning Toggle switch (On/Off)
Mode Simple or OPA
Alert Severities Which severities trigger alerts
Block Severities Which severities block the PR
Scanners Which scanners run on PRs
Last PR Scan Timestamp of the most recent PR scan

Step 3: Toggle PR Scanning On

Click the PR Scanning toggle for your repository to switch it from Off to On. When you enable PR scanning for the first time, default settings are applied automatically.

Default Settings

When PR scanning is first enabled, the following defaults are applied:

Setting Default Value
Mode Simple
Alert severities Medium, Low
Block severities Critical, High
Scanners OpenGrep
Active Enabled

Customizing Defaults

These defaults provide a sensible starting point. You can immediately customize them — see Configuring Alerts & Blocks for details.

Step 4: Verify the Setup

To confirm PR scanning is working:

  1. Open a pull request on the repository (or push a new commit to an existing PR)
  2. Navigate to the Scan Queue page — you should see a PR scan queued or running
  3. Once the scan completes, check the pull request on GitHub for the Mayo ASPM comment and check run

What Happens After Enabling

Once PR scanning is enabled for a repository, the following occurs automatically for every pull request:

On PR Open

When a new pull request is opened:

  1. GitHub sends a pull_request.opened webhook to Mayo ASPM
  2. Mayo ASPM validates the webhook and checks if PR scanning is enabled for the repo
  3. A scan is queued using the configured scanners and settings
  4. Results are posted as a comment and check run on the PR

On PR Push (Synchronize)

When new commits are pushed to an existing PR:

  1. GitHub sends a pull_request.synchronize webhook
  2. A new scan is queued for the updated branch
  3. The existing comment is updated (not duplicated) with the new scan results
  4. The check run is updated with the new status

On PR Reopen

If a closed PR is reopened:

  1. GitHub sends a pull_request.reopened webhook
  2. A new scan runs against the current branch state
  3. Results are posted/updated as usual

Configuring GitHub Branch Protection

To enforce PR scanning as a merge gate, configure GitHub branch protection rules:

Step 1: Go to Repository Settings

On GitHub, navigate to your repository's Settings > Branches > Branch protection rules.

Step 2: Add or Edit a Rule

Create or edit the rule for your default branch (e.g., main).

Step 3: Require Status Checks

Enable Require status checks to pass before merging and add the Mayo ASPM check:

mayo-aspm-scanner / security-scan

Step 4: Save

Save the branch protection rule. Now, PRs cannot be merged unless the Mayo ASPM check passes.

Blocking Merges

When branch protection is configured to require the Mayo ASPM check, any PR with findings at block severity levels will be unable to merge. Ensure your team understands the block thresholds before enabling this. Start with blocking only Critical findings, then expand as your team adapts.

Enabling for Multiple Repositories

If you need to enable PR scanning across many repositories at once, use the bulk management feature:

  1. On the PR Scanning page, select repositories using the checkboxes
  2. Click Bulk Actions > Enable
  3. All selected repositories will have PR scanning enabled with default settings

See Bulk Management for detailed instructions.

Disabling PR Scanning

To disable PR scanning for a repository:

  1. Navigate to the PR Scanning page
  2. Find the repository
  3. Toggle the PR Scanning switch to Off

When disabled:

  • No new PR scans will be triggered for that repository
  • Existing scan history and findings are preserved
  • The Mayo ASPM check will no longer appear on new PRs
  • Previously posted comments remain on past PRs

Troubleshooting Setup

PR Scan Not Triggering

If opening a PR does not trigger a scan:

  1. Verify PR scanning is enabled for the repository on the PR Scanning page
  2. Check the GitHub App installation — ensure the app has access to the repository
  3. Check the Scan Queue — the scan may be queued behind other scans
  4. Verify the webhook — navigate to the GitHub App settings and check the webhook delivery log for failures

Check Run Not Appearing

If the scan runs but no check run appears on the PR:

  1. Verify the GitHub App permissions — the app needs checks: write permission
  2. Wait for scan completion — the check run is posted after the scan finishes, not when it starts
  3. Check for errors — view the scan details in the Scan Queue for any failure messages

Comment Not Posted

If the scan completes but no comment appears:

  1. Verify the GitHub App permissions — the app needs pull_requests: write permission
  2. Check the finding count — if the scan produced zero findings, no comment is posted (and the check run passes)

Next Steps