Blog

How to Link Branches, Commits and Pull Requests to Issues

Ask a team which issue a pull request belongs to and the answer is often a pause followed by a search. Ask which code shipped for a given issue and the answer is a trawl through commit history. Both questions take seconds when one habit is in place: the issue key travels with the work, from the branch name to the commit message to the pull request.

That habit does not need a new process or a new tool. It needs a few small conventions, applied the same way every time. This guide covers those conventions, the mistakes that quietly break them, and how ISO Mate uses them to show the code on every issue without anyone filling in a form.

Why the issue key is the link

Git knows nothing about your issue tracker. A branch, a commit, and a pull request are just names and text. The only way to connect them to a piece of planned work is to write something into that text that a person or a tool can recognize later. The issue key (for example PROJ-42) is ideal because it is short, unique, and already how the team refers to the work.

Once the key is in the text Git keeps, a lot of otherwise tedious questions get easy. Reviewers see why a change exists. Whoever writes the release summary can see which changes belong to which issues. Someone debugging a regression months later can go from a line of code to the commit to the reason it was written. And when an auditor or customer asks which change covered a given requirement, you can answer from the record instead of from memory.

The five habits

  1. Use keys that never change.
  2. Name the branch with the key.
  3. Start commit messages with the key.
  4. Put the key in the pull request title.
  5. Decide what a merge means for the issue.

1. Use keys that never change

A key only works as a link if it identifies exactly one item for as long as the code exists. If keys can be renumbered, reused, or rewritten when an item changes type, every old branch name and commit message becomes a dead reference. Choose a prefix per project that is short and recognizable, such as API or WEB, and treat the number as permanent.

The fix: pick a tracker that never rewrites keys, and agree a prefix per project before the first branch is created. In ISO Mate the project key is 2 to 10 uppercase letters or numbers and is fixed when the project is created. An issue also keeps its key if you later change it from a Task to a Bug, so references in commit messages stay valid.

2. Name the branch with the key

The branch is the first thing created when work starts, so it is the earliest point where the link can be made. A consistent pattern also makes branches sortable and readable in any Git tool.

The fix: agree one pattern and use it everywhere. A common choice is feature/PROJ-42-add-invoice-export: a type, the key, then a short slug of the summary. Keep the key near the front, keep the slug short, and aim for one branch per issue. If a branch quietly carries three issues, the link is true for all of them and useful for none.

3. Start commit messages with the key

Commits are where the link survives longest, because commit history is permanent even after branches are deleted. A message such as PROJ-42 Add CSV export for invoices is searchable by key and readable at a glance.

The fix: lead with the key, then a plain description of the change. Keep one issue per commit where you can. One caveat: if your team squash merges, the individual commits collapse into one, and the message of that one commit usually comes from the pull request. That makes the next habit the more important of the two.

4. Put the key in the pull request title

The pull request is what reviewers, managers, and release owners actually look at. A title such as PROJ-42 Add CSV export for invoices tells all of them what the change is for before they open it. The description is the place for related keys, context, and anything a reviewer should check.

The fix: open the pull request as a draft as soon as there is something to show. The link then exists while the work is in progress, and a project manager can see that the issue has code behind it without asking. If a single pull request really does cover more than one issue, name each key. It is also a prompt to ask whether the change should have been split.

5. Decide what a merge means for the issue

Linking code to an issue and finishing an issue are different things. A merged pull request does not necessarily mean the work is done. It may still need a deployment, a test pass, or a check against the acceptance criteria. Teams that skip this decision end up with issues marked Done that nobody has verified, or issues sitting In Progress long after their code shipped.

The fix: write down who moves the issue and at what moment: on merge, on deployment, or after verification. Then make it part of your definition of done rather than leaving it to memory.

Four ways the link breaks quietly

  • A typo in the key. Writing PROJ-24 instead of PROJ-42 links the work to a different, real issue. Nothing errors, so the wrong issue simply shows activity it should not have. Copy the key from the issue instead of typing it.
  • Starting before the issue exists. Work that begins as an unnamed branch gets its key added later, if at all. Creating the issue takes a minute and saves the cleanup.
  • Long lived branches. A branch that stays open for weeks and collects several issues makes every link on it less meaningful. Smaller branches also mean smaller, easier reviews.
  • Key only in the description. Some tools read only the title. Put the primary key in the title and treat the description as the place for extras.

How ISO Mate does the linking for you

These habits are tool independent, but they pay off most when something reads the keys for you. That is what Project Git Integrations in ISO Mate do. Here is how each habit maps to what the platform does.

  • Keys: issues in a project take the project key as their prefix, so a project keyed PROJ produces PROJ-1, PROJ-2, and so on. Issues without a project use a type prefix (EPC, USR, TSK, BUG, or SUB). The guide to issue keys explains the numbering.
  • Connecting a repository: from a project’s settings, add a connection to GitHub, GitLab, or Bitbucket with an access token. ISO Mate validates the token and detects whether it has read only or read and write access.
  • Matching: every 15 minutes, ISO Mate syncs branches, commits, and pull requests from each connected repository. It looks for issue keys in branch names, commit messages, and pull request titles and descriptions, and links what it finds to the matching issue. Matching ignores letter case, and a pull request that names two keys is linked to both. A key only links if an issue with that key exists.
  • Git Activity on the issue: open an issue and its Git Activity section lists the linked branches, commits, and pull requests grouped by repository, with a link out to the provider. Pull requests show their status, and a refresh action syncs the issue on demand instead of waiting for the next cycle.
  • Starting work from the issue: Create Branch builds a name from the issue key and summary. The default pattern is feature/{KEY}-{summary}, and each project can set its own default branch pattern. You can copy the branch name or a ready made checkout command. Create MR/PR opens a pull request that carries the issue key in its title and starts it as a draft. Both need a connection with write access.
  • Tidying up: each branch and pull request has an action menu to unlink it from the issue, and, with write access, to delete the branch or close an open pull request on the provider after a confirmation.

There are limits worth knowing before you rely on it. Syncing runs on a 15 minute cycle, so a brand new branch can take that long to appear unless you refresh. ISO Mate does not change an issue’s status when a pull request merges, so habit five stays a team decision. And once a link exists it is not removed automatically when you edit a title, so if a typo linked the wrong issue, unlink it from the Git Activity section.

One security point: use the least access you need. If your developers create branches and pull requests in their own tools, a read only token is enough for ISO Mate to sync and link. Grant write access only if you want to create branches and pull requests from the issue. The setup guide lists the token scopes for each provider.

A five question check for your team

  1. Does every issue have a key that will never be renumbered or reused?
  2. Does everyone name branches with the same pattern, key first?
  3. Do commit messages and pull request titles start with the key?
  4. Can you open any issue and see the code behind it, and open any pull request and name its issue?
  5. Does the team know who moves an issue to Done, and when?

If the answer to any of them is no, start with the habit nearest the top of the list, because each one makes the next more valuable. To see the links on your own issues, connect a repository to a project in DevOps Management. Every ISO Mate account starts with a 14-day free trial.

Leave a Reply