Descriptions

PR descriptions

PR descriptions can fill empty descriptions, or keep a generated summary between <!-- auditor:summary:start --> and <!-- auditor:summary:end --> markers. Text outside the markers is never changed.

The description follows the team template under PR descriptions: Risk (a Low, Medium or High callout naming the riskiest behavior change), Summary (what the code now does, without assuming the author's intent), Changes (a file table or a list), Ticket, Preview and Flags, in the order you set, each switchable and left out when empty. With Repository templates first on, a repository's .github/pull_request_template.md is filled heading by heading, and only sections it has no heading for are added. Flags are a checklist: Auditor ticks the ones that apply, and after that the author's ticks are kept.

The Ticket section links a ticket found in the branch name, then the PR title, then commit messages, using the ticket keys and aliases on each repository's Tickets tab (alias p for key PAY turns maya/p412-retry into PAY-412). Without a connection a tracker is a link target only, so the ticket is linked without its title. When no ticket is found, Auditor leaves a note, leaves the section out, or asks in a comment; replying with a ticket ID adds the link to the description. The Preview section shows the URL a deploy integration such as Vercel reported to GitHub for the head commit.

Tickets

Auditor finds a pull request's ticket from its branch name, title or commits, using the keys you give each repository in its settings (the Tickets tab), and links it in the description. Connect the tracker and the review reads the ticket too. The deep review gets the ticket's title and text as context for what the change is meant to do, and one extra request compares the two: it says so when the change does not look like the ticket's work at all (a wrong ticket ID, say), and otherwise lists up to three things the ticket asks for that the change does not do. Those appear as a Ticket note on the review, in the reply to @auditor review and in the check run. When a review has no findings, a change that may not match its ticket is also named in the check's title. They are read from the ticket, not from the code, and never fail the check. The comparison is part of the deep review, so it doesn't run when the deep review is off or skipped. On a pull request from a fork, Auditor links the ticket but never reads it from the tracker, since whoever opens a fork can name any ticket.

To connect a tracker, add it under Issue trackers on the Auditor page's Add-ons tab and open it. Linear can Sign in, which Auditor keeps refreshed; or choose Use a token (Connect for Jira and Shortcut) and paste an API token: a personal API key for Linear, an API token for Shortcut, or an API token with its account's email for Jira. A token is checked, stored encrypted, and never shown again; use one that can only read. A GitHub issue the pull request closes (Fixes #12) is used as the ticket when no tracker ticket is found, with no connection. For Linear, Auditor can also say what the check finds on the issue and work on issues you mention it on: see Auditor in Linear.