Commit summaries
What Heimdall reads when a linked pull request merges, how it says what shipped for the item in words a reporter and a tester can use, where the answer lives, who it is written as, what it costs, and the lines it never crosses.
By the end of this page you will know how Heimdall's commit summaries work: what it is given when a pull request merges, how it must answer, where the answer is kept, who the call is made as, what it costs, and what it never does. Reading the answer under a pull request in an item's Code section, and asking for one by hand, is on the Git linking page.
When it runs
A pull request linked to an item merges, the repository's webhook reports it, and the item moves as the project's switches ask. In the same breath, on a project whose AI assists are on, Heimdall is asked what shipped: the request is queued, so the webhook answers GitHub at once and the summary appears under the pull request a few seconds later. A pull request that already carries a summary is left alone; a person asks again with Summarise Again when the answer should be refreshed. Nothing runs on a project whose assists are off, and nothing runs for a branch, a commit or a pull request that closed without merging.
The automatic call is made as a person, because every assist is: the item's assignee, or its reporter when nobody is assigned, or the project's lead developer or project manager. That person must be allowed to use the assists and to change the project's items; when nobody on the item or the project may, nothing is written and nothing is charged, and a person who may can still ask by hand.
What Heimdall is given
Heimdall sees no code and no diff. Everything it knows arrives in one brief, written the same way every time and read through the same services the backlog reads through, so it sees nothing the person it acts as could not open:
- The item: its kind, key and title, its story sentence, its epic, its description as plain text, and its acceptance criteria, up to ten of them.
- The pull request as the webhook recorded it: its number and title, who opened it, which repository it lives in, when it merged, and the lines added and removed.
- The commits linked to the item: the first line of each commit message that carried the item's key, with its author and date, the newest first, up to thirty; the branches linked to the item, and any other pull request on it.
A commit whose message left the key out is not linked to the item and so is not in the brief; the summary says plainly when the messages are too thin to tell what happened.
How it must answer
The answer has two parts, and both are kept:
- The summary: two to four plain sentences on what changed, in the words of the messages, and how much of it there was.
- The highlights: up to five short lines a tester can act on. A criterion the messages say was met; a criterion the messages never mention; a migration, a flag, a setting or a dependency the messages name; a risk the size or the wording suggests.
Heimdall is told never to invent a change, a file or a behaviour the messages do not carry, and never to guess at code it cannot see. Empty lines are dropped, the highlights are cut at five, and the summary is kept as plain text.
Where the answer lives
The answer is kept on the pull request's own row, not on the item: the item's Code section shows it
under the merged pull request, the Code references API answers
it as summary, highlights and summarised_at on the reference, and an agent reads the same
through list_code_references. Asking again replaces the earlier answer; nothing is versioned,
because the words are Heimdall's account of the messages, not the team's record.
What it costs
Each summary is one call, charged to the team's monthly AI budget and booked in the usage statement under Commit summaries, against the project and the person it was made as; see Usage and budgets. A spent budget stops the automatic summaries silently and refuses a request by hand with a message; nothing is booked for a call that fails.
Ask by hand
Summarise with Heimdall beside a merged pull request in an item's Code section asks for the
first summary, and Summarise Again replaces one; both need the project's assists on and the
permission to use them and to change items. Over the API, POST /v1/code-references/{codeReference}/summary
does the same under ai:use; over MCP, summarise_shipped_code.
Where it stops
- Heimdall never moves the item, never comments on it and never changes the pull request itself; it writes the summary and nothing else.
- It reads no code: a repository's contents never leave the host. The brief carries titles, messages, counts and dates, and the answer is only as good as the messages.
- It never runs for a client guest, on a project with the assists off, or for a person who may not use the assists.
- It never summarises an open pull request, a branch or a commit; the summary is about what shipped, and only a merge ships.
Related
Git linking
Reading the summary under a pull request, and asking for one by hand.
Pull request flow
What else happens when a pull request merges: the move and what is announced.
summarise_shipped_code
The MCP tool that asks for the summary from an agent.
Usage and budgets
Where each summary is booked and what stops it.
How is this guide?
Last updated on
Sprint planner
What Heimdall reads before it proposes a scope for a sprint, the rules it plans by, how its answer is checked against the candidates before you see it, why nothing is planned until you tick it, what a proposal costs and where it stops.
Brief import
What Heimdall is given before it reads a brief, how it fills each kind of suggestion from one uniform row, how it judges its own confidence, why it runs on the queue as you, what it costs and where it stops.