Skip to content

Set Up PR Security Gates

This guide walks you through configuring Mayo ASPM to automatically scan pull requests and post results as GitHub check runs and comments.

Goal

By the end of this guide, you will have:

  • PR scanning enabled for a repository
  • A policy that blocks PRs introducing critical vulnerabilities
  • Check runs and inline comments on PRs with findings

Time: ~20 minutes

Prerequisites

  • A Mayo ASPM account with admin access
  • The GitHub App installed with Checks: Write and Issues: Write permissions
  • At least one repository synced and scanned (see Secure a Node.js app)

Step 1 — Enable PR scanning

  1. Navigate to Settings > Integrations > GitHub > PR Scanning.
  2. Toggle Enable PR scanning to on.
  3. Select the scanners for PR scans:
    • Gitleaks (recommended — fast, catches secrets)
    • Grype (recommended — catches new vulnerable dependencies)
    • Semgrep (optional — adds SAST but increases scan time)
  4. Select the comment style:
    • Summary comment — one comment with finding counts
    • Inline annotations — comments on specific lines
    • Check both for the best experience
  5. Click Save.

Step 2 — Write a PR scan policy

  1. Navigate to Policies > New Policy.
  2. Select kind: PR Scan.
  3. Name: pr-gate-block-critical.
  4. Paste this Rego:
package mayo.pr_scan

import rego.v1

# Block PRs that introduce critical findings
result := "fail" if {
    input.scan_results.by_severity.critical > 0
}

# Pass everything else
default result := "pass"

# Compose a helpful message
message := sprintf(
    "Blocked: %d critical finding(s) introduced by this PR. Please fix before merging.\n\nFindings:\n%s",
    [
        input.scan_results.by_severity.critical,
        concat("\n", [sprintf("- %s (%s)", [f.title, f.severity]) |
            some f in input.scan_results.new_findings
            f.severity == "critical"
        ])
    ]
) if {
    result == "fail"
}

message := sprintf(
    "Scan complete: %d new finding(s), %d fixed. No blocking issues.",
    [input.scan_results.total_new, input.scan_results.total_fixed]
) if {
    result == "pass"
    input.scan_results.total_new > 0
}

# Annotate critical and high findings inline
findings_to_annotate := [f.id |
    some f in input.scan_results.new_findings
    f.severity in ["critical", "high"]
]
  1. Click Save & Activate.

Step 3 — Test with a pull request

Create a test PR to verify the setup:

  1. In your repository, create a new branch:
git checkout -b test-mayo-pr-scan
  1. Add a test vulnerability. For example, add a known-vulnerable dependency:
# In package.json, add or downgrade a dependency to a vulnerable version
# e.g., "lodash": "4.17.19"

Or add a test secret (in a file you'll delete later):

echo 'AWS_SECRET_KEY=AKIAIOSFODNN7EXAMPLE0' > test-secret.txt
git add test-secret.txt
git commit -m "Test: trigger PR scan"
git push -u origin test-mayo-pr-scan
  1. Open a pull request targeting your main branch.
  2. Wait 1-2 minutes for the scan to complete.

Step 4 — Verify the results

On your pull request in GitHub, you should see:

Check run

A check run named Mayo ASPM Scan with status:

  • Pass (green check) — no blocking findings
  • Fail (red X) — critical findings detected

PR comment

A comment from the Mayo ASPM bot with:

  • Finding count by severity
  • Links to findings in Mayo ASPM
  • Remediation guidance

Inline annotations

If you enabled inline annotations, you'll see comments on the specific lines where findings were detected.

Clean up your test

After verifying, close the test PR and delete the branch. Remove any test vulnerabilities you added.

Step 5 — Configure branch protection (optional)

To enforce PR scans as a merge requirement:

  1. In GitHub, go to Settings > Branches > Branch protection rules.
  2. Edit the rule for your main branch.
  3. Under Require status checks to pass before merging, add Mayo ASPM Scan.
  4. Click Save changes.

Now PRs cannot be merged until the Mayo ASPM scan passes.

Step 6 — Refine the policy

After running for a week, review PR scan results:

  1. Navigate to Scans and filter by type: PR Scan.
  2. Check how many PRs were blocked vs. passed.
  3. If the block rate is too high:
    • Tighten the policy to block only critical (not high)
    • Add exceptions for specific patterns (e.g., test files)
  4. If the block rate is zero:
    • Consider expanding to block on high-severity findings too

Advanced: Different rules per repository

Scope the PR scan policy to specific projects for stricter or more lenient rules:

  • Payment service: block on critical + high
  • Internal tools: inform only, no blocking
  • Open source libraries: block on any new finding

See Policy scoping for details.

Verification

Confirm your setup:

  • PR scanning is enabled in integration settings
  • A PR scan policy is active
  • Test PR received a check run result
  • Test PR received a comment with findings
  • (Optional) Branch protection requires Mayo ASPM scan

Next steps