Git linking
Put an item's key in a branch name, a commit message or a pull request and the repository's webhook links the code to the item; read an item's code in its flyout and the project's on the Branches & PRs tab, link by hand what the key missed, and take a wrong link off.
By the end of this page you will have the code of a project tied to its items: a branch, a commit or a pull request that names an item's key shows on the item the moment the repository's webhook reports it, with where it stands; you will read an item's code in its flyout and the project's on its Branches & PRs tab, link by hand the one that left the key out, and take a wrong link off. What a pull request does to an item's status is on the pull request flow page; registering the webhook at the host is on the GitHub page.
Before you begin
| To | You need |
|---|---|
| See an item's code and the Branches & PRs | work-item:view-any; staff only, never a client guest |
| Link a reference by hand, or unlink one | work-item:update; the project manager, the analysts, the developers and the testers |
| Set the repository's webhook secret | repository:update; see Repositories |
A repository has to be registered on the project and its webhook set up before anything links itself. Until then, the link by hand still works.
Name the key in the code
Every item carries a key, the project's key and a number: CRM-142. Put it where the host will
show it:
- In a branch name, such as
feature/crm-142-voucherorCRM-142-voucher. The case does not matter; the key is read between the slashes and the dashes. - In a commit message, anywhere:
CRM-142 Apply the voucher at checkout, orFixes CRM-142 and CRM-143for a commit that serves two items. - In a pull request, in its title, its branch name or its body; the first delivery that names the key links it, and every later one follows its state.
Only the project's own key counts: a message on this project's repository that names an item of
another project links nothing here, and a number no item carries links nothing either. A token
that merely contains a key, such as ACRM-1420, is not a key.
Read an item's code
Open an item on the backlog and find Code in its flyout, under the
checklists and the time. Each line is one reference: a badge for its kind (Branch, Commit
or Pull request), its short form (the branch name, seven characters of the sha, or # and the
number) linking to the host, the commit's first line or the pull request's title, a badge for its
state, and the repository. Pull requests come first, then branches, then commits, the newest first
within each. An item with a pull request shows its number and state as a chip on its row in the
list, so a backlog reads at a glance which items have code up for review and which merged.
Read the project's Branches & PRs
Under the project's Code pages, the Branches & PRs tab lists every reference of the project, the newest first: the reference with its kind and title, the item it belongs to (opening the item's flyout), the repository, the author as the host names them, the state, and when it was opened or pushed. Narrow by kind, by state, by repository or by words in the ref, the title, the author or the item's key or title, and sort by the reference, the author, the state or the date. Open at Provider in the row menu goes to the host; Open Item goes to the backlog.
Link what the key missed
A commit whose message forgot the key, or a pull request whose title and branch left it out, is
linked by hand. In the item's flyout, Link beside the Code heading opens the dialog: pick
the Repository (one of the project's live ones), the Kind, type the Ref (the branch
name, the commit sha or the pull request number) and, if you like, the Title and the
Address; the address is composed from the repository's own when left out. The reference joins
the item at once, announced as code.branch_linked, code.commit_linked or
code.pull_request_linked the same way the webhook's links are; linking the same one twice
refreshes the row rather than doubling it. A link by hand never moves the item: the moves follow
the host's own word through the webhook.
Unlink a wrong link
A key typed into the wrong message links the wrong item. The cross on the line in the item's
flyout, or Unlink in the row menu on the Branches & PRs tab, takes the reference off after a
confirmation; the branch, the commit or the pull request itself is untouched, code.reference_removed
goes out, and the host's next delivery about the same reference links it again if the key is still
in it, so fix the message or the title at the host when it was the key that was wrong.
All the fields
What the host sends carries more: the author, the lines added and removed on a pull request, when it was opened, merged or closed, and a few host fields kept beside the row.
What happens next
- Every reference is written to the item's activity history: linked by the webhook for no person, or by the person who linked it by hand; a state that moves is written too.
- The
code.branch_linked,code.commit_linkedandcode.pull_request_linkedevents go out when a reference is first linked,code.pull_request_mergedwhen a linked pull request merges, andcode.reference_removedwhen one is taken off; see thecode.*events. - A pull request that opens for review or merges tells the item's assignee, reporter and reviewer under the Code alert class, through the channels each of them chose in their notification settings.
- A pull request moves the item when the project's switches ask it to; see Pull request flow.
- The repository remembers when its host was last heard from; the repository's flyout shows it beside the webhook secret.
Heimdall on this page
Heimdall reads the code the way an agent does, through the same tools: "Is there a branch for
CRM-142 yet?", "Which items have an open pull request?" and "What merged this week on the
portal repository?" read the references; "Link commit a1b2c3d to CRM-142, the message forgot the
key" links by hand through link_commit. Heimdall never unlinks a reference and never moves an
item on the strength of a link; the moves stay with the webhook and with you.
From the API and MCP
Code references API
A project's references and an item's, one reference, the link by hand, and the unlink.
list_code_references
An agent reads what code an item already has before it opens a branch.
link_commit and link_pull_request
An agent links the commit or the pull request whose message or title left the key out.
code.* events
Branch, commit and pull request linked, pull request merged, reference removed.
Permissions
| Action | Permission |
|---|---|
| See an item's code, read Branches & PRs | work-item:view-any; never a client guest |
| Read one reference over the API | work-item:view |
| Link a reference by hand | work-item:update |
| Unlink a reference | work-item:update; in the application and over the API |
| Set or rotate the webhook secret | repository:update |
Frequently asked
I pushed a commit with the key and nothing appeared. Check the repository's flyout: a webhook secret must be set, and the host must have the address registered with the push, branch and pull request events; the flyout says when the host was last heard from. Then check the key: the project's own key, a dash, the number, with no letters stuck to either end.
A commit names two items. Which one gets it? Both. A commit, a branch or a pull request that names several keys of the project is linked to each of those items, once per item.
The branch was deleted. Does the link go? No. The branch's reference moves to Closed and stays on the item, so the history of where the work happened is kept.
Can a client guest see the code? No. The references, the Branches & PRs tab and the Code panel are staff's; a guest sees the item without them.
Does linking a merged pull request by hand move the item? No. Only the host's own word through the webhook moves an item, and only when the project's switches are on; move the item yourself when you link a pull request after the fact.
Related
- Pull request flow: what a pull request does to an item's status.
- GitHub: registering the webhook at the host.
- Repositories: registering where the code lives and setting the secret.
- Backlog: the items the code is linked to.
- Board: where the moves a pull request makes show up.
How is this guide?
Last updated on
Timesheets
The Timesheets page: a person's week of time across their projects, day by day and item by item; the week put to its approver, held while they read it, locked when approved, reopened when it must change, and exported as a file.
Pull request flow
What the repository's webhook does to an item when a pull request naming it opens, turns into a draft, merges or closes: the moves the project's two switches allow, the statuses they start from, the kinds that finish on a merge, the gates that can refuse a move, and what is announced.