A pull request that nobody can find from the issue is a small, constant tax. Reviewers hunt for context. The person who filed the issue cannot tell whether a fix is in flight. Release notes get written from memory.
Deckbell links pull requests to issues automatically. This post explains the one naming rule that makes it work, what you see on the issue once it does, and how to keep it tidy across several repositories.
The one rule
A pull request is linked to an issue when its branch name, title or description contains the issue's key, such as HRB-142. Case does not matter, so hrb-142 works too. See Issue details.
That is the whole rule. Everything else in this post is about using it consistently.
We suggest putting the key in all three places, so the link survives a renamed branch or a rewritten title:
- Branch:
hrb-142-proration-on-seat-change - Title:
HRB-142: Prorate seat changes mid-month - Description: a line that reads
Issue: HRB-142
The description line also helps people reading the pull request on GitHub, where there is no issue sidebar.
Pull requests that an agent opens for an issue are linked without any of this, because Deckbell opened them. A coding agent works on one branch per issue, for example coder/hrb-142, and running it again on the same issue continues that branch and pull request. See AI agents.
What shows up on the issue
Linked pull requests are listed under Pull requests in the issue's right sidebar. Each row shows:
- the provider's logo (GitHub, GitLab or Bitbucket);
- the repository and number, for example
app #56, so pull requests in different repositories are easy to tell apart; - the title;
- the state: Open, Draft, Merged or Closed, each in its own colour.
Hover a row for the full owner/repo path and the author. Click it to open the pull request.
Under each pull request, badges show its CI status: Checks passing, N failing or Checks running. With the GitHub App installed, this covers GitHub Actions and other check runs, and commit statuses from services such as CircleCI. When a check is re-run, the newest result counts. Click the badge to open the failing or running check. With Vercel or Netlify connected, the preview deployment shows there too.
Commits whose message mentions the key are listed under Commits, and deployments of branches that mention the issue but have no pull request yet appear under Deployments.
One issue, several repositories
Most real changes touch more than one repository: an API change and a web change, or an app and its docs. The same key in every repository is all it takes. Each pull request shows under the issue's Pull requests with its own repository and number, so api #60 and app #45 sit side by side on one issue.
Where it is practical, open one pull request per issue per repository. When a pull request genuinely covers several issues, mention every key in the description. It is linked to each of them.
GitHub, GitLab and Bitbucket
Automatic linking on GitHub needs the Deckbell GitHub App. Open Integrations → GitHub → Configure and choose Connect GitHub, then pick all repositories or only selected ones. See Integrations.
GitLab merge requests follow the same rule: the source branch, title or description mentions the key. They appear next to GitHub pull requests with their number, such as !318, and their pipeline status. Connect it under Integrations → GitLab, then link the projects you want. See GitLab.
Bitbucket Cloud pull requests work the same way, with Pipelines status. Connect it under Integrations → Bitbucket and link repositories. See Bitbucket.
In each case Deckbell adds a webhook to the repository or project, so updates arrive as the pull request is reviewed, built and merged. If your account cannot add the webhook, Deckbell shows the URL and secret once, and an admin can add it by hand.
Automatic reviews on linked pull requests
Once pull requests are linked, Reviewer and Security agents can read every new one in their repositories. Turn on Review new pull requests automatically when creating or editing the agent. When a pull request is opened, reopened or marked ready for review, the agent posts its findings as a comment on the pull request and on the linked issue, or in the board's channel when no issue is linked. Drafts and pull requests from forks are skipped. See Automatic pull request reviews.
Moving to Done
Linking does not change the issue's status on its own. The pull request's state updates on the issue as it is reviewed and merged, and the team decides what "done" means. A common pattern is: move the issue to In Review when the pull request opens, and to Done when it merges or deploys, with a one-line comment saying what shipped.
Whatever convention you choose, the pull request rows on the issue make it easy to check. If the only pull request is still Open, the issue is not done yet.
A checklist to pin in your repository
- Put the key in the branch name, the title and a line in the description.
- One pull request per issue per repository where you can.
- The same key in every repository the change touches.
- Mention every key when one pull request really covers several issues.
- Check the Pull requests section on the issue before you move it to Done.
That is enough for every pull request to be one click from the issue it belongs to.