PR Dependencies

← Back to Features

Enforce merge order for dependent or stacked PRs. Block child PRs from merging until parent PRs are complete.

Overview

Teams often create dependent PRs:

Stacked PRs: Feature broken into sequential parts (Part 1 → Part 2 → Part 3)
Infrastructure dependencies: App changes depend on infra deployment
Ordered rollouts: Backend first, then frontend

Without dependency management:

❌ Child PRs merge before parents, breaking main
❌ Manual coordination required
❌ No automatic blocking

With MergeGuard PR Dependencies:

✅ Automatic detection via PR description or base branch
✅ Child PRs blocked until parent merges
✅ Clear status checks showing dependency state

How to Declare Dependencies

Method 1: Explicit Syntax (Preferred)

Add dependency syntax to PR description:

This PR implements feature X.

Depends on #123

Changes include:
- Implementation details...

Supported syntax:

Depends on #123
Depends-on: #456
Blocked by #789
Requires #321

Method 2: Stacked PRs (Automatic)

MergeGuard automatically detects stacked PRs when the child’s base branch matches the parent’s head branch:

main ← PR #100 (feature-part-1) ← PR #101 (feature-part-2)

Detection:

PR #101’s base is feature-part-1
PR #100’s head is feature-part-1
→ MergeGuard detects #101 depends on #100

How It Works

1. Dependency Detection

When a PR is opened/updated, MergeGuard:

Parses PR description for dependency syntax
Checks if base branch matches another open PR’s head branch
Stores dependency information

Priority: Explicit syntax (PR body) > base branch detection

2. Status Check Update

MergeGuard creates a Check Run showing:

✅ No dependencies → “Ready to merge (when requirements met)”
⚠️ Dependency unmerged → “Waiting for #123 to merge”
✅ Dependency merged → “Ready to merge (when requirements met)”

3. Merge Blocking

If a dependency exists and is not merged:

❌ MergeGuard Check Run fails
❌ PR cannot merge (even if other requirements are met)
❌ Auto-merge is paused

When dependency merges:

✅ MergeGuard Check Run updates
✅ If all other requirements met → PR can merge
✅ Auto-merge resumes (if configured)

Use Cases with Examples

1. Stacked Feature Development

Break large features into sequential PRs:

# PR #100: Feature Part 1 - Database Schema
Base: main
Head: feature-part-1

# PR #101: Feature Part 2 - API Endpoints
Base: feature-part-1  ← depends on #100
Head: feature-part-2

Depends on #100

# PR #102: Feature Part 3 - Frontend UI
Base: feature-part-2  ← depends on #101
Head: feature-part-3

Depends on #101

Result:

#100 can merge anytime
#101 blocked until #100 merges
#102 blocked until #101 merges
Clean, ordered merge sequence

2. Infrastructure → Application Deployment

Ensure infra is deployed before app changes:

# PR #200: Add Redis Cache Infrastructure
(normal PR to main)

# PR #201: Use Redis Cache in Application
Depends on #200

This PR uses the Redis cache deployed in #200.

Result: Application changes can’t merge until infrastructure is deployed.

3. Backend → Frontend Rollout

Deploy API changes before UI that consumes them:

# PR #300: Add New API Endpoint
(normal PR to main)

# PR #301: Frontend UI for New Endpoint
Depends on #300

This PR uses the API endpoint added in #300.

Result: Frontend can’t merge until backend is live.

4. Database Migration → Code Change

Ensure schema changes deploy first:

# PR #400: Add user_roles Table
(migration PR)

# PR #401: Use user_roles in Auth Service
Depends on #400

This PR queries the user_roles table added in #400.

Result: Code using new schema can’t deploy until migration runs.

5. Multi-Repo Coordination

Use dependency syntax to reference external state:

# PR in App Repo
Depends on MergeGuard/infra-repo#50

This PR requires the infrastructure changes in infra-repo#50.

Note: MergeGuard currently only detects same-repo dependencies. External dependencies are tracked manually via description but not enforced.

6. Auto-Merge with Dependencies

Combine dependencies with auto-merge for fully automated stacks:

- name: "Stacked PR automation"
  if:
    labels: ["stack"]
  require:
    approvals: 1
    checks: ["unit-tests"]
  action:
    autoMerge:
      requireChecks: true

Workflow:

Create stack of PRs, each depending on previous
Label all with stack
Review and approve all PRs
As each PR’s requirements + dependency are met → auto-merge
Entire stack merges in order automatically

Merge queue note: if the target branch uses GitHub merge queue, the dependency behavior is the same, but the queue performs the final merge step after the PR reaches the queue.

Configuration

Dependencies work with all rules—no special configuration needed:

rules:
  - name: "Default policy"
    require:
      approvals: 2
    action:
      autoMerge:
        requireChecks: true

Behavior:

If PR has dependency → blocked until parent merges
Once parent merges + requirements met → auto-merge proceeds

On merge-queue branches, read that as “the PR becomes ready for the queue’s final merge stage” rather than “MergeGuard performs a direct merge call.”

Check Run Messages

Dependency Unmerged

⚠️ MergeGuard: Waiting for dependencies

This PR depends on #123, which must be merged first.

Dependency status:
- #123 "Add Redis infrastructure" - OPEN (not merged)

Once #123 merges and all requirements are met, this PR can merge.

Dependency Merged

✅ MergeGuard: Ready to merge

All dependencies satisfied:
- #123 "Add Redis infrastructure" - MERGED ✅

Requirements:
- Approvals: 2/2 ✅
- Checks: all passed ✅

Best Practices

1. Prefer Explicit Syntax Over Base Branch Detection

Use Depends on #123 in PR description for clarity:

✅ Visible to reviewers
✅ Works regardless of branch strategy
✅ Self-documenting

2. Keep Stacks Shallow

Avoid deep dependency chains (>3 levels):

❌ Hard to manage
❌ Blocks everything if first PR needs changes
❌ Reviewers lose context

Better: Break into smaller, independent features when possible.

3. Review All PRs in Stack Together

When creating a stack:

Open all PRs at once
Request reviews on all PRs
Reviewers see full context
Address feedback across stack

4. Use Labels for Stack Management

Label related PRs:

labels: ["stack-feature-x"]

Makes it easy to filter and track the stack.

5. Communicate Intent in PR Descriptions

Explain why the dependency exists:

Depends on #123

**Why:** This PR uses the Redis cache infrastructure deployed in #123.
Without #123 merged first, this code will fail in production.

Limitations

Same-Repo Only

MergeGuard currently only enforces dependencies within the same repository.

Workaround for multi-repo:

Use dependency syntax for documentation
Manually coordinate merge timing
Consider monorepo or Git submodules

Circular Dependencies Not Supported

PR #100 depends on #101
PR #101 depends on #100

Result: Both PRs permanently blocked.

Prevention: MergeGuard doesn’t prevent circular dependencies. Teams must avoid them.

Closed/Merged Dependency Detection

If parent PR is closed without merging, child is still blocked.

Resolution: Remove dependency from child PR description, or reopen parent.

Troubleshooting

Dependency Not Detected

Check:

Syntax is correct: Depends on #123 (case-insensitive)
Dependency is in PR description, not just a comment
PR number is correct and PR exists
For stacked PRs: base branch exactly matches parent’s head branch

Debug: Check MergeGuard Check Run details—it shows detected dependencies.

PR Still Blocked After Parent Merges