Help Center

ZenHub dependencies help teams get better end-to-end visibility for issues and stories when moving projects forward. This information give teams a stronger understanding about why a block is occurring and what is needed to move initiatives forward with less risk.

Get familiar with ZenHub dependencies

A dependency is a project management term used when referring to a piece of software, code, or task that relies on another one before it can be considered ready to be worked on.

Here's an example: Issue X uses the framework from Issue Y.

X depends on Y. Y is a blocker for X. This creates a dependent relationship between X and Y.

Dependencies provide teams a bird's eye view of all tasks and related work that must be completed.

Why are dependencies important to track?

Dependencies give teams a visualization of task relationships within a project. A poor decision made due to lack of full visibility into dependent work can have expensive consequences and delay releases. Tracking dependent work help teams stay ahead of compatibility problems and future Issues that end up setting deadlines back

Even if your team has a process and framework for talking through Dependencies for upcoming sprints and iterations, a lot of time gets spent managing day-to-day work. Relying solely on meetings to uncover important connections between pieces of work not only takes time away from teams to get actual development done, but risks information not surfacing that is critical to pushing projects forward. Competing priorities, differing schedules, teams working autonomously on the same project, and unforeseen bugs: All examples of work that can result in delays and teams spending more time figuring out the details of a project than actually releasing software.

For example, Team X and Team Y are both working on a new infrastructure change for your product. Team X creates a dependency on Team Y, because they must finish the foundational work on the infrastructure before Team X can start polishing the code. Managing deadlines cross-teams, cross-repos, and even sprint-over-sprint can mean important information gets lost.

ZenHub dependencies provide the ability to raise cross-team relationships using GitHub issues and pull requests in a central location. This facilitates end-to-end communication and collaboration to mitigate potential risks surrounding important deadlines and objectives.

Creating and managing dependencies

ZenHub supports two Dependencies:

  • Issues can be Blocked by other issues
  • Issues can be Blocking other issues

To add Dependencies to GitHub issues or pull requests, get started by heading to a GitHub issue. Below the initial description/comment of the Issue you will see the add dependency button. To get started, search for the issue or pull request that is a blocker for the Issue you are working on to indicate that it is Blocked by another piece of work. If instead, the issue is a blocker for another Issue, you can select Blockingwhen adding a dependency:

Creating Cross-Workspace Dependencies

You can also create cross-workspace dependencies to show Issues rely on Issues outside of this particular Workspace. To set up a dependency with Issues outside of the Workspace, click the add dependency button when viewing an Issue. From here, enter into the search bar the @orgname/repo and query the issue title you'd like added:

Once dependencies are added, all issues or pull requests that are blocked by other issues or pull requests will have a new banner displayed at the top of the issue indicating what the blockers are. A new badge, Blocked, will also appear at the top of the issue next to the open/close status indicator:

When repos belong to more than one Workspace dependencies may display Not in this Workspace for dependent issues that are not a part of a repo in the current Workspace. Issues within the current Workspace will continue to show their respective pipeline name. 

Unblocking Issues and Pull Requests

Issues and pull requests are no longer considered a blocker when they are closed. Once closed, the dependency list will be updated with the issue's closed status. When an issue has no more blockers, but is still blocking other issues the status at the top of the dependency list will be updated to indicate that the Issue is blocking other issues.

If the issue is no longer blocking any other work and is free from blocking any work itself, the issue will indicate that it is ready to go!

Use Dependencies and Sprints together to stay ahead of important deadlines

Teams can better forecast deadlines and proactively tackle roadblocks by getting a top level view of key dates and events associated with projects using sprints with dependencies. Sprints and dependencies help teams to visualize dependent risks while also knowing how they are burning down towards a deadline.

If a dependent relationship is no longer needed, you can remove the connection on either Issue using the remove option on the right-hand side of the dependency list.

Removing a dependency

Tracking dependency changes in the issue history

For all dependencies being added or removed events will be logged in the issue history for reference.

issue change tracking for dependencies

Viewing dependencies on the Board

When dependencies get added to issues, you can view that dependency directly from the Board. Four different icons will appear across your Issues as dependencies get added:

  • Dependencies on ZenHub BoardsThis issue is blocked by other Issues
  • Dependencies on ZenHub BoardsThis issue is blocking another Issue
  • Dependencies on ZenHub BoardsIssue is blocked by another issue, as well as blocking an issue
  • Dependencies on ZenHub BoardsWhen a question mark appears on an issue, it indicates that a dependency exists but it is being filtered out.

You can filter by a dependency to show all the issues that belong to the dependency tree of the selected issue.

To filter the Board, you can either: Use the View Board option within the issue, under the dependency section

Dependencies on ZenHub Boards

Or, click the dependency icon on the issue’s dependency icon from the Board, selecting Filter by this Issue’s Dependencies

Once filtered, the Board will show you that issue’s dependency tree and where in your workflow each issue is. A legend will also appear, indicating what each dependency indicator means based on how actionable each issue is.

  • Blocking other issues We recommend teams to work on these issues first, as they are not blocked, but preventing work on other issues
  • Blocked and blocking issues If it is possible to start working on these at the same time as the issues that are blocking them, finishing these issues will help clear up completely blocked issues. As their blockers get closed, they will be unblocked and prioritized
  • Blocked These issues should be lower priority as other Issues are blocking them so they are not immediately actionable. Best practice to get these issues ready for development, so once unblocked, they can be actionable sooner

Dependencies on ZenHub Boards

Filtering out dependencies on Board issue cards

Similar to filtering out labels, estimates, or epics from the issue card data, dependencies can also be filtered off. This will remove the status indicators in the top right of blocked/blocking issues. Filtering these off only impacts your view, it won't change the view of others in your team.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.