Cross-repository stacked pull requests: user-defined, reorderable ordering gated per layer

[StephenHodgson]

Summary

Native stacked PRs are excellent, but they're scoped to a single repository. A lot of real
change spans multiple repositories at once (an engine, an app, content packages, shared
libraries, services...). Today that has to be split into independent PRs in each repo with no
first-class ordering, gating, or "merge the stack" semantics tying them together.

I'd love cross-repo stacks where the author freely arranges any set of PRs across repositories
into an ordered stack, reorders them at will, and each layer merges once its own gates pass.
The stack is just an explicit, editable order the author declares; GitHub shouldn't assume which
repo is "lower" or infer a fixed direction from the dependency graph.

Why order must be user-defined, not inferred

The correct merge order isn't a property of the dependency tree; it's a property of the change
and the team's release process. For the same set of repos, one change ships the content package
first, another ships the engine first, another lands the app last as the integrator. Tooling
that hard-codes "downstream depends on upstream, so merge upstream first" gets it wrong half the
time. What's actually invariant is: a layer may merge only when its gates are green (required
checks, approvals, and any declared "depends-on" PRs already merged). Given that, the author
should be able to place PRs in whatever order makes sense and reorder freely.

Motivating shape

A cross-repo stack is an ordered list of PRs, each in its own repo, each with its own gates:

graph BT
    subgraph rC["org/repo-c"]
        C["PR (layer 3)"]
    end
    subgraph rB["org/repo-b"]
        B["PR (layer 2)"]
    end
    subgraph rA["org/repo-a"]
        A["PR (layer 1)"]
    end

    A -->|"gates green, then unblocks next"| B
    B -->|"gates green, then unblocks next"| C

    classDef node fill:#eef2ff,stroke:#3b6fd4;
    class A,B,C node;

Loading

The order above (a -> b -> c) is just one arrangement the author chose. Any PR can be dragged to
a different position; the stack re-gates from the new order. What never changes is that a layer
can't merge until everything ahead of it in the current order has merged and each of its own
gates passes.

sequenceDiagram
    autonumber
    participant Dev as Author
    participant L1 as layer 1 PR
    participant L2 as layer 2 PR
    participant L3 as layer 3 PR

    Dev->>L1: Arrange PRs into a stack (order is editable)
    Dev->>L2: ...
    Dev->>L3: ...

    Note over L2,L3: later layers gated FAIL until earlier layers merge + their own gates pass

    L1-->>L1: Gates pass (checks + approvals + depends-on)
    L1->>L2: Merge layer 1, re-evaluate the rest
    L2-->>L2: Gates pass
    L2->>L3: Merge layer 2, re-evaluate the rest
    L3-->>L3: Gates pass
    L3->>L3: Merge layer 3, whole stack landed in the chosen order

    Note over Dev,L3: at any point the author can reorder unmerged layers and the stack re-gates

Loading

What we do today (and why it's not enough)

• Manual "Depends-on:" / "Blocked by:" notes in PR bodies: no enforcement, easy to merge out
  of order.
• Third-party tools to fill the gap: e.g. gating apps like PRereq, and CI actions like
  gregsdennis/dependencies-action and depends-on/depends-on-action that parse the PR body
  and fail a required check until referenced cross-repo PRs are merged (some also fetch +
  cherry-pick the dependent PRs so CI builds against the combined code).
• These work but are bolted on: no shared "stack map" UI across repos, no author-defined
  reorderable order, no one-click ordered merge, and gating quality varies by tool.

What I'm requesting

• A stack that can contain PRs from different repositories in an author-defined, editable
  order (drag to reorder; no assumed direction).
• Per-layer gating: a layer merges only when its own gates are green (required checks,
  approvals) and every layer ahead of it in the current order has merged. Ideally declared
  cross-repo "depends-on" links feed into this as a first-class required check, not a bespoke
  Action.
• Reorder + re-gate: reordering unmerged layers is supported and simply re-evaluates gates
  against the new order.
• A cross-repo stack map visible on every member PR so reviewers see the whole stack and its
  current order.
• Optional version/ref coordination hooks: when a layer merges (and optionally a tag/release
  is produced), signal or assist the retarget/ref-bump of the next layer.
• Webhook/REST/GraphQL parity with single-repo stacks so all of this is automatable.

Why this fits the stacks model

Single-repo stacks are already an ordered series of PRs merged in sequence with automatic
retarget. Generalizing to cross-repo just means (1) members can live in different repos and (2)
the order is explicit and editable rather than implied by a single repo's branch chain. Everyone
splitting work across services, shared libraries, engines, and content packages hits this, and
it's exactly the AI-agent-heavy, high-volume workflow stacks are pitched for.

Acknowledged hard parts (not blockers, just flagging)

• Permissions/branch-protection differ per repo; gating must respect each repo's own rules.
• "Merge the whole stack" across repos needs per-repo required-check satisfaction, and
  versioning (tag/publish) may need to happen between layers rather than in one atomic op.
• Cross-fork was intentionally excluded; cross-repo-within-an-org would be the pragmatic first
  step.

Even a read-only "cross-repo dependency + explicit order" primitive with an official required
check would be a big improvement over the current third-party patchwork.

Thanks for shipping stacks; it's already a big quality-of-life win. Cross-repo, with a freely
orderable stack gated per layer, would make it usable for teams whose "large change" is
inherently spread across several repositories.