What Colony puts on a pull request
What Colony puts on a pull request
Section titled “What Colony puts on a pull request”Colony writes pull request content for the person who decides whether to merge. The PR carries the merge decision; the linked issue is the process log (every round, retries, the trace). Colony does not mirror process detail onto the PR.
All PR text is rendered by one shared renderer, so every Colony-authored PR has the same shape.
Title and body
Section titled “Title and body”The title is <type>: <change summary> (#N), where N is the issue number. Colony regenerates it each round unless a human has edited it.
The body starts with a status line, followed by a brief between <!-- colony:brief:start --> and <!-- colony:brief:end --> markers. Colony regenerates everything between the markers on each developer round. Text you write outside the markers is never touched. The body ends with the attribution footer (once) and exactly one Closes #N.
The brief has these sections, in this order:
| Section | Content |
|---|---|
| What this does | One short description of the change |
| Since last review | From round 2: what changed in response to review |
| Changes | The change list, grouped by area |
| Review focus | Points the reviewer should look at |
| Verification | Results from Colony’s own records (deterministic checks, CI), never from the developer’s claims |
| Outside the plan | Changes beyond the planned scope |
Epic PRs add a Subtasks roll-up.
Each section is trimmed at item boundaries with a +N more on #N pointer to the issue; text is never cut mid-word, mid-list or mid-table. Every file:line reference is a link into the PR’s Files tab. When no valid brief exists, Colony writes a fallback body with only the verification results and a changed-file count.
Status line
Section titled “Status line”One line at the top of the body, updated on every transition that touches the PR. It replaces the older draft and ready banners in place.
| State | Line |
|---|---|
| Draft, awaiting review | 🟡 Status: Draft, automated review pending. |
| In review | 🔵 Status: In automated review. |
| Changes requested | 🟠 Status: Round N: changes requested, Colony is reworking. |
| Approved, waiting for a human | ✅ Status: Approved at sha, ready for your review. |
| Approved, auto-merge | ✅ Status: Approved, will merge automatically when checks pass. |
| Escalated | 🛑 Needs your decision: <reason> Action: <action> |
| Blocked | ⏸️ Status: Blocked: <reason>. |
| Merged | 🟣 Status: Merged. |
| Superseded | ⚪ Status: Superseded and closed: <links>. |
| Closed | ⚪ Status: Closed without merge: <links>. |
Escalation is visually distinct from approval, so “Needs your decision” always means a human has to act.
Colony writes a hidden write-time stamp next to the status line (<!-- colony:pr-status-at:N -->) and in the brief region (<!-- colony:brief-at:N -->). A retried (queued) write never overwrites a newer one. Direct writes use the worker host’s clock; queued writes use Postgres created_at. Keep worker and Postgres hosts NTP-synced: clock skew larger than the gap between two writes can drop a newer write or let a stale one through.
Reviews
Section titled “Reviews”The formal review on the PR is a compact verdict:
- A head line:
**Colony** · Reviewer — ✅ Approved · round N · \sha“. - The reason, in a few sentences.
- Required changes as a numbered list.
- Everything else collapsed in a
<details>block. - A
Full history on owner/repo#Nlink to the issue.
When Colony approves a PR that waits for a human (auto-merge off), it also anchors up to 3 of the brief’s Review focus points that have a file and line as inline comments on the approving review, so they appear next to the code in the Files tab. They are informational and need no resolving. Changes-requested reviews, re-approvals, conflicted PRs and Dependabot PRs get no inline comments, and a rejected anchor never blocks the approval.
The Colony Review check run carries the same verdict. Colony posts one verdict per head commit. A re-review on an unchanged head with the same verdict posts nothing; push a commit to get a new verdict. A re-approval after the base branch moved, with no code change, is a single line. Epic reviews show only findings that are new or changed since the previous round. Reviews on external PRs carry the attribution footer and no issue-history line.
Colony never edits the title or body of a PR it did not author (external and Dependabot PRs).
Notification tiers
Section titled “Notification tiers”Routine progress only updates the status line, silently. Humans are notified when a decision is needed:
| Event | What happens |
|---|---|
| Approved behind a human gate (no auto-merge) | Colony requests a review from the stewards |
| Escalated | Colony requests a review from the stewards and posts one PR comment with the reason, the decision needed and /colony:retry / /colony:reimplement |
| Closed without merge | One PR comment, e.g. Replaced by #A, #B |
| Approved with auto-merge | No request |
Stewards are the epic’s assignees, else default_stewards. Review requests and escalation comments are deduplicated per transition. Escalation and close-without-merge are the only events that get a PR comment, and those comments carry no attribution footer.
Merging
Section titled “Merging”merge.method (merge, squash or rebase, default merge) sets how Colony merges. Epic PRs into the default branch always use a merge commit. Colony’s merge commit uses the PR title as its title and a condensed message from the brief (what the change does, the change list, Closes #N). PRs without a stored brief, such as Dependabot PRs, get the title only. With rebase, GitHub ignores the title and message.
Epics accepted through the API. An epic accepted with colony_act invoke intent=approve has no approval on the code host. If the base branch’s ruleset requires an approving review, either put the Colony App on the ruleset’s bypass list (no review is submitted), or let Colony submit an approving review from its review identity that records the verdict. If the rules can’t be satisfied (the App is the PR author and cannot approve its own PR, code owners are required, more than one approval is required, or Azure DevOps requestor policy applies), Colony does not merge: it posts a comment explaining which rule blocked the merge, drops the verdict and returns the item to human-review-ready to be decided again. See Accepting an epic.
Developer commits use <type>: <title> for round 1 and <type>: address review round N — <summary> afterwards, with a Refs: #N trailer.