Getting Started with MergeShield in 5 Minutes

By the end of this guide, you'll have MergeShield running on your GitHub repositories with automatic risk analysis on every pull request. Here's what the setup involves:

1. 1Install the MergeShield GitHub App on your organization
2. 2See your first risk analysis on an open PR
3. 3Understand the six risk dimensions and how scores work
4. 4Optionally configure auto-merge rules for low-risk PRs

The entire process takes about 5 minutes. No server setup, no infrastructure, no YAML files.

Head to mergeshield.dev and click "Get Started with GitHub." You'll be redirected to GitHub to authorize the MergeShield app.

During installation, you'll choose which repositories to grant access to. You can start with a single repository to test things out, or install across your entire organization.

MergeShield requires these permissions:

• Read access to pull requests, commits, and code (for AI analysis)
• Write access to comments and commit statuses (for posting risk reports)

Once installed, MergeShield automatically syncs your repositories and begins monitoring for new pull requests. You'll see your repos appear in the dashboard within seconds.

Open a new pull request in any repository where MergeShield is installed — or push a new commit to an existing PR. Within 30 seconds, MergeShield posts a detailed risk analysis comment directly on the PR.

The comment includes:

• An overall risk score (0-100) with a colored severity badge
• Individual scores across all six dimensions
• Specific findings with concrete suggestions
• File-level risk attribution showing which files contribute most to the score
• A link to the full analysis on the MergeShield dashboard

This comment is the core of MergeShield's value. Your team sees the risk assessment right where they already review code — no new tools, no dashboards to check, no context switching.

MergeShield evaluates every PR across six independent dimensions:

• Security — authentication changes, secrets exposure, injection risks, permission modifications
• Complexity — cyclomatic complexity, deeply nested logic, large function additions
• Blast Radius — how many components, services, or users are affected by this change
• Test Coverage — whether new code has tests, whether existing tests were modified to match
• Breaking Changes — API contract changes, schema modifications, backward-incompatible updates
• Dependencies — new dependencies, version bumps, supply chain risk, license concerns

Each dimension gets a score from 0 (no risk) to 100 (critical risk). The overall score uses a weighted formula: max × 0.4 + avg × 0.6. This ensures that one high-risk dimension can't hide behind low scores in other areas.

Scores map to four severity levels:

• Low (0-25) — routine changes, safe to auto-merge
• Medium (26-50) — worth a quick look, usually fine
• High (51-75) — requires careful review
• Critical (76-100) — block merge until a human signs off

Once you're comfortable with MergeShield's scoring, you can enable auto-merge for low-risk PRs. Navigate to your repository settings in the MergeShield dashboard and toggle auto-merge on.

The default configuration is deliberately conservative:

• Maximum risk score: 30 (only Low-risk PRs)
• Minimum trust level: Medium for the agent
• All CI checks must pass
• 5-minute cooldown before merging (re-checks criteria after delay)
• Maximum 50 changed files

You can adjust every parameter to match your team's risk tolerance.

Auto-merge is particularly powerful for AI agent PRs. When Dependabot opens a routine dependency bump that scores 5/100, there's no reason for a human to review it. MergeShield merges it automatically after the cooldown, freeing your team to focus on the changes that actually need attention.

You're now up and running with MergeShield. Here's what to explore next:

• Agent Detection & Trust — MergeShield automatically identifies 11+ AI coding agents and tracks their trust scores independently
• Approval Workflows — require human sign-off for PRs above a certain risk threshold, with automatic escalation to specific reviewers
• Custom Risk Policies — add per-repo rules to adjust scores for sensitive file patterns (like *.env*), specific authors, or critical paths
• GitHub Action — run MergeShield as a CI check with uses: mergeshield/risk-check@v1 for even tighter integration
• API & Webhooks — build custom integrations with the MergeShield REST API and outgoing webhooks

All of these features are configurable from the dashboard. Start simple and progressively enable more governance as your team's confidence grows.