Run MergeShield risk analysis as a CI check in your GitHub Actions workflows. Get risk scores directly in your PR checks.
How the GitHub Action works
Interactive walkthrough · 5 steps · 35 seconds
The MergeShield GitHub Action runs as a CI step in your workflow. It analyzes PRs for risk and sets a commit status check on the PR.
CI integration
Runs as a GitHub Actions step. Sets commit status on the PR.
The mergeshield/risk-check GitHub Action lets you run MergeShield risk analysis as a CI status check in your GitHub Actions workflows. When the action runs, it:
This is separate from the webhook-triggered analysis that runs automatically when the GitHub App is installed. The Action gives you explicit control over when and how analysis runs in your CI pipeline. You can configure it to fail the workflow if the risk score exceeds a threshold, making it a hard gate in your CI/CD process.
The action uses a hybrid architecture: it provides a GITHUB_TOKEN to the MergeShield API, which uses that token to fetch PR data (diff, files, commits) via Octokit. The risk score is posted as a commit status with context mergeshield/risk-check, which is separate from the mergeshield/approval status used by the approval workflow.
mergeshield/risk-check
Risk Score: 23/100 (Low) — Analysis completed in 18s
Setting up the action takes just a few minutes:
MERGESHIELD_API_KEY.The action runs on pull_request events and needs two tokens:
GITHUB_TOKEN — Automatically provided by GitHub ActionsMERGESHIELD_API_KEY — Your MergeShield API key (stored as a secret)Once the workflow file is committed, the action runs automatically on every pull request. The risk score appears as a status check on the PR, and a summary is posted to the workflow's job summary page with the full risk breakdown.
name: MergeShield Risk Check
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
risk-check:
runs-on: ubuntu-latest
permissions:
contents: read
statuses: write
steps:
- uses: mergeshield/risk-check@v1
with:
api-key: ${{ secrets.MERGESHIELD_API_KEY }}The action accepts five inputs:
api-key (required) — Your MergeShield API key, stored as a repository or organization secretgithub-token (default: GITHUB_TOKEN) — Used to fetch PR data and post commit statusesrisk-threshold (default: 75) — Maximum risk score before the action fails the workflow. Set to 50 for medium+ blocking, or 75 for critical-only blocking.timeout (default: 300 seconds) — How long the action waits for analysis completionfail-on-error (default: true) — Whether errors during analysis fail the workflow. Set to false for warning-only mode.The action also produces five outputs for use in subsequent workflow steps:
risk-score — The numeric score (0–100)risk-level — String level (low, medium, high, or critical)analysis-id — The MergeShield analysis record IDanalysis-url — Direct link to the analysis in the dashboardstatus — Final status (success, failure, or error)For more sophisticated workflows, you can use the action's outputs in conditional steps. For example:
You can combine the action with GitHub branch protection rules for hard enforcement. Configure your repository to require the mergeshield/risk-check status check, and the action will block merging when the risk score exceeds your threshold.
For monorepos or repositories with many workflows, consider using the paths filter in your workflow trigger to run the action only on relevant paths. This reduces unnecessary API calls and keeps your analysis count within your plan limits.
name: MergeShield Risk Check
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
risk-check:
runs-on: ubuntu-latest
permissions:
contents: read
statuses: write
outputs:
risk-score: ${{ steps.risk.outputs.risk-score }}
risk-level: ${{ steps.risk.outputs.risk-level }}
steps:
- id: risk
uses: mergeshield/risk-check@v1
with:
api-key: ${{ secrets.MERGESHIELD_API_KEY }}
risk-threshold: 50
fail-on-error: false
- name: Post risk summary
if: always()
run: |
echo "Risk Score: ${{ steps.risk.outputs.risk-score }}"
echo "Risk Level: ${{ steps.risk.outputs.risk-level }}"
echo "Analysis: ${{ steps.risk.outputs.analysis-url }}"It's important to understand the distinction between the two types of analysis:
Action-triggered (from the GitHub Action):
- Designed for CI/CD visibility and branch protection enforcement
- Skips approval workflow and auto-merge evaluation
- Uses commit status context mergeshield/risk-check
- The action manages its own gates via workflow pass/fail
Webhook-triggered (from the GitHub App installation):
- Designed for governance enforcement
- Runs the full pipeline: approvals, auto-merge, trust scoring, notifications
- Uses commit status context mergeshield/approval
You can use both simultaneously. The GitHub App provides automatic governance, while the Action provides explicit CI check visibility. They use separate commit status contexts so they don't interfere with each other. Note that the analysis count for billing purposes is incremented for both types.
Tip
Use the GitHub Action for CI/CD visibility and branch protection enforcement. Use the webhook-based GitHub App for the full governance pipeline including approvals, auto-merge, and trust scoring.