Note: GitHub's pull request linking system is separate from ZenHub's
GitHub's linking system in the sidebar of issues and pull requests is separate from ZenHub's issue PR connection. The content below is related to ZenHub's issue PR connection feature and not GitHub's. You can learn more on GitHub's linking feature here
Within ZenHub it is possible to set up connections between issues and PR's so that the status of work is accurately updated and reflected within your Workspace. In order to connect pull requests with your existing issues, you must have the ZenHub extension installed on either Chrome or Firefox. You can download the ZenHub extension here.
Issue and PR connection rules
- You can connect a single PR to multiple issues or you can connect multiple PR's to a single issue.
- There cannot be a crossover in the issues and PRs that are connected.
- issues and PR's can only be in one pipeline at a time. The crossover in connection types is not allowed as this could lead to unexpected issue/ PR movements on the Board.
- Example: As seen in the image below, you can connect PR #9 to issue #1 with multiple PR's attached. However, you cannot connect PR #9 to issues #5 as this is connected to PR #4 which is already connected to other issues.
Connecting a single PR to multiple issues
1. Connecting an existing PR to issues: To get started, select to view a pull request. Whether the pull request is open or merged you'll be able to connect one or multiple issues to the PR:
Note: An issue will be invalid and therefore unable to be selected from the dropdown list if there is a potential for crossover in connection types. ( Refer to connection rules above.)
When viewing a PR with multiple issues connected, you will see a list of the different issues connected. You have the option to remove these issues from your pull request if required:
2. Connecting issues when creating a PR: On the pull request creation page, you'll notice two options below the green Create pull request button.
1. The first is a default pipeline option. Here, you will be able to choose a default pipeline for your pull request to automatically land on your board. This will then be the default pipeline for all new pull requests going forward.
2. The second is a Connect with an issue option. Here, you will be able to connect your pull request with any of your existing issues that live in your ZenHub Workspace, including those that are cross-repo. This will automatically place both the pull request and the connected issue in the default pipeline that you specified:
Using GitHub Keywords to Automatically Connect issues and pull requests in ZenHub
For all new PRs you create, GitHub keywords (fixes, closes, resolves) will automatically link the PR and issue in the ZenHub Board. As issues move through the Board, the linked PR will travel with it. When the PR is closed or merged, the issue will close as well - plus they’ll remain linked in the Closed pipeline for future reference.
Viewing a single pull request connected to multiple issues on the Board
When a single PR is connected to multiple issues, we will show each issue as a card on the Board. The single PR will be duplicated and will show as a nested PR card on each issue. When an Issue with a nested PR card is moved to a different pipeline, the other connected issues will also automatically be moved to that same pipeline:
Behavior when merging pull requests and closing issues using ZenHub's issue <> pull request connection
- When you merge or close a PR in GitHub, we do not automatically close the open issue(s) it is connected with. The merged PR will remain connected with the open issue(s) and they will both remain in the same pipeline. The repo name for the merged/ closed PR will have a line through it and the PR icon will change to purple ( for merged) or red ( for closed). (Note:By leveraging GitHub's closing keywords when creating a PR, we will close the connected issue when the PR is merged) :
- ZenHub supports the GitHub functionality of closing issues using keywords. Using closing keywords in your pull requests allows you to automatically close the referenced Issue. You can read more on GitHubs closing keywords here.
- When you close an issue that is connected to an open pull request, the pull request will not automatically merge. The PR will disconnect from the issue and remain in the same pipeline. The issue will be moved to the closed pipeline:
PR reviewers and review status
When viewing PR cards on the Board, you will see the PR reviewers and the review status for the PR. Each reviewer will have a colored dot next to their avatar to help you quickly understand the PR status:
- Red - requested changes
- Green - approved changes
- Grey - left review comments
- Yellow - pending review