Keypup uses links between issues and pull requests to enrich your data and populate cross-entity fields between issues and pull requests. This allows you to do cross-entity reporting, such as filtering pull requests based on resolved issue labels or reporting the list of PR authors working on a group set of issues.
Links between issues and pull requests are detected via auto-closing keywords and issue references on the pull request side.
How does it benefit my reporting?
Linking issues to pull requests allows Keypup to populate cross-entity fields, such as:
Issues & Pull Requests > Resolved Issues > Labels: the list of labels from resolved issues
Issues & Pull Requests > Resolving Pull Request > First Created At: the creation timestamp of the first pull request associated with the issue
Issue to PR associations also allows us to enhance regular fields, such as:
Issues & Pull Requests > Due on: When a pull request is linked to one or more issues, Keypup automatically infers the due date by taking the soonest of all due dates across the pull request and its related issues.
Issues & Pull Requests > Resolution State: This field is only applicable to issues. It infers the implementation status of the issue by looking at the associated pull requests. The field can have the following values:
None: the issue has no attached pull requests. It is not being implemented.In progress: the issue has at least one open pull request attached to it.Implemented: all attached pull requests are merged or closed.
Links between issues and pull requests are automatically grouped in card insights. Each card will be populated with the references of issues and pull requests, cross-app comments, due dates, global timelines, etc. This way, you have a single point of entry to see everything related to your linked items.
How to link pull requests to issues?
> Option 1: Via the pull request title
To reference a JIRA issue such as PROJ-123 or a GitHub issue such as my-org/my-project#475 , you can set your pull request title to:
[PROJ-123] Resolve problem with login button[my-org/my-project#475] Resolve problem with login button
> Option 2: Via the pull request body or a commit message
You can reference an issue by key (e.g. PROJ-123) or URL by prefixing it with an auto-closing keyword, such as “fixes”, “resolves” or “closes”, for instance:
This PR updates the handler attached to the login button. Fixes PROJ-123Fix login button. Closes https://myorg.atlassian.net/browse/PROJ-123Fix the login. Closes my-org/my-project#475This is a fix. Resolves https://github.com/my-org/my-project#475
> Option 3: Using a Jira issue key in a commit message
Jira issue keys are so specific that you do not need to specify an auto-closing keyword when you reference them in commit messages. The following examples will work as commit messages:
[PRO-123] fix a bug in the signup controlleradd feature to login page - PROJ-123
> Option 4: Using a Jira issue key in a branch name
You can use Jira issue keys in your (head) branch names to reference issues. Below are some valid examples:
proj-123-fix-this-bugPROJ-123-fix-this-bugproj-123/implement-this-featureproj-123/proj-124/implement-two-features
> Warning: Do not use GitHub's "Linked issues" feature
It is recommended to avoid linking issues to Pull Request via the Linked issues settings menu on the side of the Pull Request screen.
Issues linked this way are not exposed on the GitHub API. This means third-party applications will be unable to see these links, including Keypup, and therefore the linking will not be applied on your card insights.
Use closing keywords instead, as described previously. Issues linked via closing keywords will still appear under the Linked issues setting menu on GitHub.
Which pull requests are associated with issues?
To avoid pollution and keep the associations focused on implementation pull requests, Keypup has a few rules to determine if a PR is to be effectively associated with an issue:
The PR must contain a reference to the issue (see section "How to link PRs to Issues?"
The PR must be
OPENorMERGED, notCLOSEDThe PR must have a
base refthat has not been used as ahead refby a previous pull request associated with the issue. This condition ensures that release PRs (e.g. PR frommastertostagingthenstagingtoproduction) do not get considered as resolving if they follow a proper implementation PR (e.g. frommy-feature-branchtomaster), even though they contain references to issues through commits.