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. Tracking these relationships gives teams visibility into task connections, helps identify bottlenecks before they impact deadlines, and prevents poor planning decisions that could delay releases.
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.
Understanding dependency relationships
Zenhub supports two types of dependencies for GitHub issues and pull requests:
Dependency Type | What It Means | Example |
|---|---|---|
Blocked by | Current issue cannot proceed until another issue is completed | Issue #45 blocked by Issue #23 (waiting on API endpoint) |
Blocking | Current issue must be completed before other issues can proceed | Issue #23 blocking Issue #45 (API must be ready first) |
These relationships work bidirectionally. When you mark Issue A as blocked by Issue B, Issue B automatically shows as blocking Issue A. This two-way connection ensures both issues reflect the dependency relationship without requiring duplicate data entry.
Creating dependencies
Navigate to any GitHub issue or pull request and look for the "Dependencies" section beneath the initial description and comments.
To add a dependency:
Click the "Blocked by" or "Blocking" button (use dropdown to switch between types)
Type the issue title or number in the search field
Select the appropriate issue from the results
The dependency relationship is created immediately
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.
External dependencies: Mark dependencies 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.
Removing dependencies: 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. All dependency additions and removals are logged in the issue history for reference.
Tracking dependency status
Dependencies automatically update based on issue status changes, providing real-time visibility into blocking relationships.
Status indicators in the dependency section:
"Issue is ready to go" - All blockers are resolved and the issue isn't blocking other work
"Blocked by [X] issues" - Active blockers remain that prevent progress
"Blocking [X] issues" - Current issue prevents other work from proceeding
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. Once blocking issues are closed, the dependency list updates to reflect the resolved status, automatically unblocking dependent work.
Viewing dependencies on the Work Tracker
Dependencies appear on your Work Tracker board with clear visual indicators:
Issue card icons:
🛑 Blocked issue icon - Issue is blocked by other work
⚠️ Blocking issue icon - Issue is blocking other work from proceeding
🛑⚠️ Both blocked and blocking icon - Issue has both types of relationships
These visual indicators help teams quickly identify bottlenecks and prioritize unblocking work during sprint planning and daily standups. You can filter dependency icons on or off through the board filtering options without affecting what other team members see.
Dependencies and sprint planning
Review dependency relationships during sprint planning to identify potential risks and optimize work sequencing.
Sprint risk assessment: Issues with many blockers may not be suitable for the current sprint, while blocking issues should be prioritized to unblock downstream work. Dependencies help visualize work that spans multiple sprints, providing context for realistic timeline forecasting.
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. When blocking issues are scheduled for later sprints, teams can adjust their planning to account for the dependency chain.
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: When creating dependencies on other teams' work, ensure those teams understand the downstream impact of delays. Use dependency relationships to facilitate cross-team communication.
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.
Q: Do dependencies work across multiple workspaces?
A: Dependencies work across repositories within your current workspace. Issues must be in repositories connected to the same workspace to establish dependency relationships.