Task dependencies
Make one task wait for another, choose when the wait ends, stack a dependent on its upstream's open merge request, and manage dependencies in the app.
A dependency says “this must land before that”. The task that waits is the dependent. The task it waits for is the upstream. This page covers how a dependency gates work, the three conditions that release it, and Stacked dependencies.
What a dependency does
While a dependency is unreleased, CodeHerder gates every move of the dependent into a working stage, planning included. It also holds the dependent out of staffing. Some moves stay allowed:
- Moving the task straight to a finished stage.
- Block, cancel and archive.
- A reopen into
todo.
A reopen into a working stage such as plan or code waits until every dependency is released. See Reopening a cancelled or completed task.
A dependency is the one way to wait on a task. To wait on anything else, such as a person, a release or access, file a blocker with a resume condition. See Blockers and blocked tasks.
Choosing when a dependency releases
Each dependency has a release condition. It sets the moment the dependency stops gating the dependent. The default is done.
| App label | CLI value | The dependency releases when |
|---|---|---|
| Upstream is done | done |
The upstream reaches a finished stage. |
| Upstream is planned | planned |
The upstream reaches its workflow’s planned stage. |
| Upstream opens its merge request | mr_opened |
The upstream opens its merge request. Needs Stacked dependencies. |
A finished upstream always releases the dependency, whatever the condition. Reaching done counts, and so does being cancelled or archived. What matters is that the upstream has stopped changing state, not that it succeeded.
Upstream is planned
Only some workflows mark a planned stage. Of the built-in workflows, the initiative and epic workflows do: their in_progress stage is the planned stage. Use this condition when the dependent needs the upstream’s child tasks to exist, but not to be finished.
A story, bug, feature or task upstream has no planned stage. A planned dependency on one of them waits for done.
Upstream opens its merge request
This condition works only while Stacked dependencies is on in the workspace. It also needs a workflow with a merge stage on the dependent. The built-in story, bug, feature and task workflows have one. Without both, the dependency waits for done. See Stacked dependencies below.
Release warnings
CodeHerder saves the dependency in every case. If the condition you chose cannot release early, CodeHerder says so:
- “The upstream’s workflow marks no planned stage, so this edge waits for done.”
- “Stacked dependencies is off in this workspace, so this edge waits for done.”
- “The dependent’s workflow has no merge stage milestone, so this edge behaves like done and waits for done.”
The web app shows the warning as a toast when you add a dependency on the task’s page. The CLI prints it in the output of ch task depends-on, ch task deps create and ch task create.
A release stays released
A release is permanent. Say a planned dependency has released, and the upstream later moves back to a stage before its planned stage. The dependency stays released. CodeHerder posts a comment on the dependent, so the next agent or person can check that the work does not rely on the upstream’s planned children. Moving the upstream to blocked does not count as moving back.
When an upstream is cancelled or archived
If an upstream is cancelled or archived instead of completed, its dependents are still released. CodeHerder makes sure the missing work gets noticed:
- A comment appears on the dependent saying the upstream’s work did not land and the task is no longer gated on it.
- Watchers who receive status-change notifications are messaged.
- The event shows up on the task’s activity feed.
CodeHerder files no blocker and does not hold up staffing. The next agent, or you, decides whether the task can still do useful work.
Automatic dependency notes
While a task has an unreleased dependency, CodeHerder holds it back from staffing. It files a note on the task that names the first unreleased upstream. The task keeps its status, normally todo. The note clears itself once every dependency is released.
On the task’s page, a Waiting on dependencies box lists the upstreams that still gate the task. A Waiting on N badge sits by the title. Both disappear when the last dependency releases. See Blockers and blocked tasks.
Adding a dependency to a task already underway
Set dependencies before work starts where you can. Say you add a dependency to a task that has left its starting stage, and the new dependency is not yet released. CodeHerder pulls the task back. It retires the live session, discards that session’s in-progress work, and returns the task to its starting stage. Once the dependency releases, the task restarts from current main with a fresh plan. This reset is intended. A task that is already finished is left alone.
Stacked dependencies
Stacked dependencies lets a dependent start on its upstream’s open merge request, instead of waiting for the upstream to merge. It suits a chain of changes that build on each other. The setting is off by default.
Turn it on
A workspace admin turns it on in one of two ways:
- In the web app, open Settings → General and check Stacked dependencies.
- From the CLI, run
ch workspace edit <workspace> --stacked-dependencies on.
The setting belongs to one workspace. Child workspaces do not inherit it. To turn it off, clear the checkbox or pass --stacked-dependencies off.
When you turn it on in the app, CodeHerder checks your repos’ merge settings and lists any that work against stacked branches. The check never refuses the change. You can run it again at any time:
ch workspace stacking-check [<workspace>]
The check looks for these settings:
| Git host | Setting that works against stacking |
|---|---|
| GitLab | Squash merge is on by default, or is required. |
| GitLab | Delete source branch after merge is off by default. |
| GitHub | Automatically delete head branches is off. |
| GitHub | Only squash merge is allowed. |
A repo CodeHerder cannot read gets a warning instead.
What happens to a stacked dependent
Add a dependency with the Upstream opens its merge request condition. Once the upstream opens its merge request, the dependency releases. Then:
- The dependent starts early. It starts on the upstream’s branch, and its merge request targets that branch.
- Its merge stage waits. The dependent can reach its merge stage, but it does not start there until the upstream merges. Meanwhile CodeHerder gives “This task’s merge stage waits for its stacked upstream task to merge.” as the reason the task is not running.
- It moves to the new base after the merge. Once the upstream merges, the agent in the dependent’s merge stage checks the merge request’s target. If the target is still the upstream’s branch, the agent retargets it to the base. If the host squash-merged the upstream, the agent also rebases the branch onto the base.
A dependent stacks on one upstream at a time. If it has several mr_opened dependencies, it stacks on the first one to release. The others wait for done. Only a repo where the upstream has an open merge request stacks. The dependent’s other repos keep their usual base.
Keep stacks shallow, about three tasks deep. A deep stack means more rebases after each merge.
When the upstream is lost
An upstream is lost when it is cancelled, or when every merge request it awaits is closed without a merge. Then CodeHerder files a note that starts with “stacked upstream lost” on each live dependent. The note names the upstream and asks a person to decide. The dependent stays parked until someone chooses one of these:
- Retarget the dependent’s merge request to its base, rebase it, and remove the dependency.
- Replace the dependency with another task.
- Cancel the task.
If the upstream’s merge request reopens, CodeHerder clears the note by itself. An upstream sent back to an earlier stage with its merge request still open is not lost.
Managing dependencies in the web app
- Depends on lists upstream tasks. Each row shows the status, priority and title of the upstream. A Releases when column shows the release condition, with “(released)” once it releases.
- Click Add dependency to pick an upstream task. Use the Release when select to choose the condition.
- Remove asks you to confirm, then drops the dependency.
- Dependents lists downstream tasks. It is read-only and appears only when one exists.
On the New Task page, pick upstream tasks in the Depends on field. A Release when select then sets the condition for all of them. The server rejects self-dependencies, cycles, and going over the limit on dependencies per task.
To see the whole picture, switch the Tasks page to the Graph view.
Managing dependencies from the CLI
ch task create --title "..." --depends-on <upstreamTaskId> # repeat the flag for more
ch task depends-on <taskId> <upstreamTaskId> # add a dependency
ch task depends-on <taskId> <upstreamTaskId> --release-when mr_opened
ch task undepend <taskId> <upstreamTaskId> # remove it
ch task deps <taskId> # list upstream dependencies
ch task dependents <taskId> # list downstream dependents
--release-when done|planned|mr_opened sets the release condition. On ch task create, it needs --depends-on and applies to every --depends-on dependency. ch task deps shows each dependency’s release condition and release time.
depends-on, undepend and dependents are frozen aliases of ch task deps create, delete and dependents. See Managing a record’s child collections.
Related guides
- Blockers and blocked tasks: every way a task gets a blocker, and how each clears
- Why isn’t my task moving?: diagnose a task that waits on a dependency
- Understanding the task hierarchy: how dependencies differ from parent and child tasks
- Collaborating: comments, hand-off notes and mentions
Last updated