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

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

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