View as Markdown View this page as plain text
Open Source · MIT License
Staqd

Staqd

/stakt/ — like "stacked"

Stacked PR merge queue powered by GitHub Actions and PR comments

View on GitHub → Get Started
↓

Quick Start#

Add a workflow file for each of the two events:

.github/workflows/staqd-auto-detect.yml

YAML 
name: Staqd Auto Detect

on:
  pull_request:
    types: [opened, edited, closed]

permissions:
  pull-requests: write
  issues: write

jobs:
  staqd:
    uses: siner308/staqd/.github/workflows/staqd-auto-detect.yml@v1

.github/workflows/staqd-command.yml

YAML 
name: Staqd Command

on:
  issue_comment:
    types: [created]

permissions:
  contents: write
  pull-requests: write
  issues: write
  checks: read

jobs:
  staqd:
    uses: siner308/staqd/.github/workflows/staqd-command.yml@v1

Commands#

Comment on a PR to trigger actions. All commands support the short alias st (e.g., st merge).

stack discover #

Auto-detect the stack tree by scanning open PRs' base branch relationships. No manual metadata setup needed.

When to use After creating stacked PRs, or when you re-target a PR's base branch to form a new stack
What it does Recursively finds child PRs via base branch, updates metadata in each PR body, and reports if any children need restacking
Example output 
- #1 (feat-auth) → #2
  - #2 (feat-auth-ui) → #3 ⚠️
    - #3 (feat-auth-tests)

⚠️ Some PRs are out of date.
Run st restack on the parent PR.
stack restack push #

Restack entire stack recursively — rebases all descendant branches in topological order. Use after pushing new commits to a parent PR.

When to use After updating a parent PR with new commits, or when st discover shows ⚠️ indicators
What it does Auto-discovers the stack, then runs git rebase --onto for each descendant branch in topological order. Stops recursing into subtrees on conflict and posts resolution commands
stack merge merge + push #

Auto-discover the stack tree, merge this PR into its base branch, then automatically restack all child branches.

When to use When this PR is approved and ready to merge, but child PRs still need more work
What it does Runs discover to refresh stack metadata, squash-merges the PR, rebases children onto the base branch (e.g., main), and updates each child's base branch reference
stack merge-all merge + push #

Auto-discover the stack tree, then merge the entire stack in DFS order. Each PR is rebased, merged, then its children are processed.

When to use When the entire stack is reviewed and approved — merge everything at once
What it does Runs discover to refresh stack metadata, checks approval status on all PRs, then sequentially rebases and merges each one. Retries up to 10 min per PR for CI to pass
Options Add --force to skip the approval check (e.g., st merge-all --force)
stack help #

Show available commands and the current stack structure detected from metadata.

Auto-update on Manual Merge#

Merged a parent PR through GitHub UI instead of st merge? Staqd has you covered.

When a parent PR with stack metadata is merged (by any method), Staqd automatically detects the closed event and:

Base update Each child PR's base branch is re-targeted to the parent's base (e.g., main), preventing orphaned PRs
Notification A comment is posted on each child PR with the updated base and a reminder to run st restack if needed
Requirement Add closed to your workflow's pull_request.types: [opened, edited, closed]

How It Works#

Everything reduces to one elegant git command:

git rebase --onto <new_base> <old_parent_tip_sha> <child_branch>
Before (feat-1 squash-merged into main): 
main:     A───B───CD'          (C+D squashed into new commit)
feat-2:       C───D───E───F    (still contains original C, D)
After rebasing: 
git rebase --onto main <SHA_of_D> feat-2

main:     A───B───CD'
                    \
feat-2:              E'───F'   (C, D removed; only E, F rebased)

The skip SHA (old_parent_tip_sha) comes from GitHub's PR API, which preserves head.sha even after merge. No database needed.

Comparison#

How Staqd compares to other stacked PR tools

Staqd Graphite ghstack
Installation None (workflow file) CLI + account CLI
Stack storage PR body HTML comments .graphite_info + server Commit metadata
Restack trigger PR comment gt restack CLI ghstack CLI
Conflict resolution Async (Actions → local fix → push) Sync (terminal) Sync (terminal)
Tree stacks Supported (siblings) Supported (DAG) Linear only
Merge queue Comment-based Dedicated UI None
External dependency None SaaS None
Link copied!