Approval Workflows

Approval workflows are designed for teams that want human oversight on changes above a certain risk threshold before they can be merged. This is especially useful when combined with auto-merge: low-risk PRs from trusted agents are auto-merged automatically, while higher-risk changes require explicit human approval.

The approval workflow integrates with GitHub's status check system. When a PR requires approval, MergeShield sets a pending commit status (mergeshield/approval) on the PR. If your repository has branch protection configured to require this status, the PR cannot be merged on GitHub until the approval is granted.

You can use approval workflows in three ways:

• Standalone — As a risk-awareness layer that flags high-risk PRs for review (no auto-merge)
• Combined with auto-merge — For a complete governance pipeline: analyze → approve if needed → auto-merge if rules pass
• For specific author types — Require approval only for agent-authored PRs, only for human PRs, or both

The approval workflow is configured per-repository on the repository detail page in the dashboard. Key settings:

• Risk threshold (0–100) — The minimum risk score that triggers an approval requirement. PRs scoring below this do not require approval.
• Require for Agents — Toggle to require approval for agent-authored PRs
• Require for Humans — Toggle to require approval for human-authored PRs
• Auto-reject threshold — A safety net for extremely high-risk changes. PRs scoring above this are automatically rejected without waiting for human review.
• Timeout (1–720 hours) — After this period, pending approvals automatically expire

The auto-reject only fires when the risk score exceeds both the approval threshold and the auto-reject threshold. This prevents accidental auto-rejection of moderate-risk PRs.

When a PR requires approval, MergeShield notifies the designated reviewers through personalized emails with direct links to the Approval tab, as well as standard organization-wide notifications. Escalation reviewers are configured in the approval workflow settings using their GitHub usernames.

The reviewer selection dropdown shows organization members with their githubLogin for easy selection, and you can also enter GitHub usernames manually for reviewers outside your MergeShield organization.

Reviewers can then approve or request changes from either platform:

• From MergeShield — Click the direct link in the email, review the risk analysis, and approve or request changes from the dashboard
• From GitHub — Use the standard GitHub review flow (Files changed → Review changes → Approve or Request Changes). MergeShield syncs this automatically.

Both directions update the approval status, GitHub commit status, and audit trail instantly. See Bidirectional GitHub Sync for details.

Choosing the right escalation reviewers matters. Consider selecting team members who:

• Are familiar with the relevant codebase areas
• Have the authority to approve or reject changes
• Can respond within the configured timeout period

You can configure different escalation reviewers for different repositories to match your team's ownership model.

MergeShield uses GitHub's commit status API to enforce approval requirements. The lifecycle works like this:

1. 1Approval required → MergeShield sets a pending commit status with context mergeshield/approval
2. 2Approved (from MergeShield or GitHub review) → Status updated to success ✓
3. 3Changes Requested (from MergeShield or GitHub review) → Status updated to failure ✗
4. 4Expired → Status updated to failure ✗

If your repository has branch protection rules requiring the mergeshield/approval status check, GitHub will block the merge button until the status is success. This creates hard enforcement — even if someone tries to merge directly on GitHub, GitHub will prevent it.

The commit status is updated regardless of whether the approval action originates from MergeShield or from a GitHub review — the bidirectional sync keeps both platforms aligned. The mergeshield/approval context is separate from the mergeshield/risk-check context used by the GitHub Action.

To review a pending approval, navigate to the PR detail page in the MergeShield dashboard and switch to the Approval tab. You will see:

• The approval record with the risk score that triggered it
• The current status (Pending, Approved, Changes Requested, or Expired)
• The time remaining before expiry

You can Approve or Request Changes with an optional comment explaining your decision. When you approve:

1. 1MergeShield updates the GitHub commit status to success
2. 2A GitHub PR comment is posted: "Approved by @you via MergeShield"
3. 3Auto-merge rules are re-evaluated (if auto-merge is enabled)
4. 4If all rules pass → the PR is scheduled for merge with the configured cooldown

When you request changes, the commit status is set to failure and a GitHub comment is posted with your feedback. The PR author sees the status and comment on GitHub without needing to visit MergeShield.

Organization owners and admins can also force-merge a PR that has a pending or rejected approval, or close the PR entirely — all from the governance banner on the PR detail page.

MergeShield maintains full bidirectional sync with GitHub for approvals. This means reviewers can work entirely from GitHub's familiar interface if they prefer — MergeShield stays up to date automatically.

GitHub → MergeShield:

• Approve a PR in GitHub (Files changed → Review changes → Approve) → MergeShield approval status updates to approved, commit status set to success, auto-merge re-evaluated
• Request Changes in GitHub → MergeShield approval status updates to changes_requested, commit status set to failure
• The review comment from GitHub is synced as the approval comment in MergeShield

MergeShield → GitHub:

• Approve in MergeShield dashboard → GitHub PR comment posted ("Approved by @reviewer via MergeShield")
• Request Changes in MergeShield → GitHub PR comment posted with reviewer's feedback
• Force-merge in MergeShield → PR merged on GitHub, supersedes any pending approval
• Close PR in MergeShield → PR closed on GitHub
• Reopen PR in MergeShield → PR reopened on GitHub

Back-and-forth review cycles are fully supported. In real development workflows, reviews often go through multiple rounds — a reviewer requests changes, the author pushes fixes, the reviewer approves. MergeShield handles these transitions seamlessly:

• Approved → Request Changes (reviewer spots new issues after approving)
• Changes Requested → Approved (reviewer approves after author fixes issues)
• Expired → Approved (reviewer responds after timeout)

All state transitions are recorded in the audit trail with the source noted (MergeShield or GitHub review).

For teams that need hard enforcement — where no PR can be merged without MergeShield approval — you should combine the approval workflow with GitHub branch protection rules. This ensures that even if someone tries to merge directly on GitHub (bypassing the MergeShield dashboard), GitHub itself will block the merge.

Here's how to set it up:

Step 1: Enable the approval workflow in MergeShield (Repository Settings → Approval Workflow → Enable). Configure your risk threshold, author type requirements, and escalation reviewers.

Step 2: Add branch protection on GitHub. Go to your repository on GitHub → Settings → Branches → Add rule for your main branch.

Step 3: Require the mergeshield/approval status check. In the branch protection rule, enable Require status checks to pass before merging and search for mergeshield/approval. Select it as a required check.

Step 4 (optional): Also require mergeshield/risk-check if you use the GitHub Action. This ensures every PR has a risk analysis before it can be merged.

Once configured, the merge flow becomes:

1. 1PR opened → MergeShield analyzes and sets pending status
2. 2If risk score exceeds threshold → approval required, GitHub blocks merge button
3. 3Reviewer approves — from MergeShield or GitHub (both sync automatically) → status updated to success
4. 4If auto-merge is enabled → PR merges automatically
5. 5If auto-merge is off → developer can now click Merge on GitHub

This creates a complete governance loop where every high-risk change must be approved, and reviewers can work from whichever platform they prefer — MergeShield or GitHub.

When a reviewer requests changes from MergeShield, the platform automatically extracts actionable suggestions from the existing risk analysis and posts them as structured action items on the GitHub PR. This feature works at zero additional cost — no extra Claude API calls — because the suggestions are derived from the analysis data that already exists.

The suggestions are extracted from two sources:

• Risk dimension findings — High-scoring categories (security, blast radius, test coverage, etc.) surface their most critical findings and suggestions
• File-level risks — Files with high risk scores surface their specific explanations as action items

Each suggestion appears as a checkbox in the GitHub review comment, formatted in a structured way that AI coding agents can parse and act on. An agent receiving a "Request Changes" review with these checkboxes can read each item and resolve them systematically.

The AI suggestions section appears in the Approval tab on the PR detail page. Reviewers can:

• Click Use to add a suggestion to their review comment (the button disables after use to prevent duplicates)
• Click Copy to copy the suggestion text to clipboard for custom editing
• Write their own comments in addition to the AI suggestions

The feature can be toggled on or off per repository in the Approval Workflow settings (Include AI suggestions toggle). When off, request-changes reviews post only the reviewer's comment without appended action items. Default is on.

Every approval record maintains a full history timeline of all actions taken — who did what, when, and from which platform. This provides complete transparency for audit and compliance purposes.

The history timeline appears on the Approval tab of the PR detail page and shows entries for:

• Created — When the approval requirement was first triggered, with the risk score
• Approved — Who approved, from which platform (MergeShield or GitHub), with any comment
• Changes Requested — Who requested changes, from which platform, with feedback
• Expired — When a pending approval timed out
• Superseded — When a force-merge or force-approval replaced the current status

Each entry shows:

• The action taken (with a color-coded icon)
• The actor who performed it
• A source badge indicating whether it came from MergeShield or a GitHub review
• The timestamp of the action
• Any comment attached to the action

For PRs that go through multiple review rounds (e.g., request changes → fixes pushed → approved → new issues found → request changes again), the timeline captures every transition. Previous approval rounds appear in a collapsible Previous Rounds section below the current approval.

The history is stored as an atomic JSONB array in the database — concurrent actions from MergeShield and GitHub never overwrite each other.

The AI-suggested action items are designed to close the loop between human reviewers and AI coding agents. When a reviewer requests changes on an agent-authored PR, the structured checkboxes give the agent a clear, parseable list of what needs to be fixed.

The feedback loop works like this:

1. 1Agent opens PR → MergeShield analyzes and identifies risks
2. 2Reviewer requests changes (from MergeShield or GitHub) → Structured action items posted on the PR
3. 3Agent reads the review → Parses the checkbox items and addresses each one
4. 4Agent pushes fixes → MergeShield re-analyzes, approval resets to pending
5. 5Reviewer approves → Auto-merge proceeds if configured

The checkbox format (- [ ] **category**: description) is intentionally simple and machine-readable. Most AI coding agents (Claude Code, Copilot, Cursor, Devin, etc.) can parse GitHub review comments and use the structured feedback to make targeted fixes.

This creates a virtuous cycle: agents get better feedback, produce better fixes, and over time their trust scores improve — leading to more auto-merges and less manual review overhead.

The agent feedback loop is particularly powerful when combined with auto-merge: once the agent addresses all feedback and the reviewer approves, the PR can auto-merge without any further human intervention.

MergeShield supports three distinct governance modes depending on how you combine approval workflows and auto-merge:

1. Advisory Mode (Approval ON, Auto-Merge OFF, No Branch Protection) MergeShield flags high-risk PRs and requests reviews, but developers can still merge freely on GitHub. The approval status is informational only. Best for teams starting out who want visibility without blocking workflows.

2. Soft Enforcement (Approval ON, Auto-Merge ON, No Branch Protection) Low-risk PRs are auto-merged. High-risk PRs require approval before auto-merge proceeds — reviewers can approve from MergeShield or GitHub. Developers can still bypass by merging directly on GitHub. Best for teams that trust their developers but want automated governance for the common case.

3. Hard Enforcement (Approval ON, Branch Protection ON) GitHub blocks the merge button until MergeShield approves. No PR above the risk threshold can be merged without explicit human approval — whether through auto-merge or manual merge on GitHub. Best for regulated teams, production repositories, or organizations with strict compliance requirements.

You can mix modes across repositories. For example, use hard enforcement on your production repo and advisory mode on internal tools.