How do I create issue dependencies?
Track blocking relationships between issues and pull requests to improve project visibility and prevent delays.
What are dependencies and why track them?
Dependencies represent relationships between issues where one piece of work must be completed before another can begin. When Issue X depends on Issue Y, this means Y is a blocker for X and must be finished first.
Tracking dependencies gives teams visibility into task relationships within projects. Without this visibility, poor decisions can have expensive consequences and delay releases. Dependencies help teams stay ahead of compatibility problems and identify potential bottlenecks before they impact deadlines.
Consider this scenario: Team X and Team Y are both working on infrastructure changes. Team X creates a dependency on Team Y because the foundational infrastructure work must be completed before Team X can polish their code. Managing these cross-team, cross-repository relationships ensures important information doesn't get lost between sprints or competing priorities.
Types of dependencies in Zenhub
Zenhub supports two dependency relationships for GitHub issues and pull requests:
Blocked by: The current issue cannot proceed until another issue is completed. This indicates the current issue is waiting on external work.
Blocking: The current issue must be completed before other issues can proceed. This indicates other work is waiting on the current issue.
These relationships work bidirectionally - when you mark Issue A as blocked by Issue B, Issue B automatically shows as blocking Issue A.
Creating dependencies
To add dependencies to any GitHub issue or pull request, navigate to the issue and look for the "Dependencies" section beneath the initial description and comments.
Adding a blocking relationship: Click the "Blocked by" button to search for issues or pull requests that are blocking the current work. Type the issue title or number in the search field to find the blocking item. Select the appropriate issue to create the dependency relationship.
Adding a blocking relationship: Use the dropdown menu to switch from "Blocked by" to "Blocking" when the current issue prevents other work from proceeding. Search for and select the issues that are waiting on the current work to be completed.
Cross-repository dependencies: Dependencies work across repositories within your workspace. You can create blocking relationships between issues in different repositories, providing visibility into cross-team work that spans multiple codebases.
Dependency status and resolution
Dependencies automatically update based on issue status changes, providing real-time visibility into blocking relationships.
Active blocking: When issues have active blockers, the dependency section shows which specific issues are preventing progress. Each blocking issue displays its current status and provides a direct link for easy navigation.
Automatic unblocking: Issues and pull requests are no longer considered blockers when they are closed. Once closed, the dependency list updates to reflect the resolved status, automatically unblocking dependent work.
Status indicators: The dependency section displays clear status messages:
- "Issue is ready to go" when all blockers are resolved and the issue isn't blocking other work
- "Blocked by [X] issues" when active blockers remain
- "Blocking [X] issues" when the current issue prevents other work from proceeding
Managing dependencies
Removing dependencies: If a dependency relationship is no longer needed, click the "Remove" option on the right side of any dependency in the list. This removes the connection from both issues involved in the relationship.
Dependency history: All dependency additions and removals are logged in the issue history for reference. This provides an audit trail of how blocking relationships have changed over time.
External dependencies: Dependencies can be marked as "External" when they represent work outside your GitHub repositories. This provides visibility into third-party blockers or external team commitments that impact your project timeline.
Viewing dependencies on the Work Tracker
Dependencies are visually represented on your Work Tracker board with clear iconography:
Issue status indicators:
- Blocked issue icon: Shows when an issue is blocked by other work
- Blocking issue icon: Indicates the issue is blocking other work from proceeding
- Both blocked and blocking icon: Displays when an issue has both types of relationships
These visual indicators help teams quickly identify bottlenecks and prioritize unblocking work during sprint planning and daily standups.
Filtering dependency indicators: You can filter dependency icons off issue cards if you prefer a cleaner view. This only affects your personal view and doesn't change what other team members see. Use the board filtering options to show or hide dependency status indicators.
Dependencies and sprint planning
Dependencies integrate with sprint planning to help teams forecast deadlines and proactively address roadblocks.
Sprint risk assessment: When planning sprints, review dependency relationships to identify potential risks. Issues with many blockers may not be suitable for the current sprint, while blocking issues should be prioritized to unblock downstream work.
Cross-sprint dependencies: Dependencies help visualize work that spans multiple sprints. When blocking issues are scheduled for later sprints, teams can adjust their planning to account for the dependency chain.
Capacity planning: Consider dependency relationships when estimating sprint capacity. Blocked issues may not contribute to velocity until their blockers are resolved, affecting team throughput calculations.
Best practices for dependency management
Create dependencies early: Add dependency relationships as soon as they're identified, ideally during backlog grooming or sprint planning. This provides maximum visibility for planning and prioritization decisions.
Keep dependencies current: Regularly review and update dependency relationships as work progresses. Remove outdated dependencies and add new ones as requirements evolve.
Communicate blocking work: Use dependency relationships to facilitate cross-team communication. When creating dependencies on other teams' work, ensure those teams understand the downstream impact of delays.
Balance granularity: Create dependencies for significant blocking relationships that impact sprint planning or release timelines. Avoid over-documenting minor dependencies that don't require coordination.
FAQ
Q: Can I create dependencies on issues I don't have access to?
A: You can only create dependencies on issues within repositories you have access to. Zenhub respects GitHub's permission model for dependency creation.
Q: How do dependencies affect reporting?
A: Dependencies don't directly impact velocity or burndown calculations, but they provide context for understanding why work may be delayed or why sprint goals weren't met.
Q: Can I set up automated actions based on dependencies?
A: Zenhub doesn't include automated workflows triggered by dependency status changes. Dependencies are primarily for visibility and manual coordination rather than automation.