Dependencies (for Issues and Projects) #16501 (#56296)

am-stead · heiskr · web-flow · commit c2acbd0a2288 · 2025-08-21T17:21:22.000Z
Co-authored-by: Kevin Heis &lt;heiskr@users.noreply.github.com&gt;
diff --git a/content/issues/planning-and-tracking-with-projects/learning-about-projects/best-practices-for-projects.md b/content/issues/planning-and-tracking-with-projects/learning-about-projects/best-practices-for-projects.md
@@ -21,7 +21,9 @@ You can use {% data variables.product.prodname_projects_v2 %} to manage your wor
 
 Breaking a large issue into smaller issues makes the work more manageable and enables team members to work in parallel. It also leads to smaller pull requests, which are easier to review.
 
-To track how smaller issues fit into the larger goal, milestones, or labels. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/about-milestones) and [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels).
+To ensure efficient progress, clearly define which issues are blocked by, or blocking, other issues. See [AUTOTITLE](/free-pro-team@latest/issues/tracking-your-work-with-issues/using-issues/creating-issue-dependencies).
+
+To track how smaller issues fit into the larger goal, use milestones or labels. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/about-milestones) and [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels).
 
 ## Communicate
 
diff --git a/content/issues/tracking-your-work-with-issues/about-issues.md b/content/issues/tracking-your-work-with-issues/about-issues.md
@@ -35,6 +35,10 @@ Issues can be created in a variety of ways, so you can choose the most convenien
 
 {% endif %}
 
+## About issue dependencies
+
+You can define blocking relationships between issues using issue dependencies. Issue dependencies let you identify issues that are blocked by, or blocking, other work. See [AUTOTITLE](/free-pro-team@latest/issues/tracking-your-work-with-issues/using-issues/creating-issue-dependencies).
+
 ## About integration with {% data variables.product.github %}
 
 Issues integrate with your work all across {% data variables.product.github %}. Mentioning an issue in another issue or pull request will create references between them and using keywords, like `fixes:`, in your pull requests will automatically close the associated issues. See [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue).
diff --git a/content/issues/tracking-your-work-with-issues/configuring-issues/planning-and-tracking-work-for-your-team-or-project.md b/content/issues/tracking-your-work-with-issues/configuring-issues/planning-and-tracking-work-for-your-team-or-project.md
@@ -92,6 +92,10 @@ Below we have added a task list to our Project Octocat issue, breaking it down i
 
 {% endif %}
 
+### Showing which issues are blocked by, or blocking, other work
+
+By creating issue dependencies, you can easily see and communicate which issues are blocked by, or blocking, other issues. This helps streamline coordination, prevent bottlenecks and increase transparency across the team. See [AUTOTITLE](/free-pro-team@latest/issues/tracking-your-work-with-issues/using-issues/creating-issue-dependencies).
+
 {% ifversion copilot %}
 
 ## Understanding new issues
@@ -175,7 +179,7 @@ You can also use the existing {% data variables.product.prodname_projects_v1 %}
 
 Below is a {% data variables.projects.projects_v1_board %} for our example Project Octocat with the issue we created, and the smaller issues we broke it down into, added to it.
 
-![Screenshot of a {% data variables.projects.projects_v1_board %} called "Project Octocat Board," with issues organized into columns for "To do", "In progress," and "Done."](/assets/images/help/issues/quickstart-project-board.png)
+![Screenshot of a {% data variables.projects.projects_v1_board %} called "Project Octocat Board," with issues organized into columns for "To do," "In progress," and "Done."](/assets/images/help/issues/quickstart-project-board.png)
 
 {% endif %}
 
diff --git a/content/issues/tracking-your-work-with-issues/using-issues/creating-issue-dependencies.md b/content/issues/tracking-your-work-with-issues/using-issues/creating-issue-dependencies.md
@@ -0,0 +1,36 @@
+---
+title: Creating issue dependencies
+intro: 'Learn how to create issue dependencies so that you can see which issues are blocked by, or blocking, other work.'
+versions:
+  fpt: '*' 
+  ghec: '*' 
+type: overview
+topics:
+  - Project management
+permissions: 'People with at least triage permissions for a repository can create issue dependencies.'
+product: 'Issue dependencies are available for users on {% data variables.product.prodname_free_user %}, {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, and {% data variables.product.prodname_ghe_cloud %} plans.'
+---
+
+{% data reusables.issues.issue-dependencies-preview-note %}
+
+Issue dependencies let you define issues that are blocked by, or blocking, other work.
+
+## Marking an issue as blocked by, or blocking, another issue
+
+1. Navigate to the issue that you want to create a dependency for.
+1. In the right sidebar, click **Relationships**.
+1. From the dropdown, select a dependency option:
+   * To indicate that your issue depends on another issue being completed, select **Mark as blocked by**.
+   * To indicate that your issue is preventing another issue from being completed, select **Mark as blocking**.
+1. In the dialog box that opens, search for and select all the issues that are blocked by, or blocking, your issue.
+
+Blocked issues are marked with a "Blocked" icon on your project boards or repository's Issues page, so you can easily identify bottlenecks.
+
+## Removing a blocking relationship between two issues
+
+1. Navigate to the issue that you want to remove a dependency from.
+1. In the right sidebar, click **Relationships**.
+1. From the dropdown, select a dependency option:
+   * To indicate that your issue no longer depends on another issue being completed, select **Change blocked by**.
+   * To indicate that your issue is no longer preventing another issue from being completed, select **Change blocking**.
+1. In the dialog box that opens, deselect the issues that are no longer blocked by, or blocking, your issue.
diff --git a/content/issues/tracking-your-work-with-issues/using-issues/index.md b/content/issues/tracking-your-work-with-issues/using-issues/index.md
@@ -10,6 +10,7 @@ topics:
 children:
   - /creating-an-issue
   - /adding-sub-issues
+  - /creating-issue-dependencies
   - /assigning-issues-and-pull-requests-to-other-github-users
   - /editing-an-issue
   - /viewing-all-of-your-issues-and-pull-requests
diff --git a/data/reusables/issues/issue-dependencies-preview-note.md b/data/reusables/issues/issue-dependencies-preview-note.md
@@ -0,0 +1 @@
+> [!NOTE] Issue dependencies are in public preview and subject to change.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+> [!NOTE] Issue dependencies are in public preview and subject to change.`