Quick Start

MergeShield is a control plane for autonomous software agents. It installs as a GitHub App on your repositories and automatically analyzes every pull request opened by AI coding agents like Claude Code, GitHub Copilot, Cursor, Devin, and others. The goal is to give engineering teams the visibility and governance they need to safely adopt AI-assisted development workflows.

When a pull request is opened or updated, MergeShield receives a webhook from GitHub and runs a two-stage AI analysis pipeline:

1. 1Stage 1 — Risk Scoring: Claude evaluates the PR diff across six risk dimensions, producing a calibrated score between 0 and 100.
2. 2Stage 2 — Reasoning Extraction: A separate pass produces a structured log explaining *why* the score was assigned.

The entire process completes in under 30 seconds.

Beyond analysis, MergeShield provides a full governance layer — agent detection and trust scoring, configurable auto-merge rules, approval workflows for high-risk changes, custom risk policies, and a real-time dashboard with analytics. Everything is scoped per-organization, so each team can configure rules independently.

To get started, navigate to your MergeShield dashboard and click the Install GitHub App button. This takes you to the GitHub App installation page where you can choose:

• Which organization or personal account to install it on
• Which repositories to grant access to (all repos or specific ones)

Once you click Install, GitHub redirects you back to MergeShield. The app automatically:

1. 1Creates an organization for your GitHub account
2. 2Syncs your selected repositories
3. 3Begins watching for pull request events

If there are already open pull requests, MergeShield will queue them for analysis (up to 5 per repository on initial sync).

After installation, visit the setup wizard at /dashboard/setup to verify your repositories were synced correctly. You can also trigger a manual sync from the Repositories page if any repos are missing.

Once the GitHub App is installed, open or update a pull request on one of your connected repositories. MergeShield receives the webhook event from GitHub within seconds and enqueues an analysis job.

The worker fetches three things from GitHub via the API:

• The PR diff (up to 2 MB)
• The changed files list
• The commit history

The entire analysis typically completes in under 30 seconds. When it finishes, MergeShield posts a comment directly on the pull request with a risk score breakdown. The comment shows the overall risk level, scores across all six dimensions, and file-level risk attribution so you can see exactly which files contribute the most risk.

You can also view the analysis on the MergeShield dashboard by navigating to Pull Requests and clicking on the PR. The detail page shows the full risk breakdown, AI reasoning log, auto-merge evaluation, and approval status. If the PR was authored by a recognized AI agent, you will also see agent detection information and trust score details.

Every analysis produces a risk score between 0 and 100, broken down into four severity levels:

• Low risk (0–24) — Documentation updates, config tweaks, simple bug fixes
• Medium risk (25–49) — New features, moderate refactors, multi-component changes
• High risk (50–74) — Security-sensitive changes, API modifications, architectural changes
• Critical risk (75–100) — Authentication rewrites, infrastructure changes, production database migrations

The overall score is calculated from six individual dimensions: Complexity, Security, Blast Radius, Test Coverage, Breaking Changes, and Overall. The formula is:

overall = (max_dimension × 0.4) + (avg_all_dimensions × 0.6)

This ensures a single very high-risk dimension (like a security vulnerability) cannot be hidden by low scores elsewhere.

Scores are calibrated with repo context — the AI receives the repository name, author type (human, agent, or bot), and agent slug. A change to a test repository will generally score lower than the same change in a production infrastructure repo. For a deeper dive, read Understanding Risk Scores.

Now that you have risk analysis running on your pull requests, here are the features to explore next:

• Agent Detection & Trust — Understand how MergeShield tracks agent behavior over time and builds trust scores based on PR history
• Configuring Auto-Merge — Set up rules that automatically merge low-risk PRs from trusted agents. Start with a dry-run preview to see what would be auto-merged before enabling it
• Approval Workflows — Configure thresholds and escalation reviewers for human oversight on high-risk changes
• Custom Risk Policies — Create org-specific rules that adjust scores after AI analysis (e.g., always flag *.env* files as high-risk)
• API & Webhooks — Integrate MergeShield into your existing tooling with 65+ REST endpoints and HMAC-signed outgoing webhooks
• GitHub Action — Run risk analysis as a CI status check in your GitHub Actions workflows