The app
Stacks and dependencies
How riff shows stacked PRs and Jira dependency links, and what merges first.
Stacked PRs and Jira links tell you what has to land before a PR can. Riff reads both, folds a stack into one row, and warns before you merge out of order.
Stacked PRs
A stack is a chain of PRs where each builds on the one below it. Riff finds one two ways:
- GitHub’s native stacks (made with the
gh-stackextension), when GitHub knows the stack. - Base-branch chains: a PR whose base branch is another open PR’s head branch.
In the PR list a stack is one row, listed base first. It sits in the section of its most
urgent PR, with a summary such as “1 CI failing · 2 ready”. Press x to expand it to every
layer. A PR waiting on the one below shows “Approved · waits on #123”.
The stack bar
On a PR page, a bar under the tabs shows the stack with this PR marked. Each layer has a
state: Merged, Closed, Draft, Approved, Changes or Open. Click a layer to go to it.
Long stacks fold merged layers, then distant layers, into one entry that opens a menu. On the
Summary and Review tabs, [ and ] move to the layer below and above. The Jira card in the
details column also lists the nearest layers under Same stack.
The Summary tab adds an Order gate, “Merges after the layer below it”, with a card for that layer. It is shown while the layer below is not merged.
Jira dependency links
When a PR names a Jira ticket in its branch or title, riff reads the ticket’s links. Set Jira up in Jira.
| Link | Meaning |
|---|---|
| Blocked by | These tickets must ship before this PR |
| Blocks | These tickets wait on this PR |
| Duplicates, Relates to | Listed together under Relates to on the PR’s Jira card, never waited on |
Each linked ticket shows its PRs and a stage:
| Stage | Meaning |
|---|---|
| Open | A PR is still open |
| Merged | PRs merged, ticket not done yet |
| Released | The ticket has shipped |
| No PR | No PR is known for it |
A ticket has shipped when its status is one of your configured released statuses, or, if you set none, when it is in Jira’s Done category.
The Deps slot
The status line of every row, and the PR header, has a Deps slot:
- Waits on api #8133 (warning): a blocker has not shipped. The PR’s next step says “Waits on …” when nothing else holds it.
- Unblocks API-12 (info): other tickets wait on this PR.
The PR page shows the same as gates:
- Depends: “Blocked by 2 tickets that have not shipped”, with a card per blocker and its PR. It turns green when every dependency is released.
- Unblocks: tickets waiting on this one.
If tickets block each other in a loop, the epic grouping flags it instead of ordering them (see below).
Merge guard
Merging a PR whose ticket still has unshipped blockers asks first, and Merge anyway is your call. See Pull requests.
Group by epic or team
The list’s Group by control has three modes:
- Sections: the default ranking by what needs you.
- Epic: PRs grouped under their Jira epic, each epic in merge order. “No epic” comes last.
- Team: PRs grouped under the Jira team of their ticket, your team first. “No team” comes last.
Merge order
Inside an epic, PRs are listed in the order they have to merge. A PR merges after:
- its base PR, when it is a layer of a stack, or
- the PRs of tickets that block its ticket, which must be released first.
Each row says which earlier steps it follows. If the epic’s PRs wait on each other in a loop, riff shows a warning and falls back to the list’s own order.
Grouping works from tickets riff has already read. A PR with no ticket lands under “No epic” or “No team”.
From the terminal
riff pr status owner/repo#42 # deps and stack of one PRriff pr inbox --all --group epic # each epic in merge orderriff pr inbox --all --group teamriff pr merge 42 --ignore-deps # skip the merge guardSee riff pr for the JSON shape.