Linking work to code

Overview

Write Fixes #412 in a commit message and Gitmoap records the link, then closes the work item when that commit reaches the branch your product ships from. Pin a work item to a region of code and Gitmoap follows that region through every rename, reformat and refactor, telling you when the code the ticket is about has been rewritten or deleted. Scan a // TODO: out of the tree and it becomes a row you can promote to a real work item in one click — and deleting the comment closes it again.

Together these three mechanisms answer the questions a tracker normally cannot: what shipped for this ticket, where is the code this ticket is about, and what has this codebase already admitted to itself.

Quick start

Before you start

How it works

There are three mechanisms here and they are independent. You can use any one of them without the others.

References in commit messages and merge requests

A reference is a sigil plus a target, written in ordinary prose:

A bare & resolves in the repository's immediate parent group, not the root of your namespace, because that is the group most teams mean when they say "our group". An epic further up the tree is addressed by path.

A reference on its own links. A reference behind a closing keyword links and expresses an intent to close:

One keyword governs a whole run of references separated by commas, and, or whitespace, so Fixes #412, #413 and #414 expresses three closing intents.

Where a closing keyword takes effect is the part people get wrong. A commit closes when it lands on a closing branch — the repository's default branch, plus any branch pattern the scope adds in its work-item settings. A merge request closes when it is merged into a closing branch. Pushing Fixes #412 to a feature branch links the commit and closes nothing; that is the point, because the branch is not a claim about the state of the product. A stacked merge request that targets another merge request's source branch also closes nothing, for exactly the same reason.

Because # is the most-used character in software, the parser deliberately ignores it almost everywhere:

Linking runs after the push is accepted, not during it. A push is never delayed, never rejected and never rolled back because of anything on this page — with one exception, the push rule described under Repository rules, which can require every commit to name a work item. Everything else lands a few seconds behind the push and converges: a redelivery changes nothing, and a link that fails is re-derived from the commit next time.

Quick actions

A slash command in a commit message mutates the work item the nearest preceding reference names:

Several fit on one line, which is what a real commit message looks like:

A commit message is never an authorization bypass. Setting user.email in your git config costs nothing, so the author line is not an identity Gitmoap has authenticated. Every action is therefore checked twice — against the commit author and against the person who pushed — and runs only if both hold the access level it needs. An action that is dropped is written to the work item's timeline as a denial, so the author can see it was refused rather than lost.

Code anchors

An anchor binds a work item to a region of code and keeps evaluating it. It records the path, the line range and the commit those coordinates are valid at — which is exactly the address a permalink carries — and then, on every push to the default branch, Gitmoap replays the diff and carries the anchor forward through the hunks.

That gives you a second, live set of coordinates beside the frozen ones, and a state:

Recognition is a similarity score over the region's lines, with whitespace and comment markers normalised away first. At or above 0.75 the anchor stays live; between 0.2 and 0.75 it is drifted; below 0.2 it is orphaned. Re-indenting and re-spacing change nothing the score can see, so running a formatter over an anchored file does not drift its anchors. Adding a line inside an anchored block grows the region rather than breaking it, and a git mv relocates the anchor rather than orphaning it.

Two things follow from anchors being rows rather than strings in a paragraph. The code browser can draw open work in the gutter beside the lines it is about, and a review can be told that a change overlaps an open bug's anchored region — not merely that it touches the same file.

Anchors track the default branch only. A region that exists on a feature branch and nowhere else has no shared history to follow.

Code TODOs

Gitmoap reads the + and - lines of each push to the default branch and recognises six marker keywords — TODO, FIXME, HACK, XXX, BUG, OPTIMIZE — in a comment:

Uppercase only, and only in a comment: everything on the line before the marker has to be whitespace or comment punctuation, which is what keeps let msg = "TODO: fix this"; out of your backlog without a parser per language.

What happens to an unlinked marker is a setting on the scope, inherited from the group:

index is the default deliberately. A repository with four hundred markers that auto-minted four hundred work items has a destroyed backlog, and the only way out is bulk deletion.

A TODO's identity is its content digest, not its path and not its line. The digest is taken over the normalised marker text with the (@owner) or (#412) group and the comment syntax stripped, so it survives a reformat, a rename and a move. A marker is the same TODO as an existing one if either the digest matches or its position carries onto an existing anchor. Reword it in place and the anchor recognises it; move it and the digest recognises it. Reword it and move it in one push and you get a new TODO — correctly, because it is a different statement in a different place.

Vendored and generated files are never scanned: lock files, minified bundles, source maps, anything the repository marks generated in .gitattributes, and by default vendor/**, third_party/** and node_modules/**.

How to

Start work by naming the branch after the item

A branch whose name begins with the number and a hyphen — 412-retry-loop-double-charges — or which carries #412 anywhere in it — fix/#412 — names work item 412 in the repository the branch is created in. The leading form has to lead: fix-412-retry names nothing, because the digits are not the first thing in the name. Creating it records the branch on the item's timeline and, unless the scope has turned that transition off, moves the item into the in progress category. It is the cheapest way to start a ticket, because you were going to create the branch anyway.

Two things about it surprise people. It fires on create only — pushing more commits to the branch does not drag an item a reviewer has already moved to in review back to in progress. And no link row is written: which branches belong to #412 is answered from the branch names themselves, so renaming the branch changes the answer rather than leaving a stale one behind.

Close a work item from a commit message

Write the closing keyword and the reference in the commit message body, then push the branch and merge it as usual:

The link appears on the work item within a few seconds of the push. The item closes when that commit reaches a closing branch — through a merge, a squash, a rebase or a direct push, all of which Gitmoap treats identically. Merging a stacked merge request into another merge request's branch links but does not close, because nothing shipped.

To close from the merge request itself rather than from a commit, put the keyword in its title or description. Gitmoap re-reads the body on every edit, so editing Closes #412 down to a bare #412 before the merge means the merge links but does not close, and deleting the reference removes the link. Neither ever reopens something that is already closed — closing intent is read once, at merge.

Run a quick action from a commit message

Put the action after the reference it applies to. An action binds to the nearest reference before it, or to the first reference in the message if none precedes it:

Unknown action names are ignored rather than rejected — a commit message is not a command line, and refusing a push after the fact would help nobody. If an action does not take effect, open the work item's timeline: a refusal is recorded there with the action, the commit and the reason.

Review the commits behind a work item

Every commit whose message named the item, each with the repository it lives in — which is not necessarily the item's own repository, since a reference can be written from anywhere you can see. The page is ordered by repository and then by commit id, not by date, so do not read the first row as the most recent one. A commit whose object git can no longer produce still comes back with its id, because the link records what a message said.

Review the merge requests behind a work item

Each linked merge request comes back with a flag saying whether it claims to finish the item or merely mentions it. That flag is the whole difference between a link and a promise, and it is what merge time reads. This page is ordered by repository and then by merge-request number, not by date.

Track an epic's work across repositories

An epic lives in a group and has no repository of its own, so it is addressed under the group. The listings are otherwise identical, and they span every repository you can see.

Commits and merge requests you cannot see are dropped from both listings rather than shown as placeholders, so a private repository inside a public group never becomes visible through its cross-references.

See what a commit named

The reverse direction: hand it a full 40-character commit SHA and get back the work items that commit's message named — the ones it closed and the ones it merely mentioned alike. An abbreviated SHA is refused; copy the whole thing. A well-formed SHA that names no commit is not an error: the answer is an empty list, because the question is asked of the links rather than of git.

See what a merge request will close

Pin a work item to a region of code

Give a path, an inclusive line range and the commit those coordinates are valid at. Gitmoap reads the region at that commit — an anchor is never born broken — and immediately resolves it forward to the current tip of the default branch.

The response names the file's CODEOWNERS owners as suggested assignees — which is the reason to pin an anchor rather than paste a permalink. Turning on the scope's assign from code owners setting makes the suggestion an assignment, and only when the item has no assignee at all: an item somebody has already picked up is triaged, and adding a second name is somebody else's queue getting work they did not ask for. A repository with no CODEOWNERS file is not an error; the suggestion is simply empty. A code owner who is not a member of the scope stays a suggestion and is never assigned, because assigning work to somebody who cannot open the item reads as a person ignoring their queue.

Four rules decide whether a pin is accepted:

• The work item has to be repository-scoped. An anchor points into a repository, and a group-scoped epic has none.
• The region is at most 500 lines, starting at line 1 or later, ending at or after it starts.
• The path, the range and the commit have to resolve, and the file has to be text. A range past the end of the file, a path that does not exist at that commit, or a binary file is refused.
• The commit has to be reachable from the default branch. A feature-branch-only commit is refused, because a squash-merge would leave the anchor pinned to a commit that never enters the default branch's history at all.

An anchor's kind says what it is pinned to. A region — the default, and what you get from the code browser — is a line range. A symbol is the same line range with the name of the thing carried alongside it. A file is the whole file, followed only through renames and deletions, with no line mathematics and no drift. A marker is a TODO comment carrying a work item's number; the TODO scan is what mints one, and it is the only kind that may close its work item when the code goes.

on_orphan: close_issue is accepted only on a marker anchor. Everything else defaults to flag, because deleting the code a bug points at is not the same as fixing the bug.

See what a work item is anchored to

Show open work beside the code

The gutter query. Ask for one file and you get every anchor on it, each carrying enough of its work item — number, type, title, status — to render a marker beside the lines.

Passing a ref projects the anchors onto it without storing anything. The default branch is where the resolved coordinates are authoritative. Leave the file out and you get every anchor in the repository instead of one file's — the same rows, unfiltered.

An anchor is not removed when its work item closes, so a closed item's regions keep appearing here and in the review overlap below. Every row carries its item's status, which is what tells the two apart; unpin the ones a finished ticket no longer needs.

Check whether a merge request touches open work

The single highest-value review signal here: not this change mentions #412, but this change edits the code #412 is about, whether or not anybody noticed.

Overlap is computed against the change's own hunks, from the merge base to the source branch's head — so it describes what this merge request does, not what has landed on the target since it opened. A merge request that edits line 400 of a file anchored at lines 88–104 is correctly reported as touching nothing, and one that deletes the file reaches every anchor on it.

Find the files that carry the most open work

Heaviest means the most open bugs and stories, and only those two types are counted in those two columns — a file whose anchors are all chores or tasks shows zeros there while its total says otherwise. The total counts every anchor on the file whatever its item's type or status, and the marker column counts the ones the TODO scan pinned.

This comes from the tracker's own data. No heuristic, no code-churn proxy, no static analyser.

Take an anchor off automatic tracking

Setting an anchor's state to manual takes it out of tracking: while it is manual, Gitmoap never re-resolves it, never drifts it and never orphans it — a push that touches its file skips it, and so does re-resolving. This is the escape hatch for the case where the automatic result is confidently wrong. Setting any other state hands it back, and the next push picks it up again.

You can change an anchor's state and what happens when it is orphaned. You cannot change its coordinates or its pinned commit — an anchor whose region could be edited would be a mutable claim about an immutable commit. Pin a new one instead.

Re-resolve an anchor

Re-derives the anchor against the current tip of the default branch. Use it to heal an anchor left at needs_review by an oversized push, or to see the effect of a push immediately rather than waiting.

An anchor that was skipped heals on its own the next time somebody pushes a change to its file, because its base never advanced — the next diff simply crosses the whole gap. Re-resolving just does it now.

Unpin an anchor

Prefer setting the anchor to manual if the goal is only to stop Gitmoap moving it: that keeps the record and stops the tracking.

Browse the TODO markers in a repository

Paging uses two differently-named halves: the response carries next_token, and you pass that value back as cursor.

Promote a TODO into a work item

Promotion mints a work item from the marker, pins a marker anchor to the comment, and stamps the row so the CLI can find it. The type defaults to whatever the scope's TODO settings say — Chore unless changed — and the title defaults to the marker text. Assignees are whoever you name; the marker's (@owner) is the suggestion the promote dialog pre-fills, not something the server applies on its own.

Promotion is idempotent. Promoting a digest that has already been promoted returns the existing work item with 200, not a conflict, because the statement it makes is already true. The one case that does answer 409 is a genuine race — two promotions of the same TODO in flight at once, where one wins and the other finds the marker already claimed. Retry it and you get the 200 and the winner's work item.

Because it mints a work item and an anchor in one go, it can be refused at either ceiling: the scope's open work item cap, or the anchor cap on the repository. Both answer 429, and the message says which. A type you name has to be one a repository can hold, so epic is refused with 400.

The minted item carries a marker anchor with on_orphan: close_issue, which is the tight loop the feature exists for: delete the comment and the work item closes, with a timeline entry naming the commit that removed it and crediting the person who pushed that removal — not whoever wrote the marker. Three guards stop that from being a surprise. The deletion has to land on the default branch. A marker removed in one place and added in another with the same digest is a move, not a deletion. And the marker anchor has to be the item's only anchor — an item somebody has also anchored to a region of code, or given acceptance criteria, is a real work item now, and a real work item is not closed by a comment edit.

Stamp the new ids back into your code

Promotion mints #430 but the server never rewrites your pushed history, so the source still says a bare // TODO:. Close the loop on your machine, inside a clone:

With nothing to do it says so and exits — Nothing to stamp — no promoted TODOs are missing their id when no promoted TODO is unstamped, No matching TODOs found in the working tree when none of them is in front of you.

The rewrite replaces the marker's header, keeping your comment syntax, your indentation and the text: // TODO: fix the retry becomes // TODO(#430): fix the retry. An owner group is replaced by the id rather than kept beside it, so TODO(@sam): becomes TODO(#430): — if that name should survive, put it on the work item as an assignee before you stamp. It stages the files and stops. Pass --commit to have it commit as well, --dry-run to print the plan and touch nothing. It never pushes, it is safe in a dirty tree, and it is safe to run twice: a marker that already carries its id is not a candidate.

Markers are matched by digest, never by path and line. A TODO whose digest is nowhere in the working tree is skipped with a warning rather than edited blindly — if you have already reworded that comment, the line at app/payments.rs:88 is somebody else's code now.

Require every commit to name a work item

Two push rules turn the convention into a requirement, and unlike everything else here they run during the push and can reject it: one requires every commit to reference a work item, and the stronger one requires a closing reference. Merge commits are exempt, because git wrote their message, and so are tags. The check is lexical — it does not confirm that the item exists, because a database lookup per commit on the push path would make every push slower to catch a typo that the linker reports anyway.

Both live in the repository's push rules; see Repository rules for how to set them and how they inherit from the group.

Reference

Commit and merge-request links:

Code anchors:

Code TODOs:

Limits

Two of the operations here are capped, and both refuse with 429 rather than partially succeeding: nothing is created, no counter moves, and retrying without freeing space gives the same answer.

Anchors are capped twice, and the two are reported separately — running out on one work item is a nudge to tidy one ticket, while running out on the repository is a plan limit, and being told to delete anchors from an item that has one would be a wrong answer that reads like a plausible one.

Promoting a TODO takes two slots, because it mints a work item and pins its marker anchor in one transaction: an open work item slot in the repository, and an anchor slot. At either cap promotion is refused and the code TODO row stays exactly where it was, still visible and still promotable once you have freed some space.

Three more ceilings apply to what the platform maintains for you rather than to what you can create:

Nothing refuses a push when one of these is reached — a push is never rejected by anything on this page except the push rules above. At the commit-link cap that one work item stops collecting commits, and it stops there: the message's closing keyword and its quick actions are not applied either, because the link is written first and the rest of the message is abandoned when it cannot be. At the merge-request-link cap the item stops collecting merge requests, so its Code tab under-reports what names it. Nothing is written and no error reaches the pusher in either case, so a work item that has quietly stopped reacting to commits is worth checking against its link count. Indexing stops at the TODO cap while promotion keeps working. A commit that a force-push leaves on no branch has its link retracted and the count comes down with it, so a branch rebased three times does not burn a work item's budget three times over.

Per-push ceilings bound the work each push does, and every one of them degrades visibly rather than silently:

Two more bounds are per artefact rather than per push. One merge request body links at most 50 work items — a description is prose, and prose can hold five hundred numbers — and the tail is dropped and counted. A marker's text is kept to 255 characters; the identity is computed over the shortened form, so it stays stable.

An anchor left at needs_review heals on the next push to its file, or immediately when you re-resolve it.

Any of these limits can be raised for your namespace without changing plan — see Billing and plans for how to request an increase.

Troubleshooting

FAQ

Related