Files
check-naming/README.md
T
Donavan FritzandClaude Fable 5.1 4c17d84dd2
test / test (pull_request) Successful in 12s
Accept Mission work branches and native Ticket ids
AgentHub supplies every Mission a work_branch of the form mission/<mission-id>,
and Bug ids were retired in favour of native Ticket ids. The check accepted
neither, so no Mission-driven pull request could pass validate / naming in a
consumer that pins this action (t-mazzph405ay0).

A Mission branch needs a Conventional title and the visible attribution, and
no Tracking section, because the Mission is the tracking. Role branches now
carry a native Ticket id or the retired Bug id; the title and Tracking rules
are unchanged apart from the id they name.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-11-04 11:35:54 -06:00

121 lines
5.6 KiB
Markdown

# action/check-naming
Composite Gitea Action that validates a pull request's branch, title, Bug
tracking, PR-description AI authorship, and commit range against the fritzlab
Git standard. The current action fails (exits 1) on any violation; `@v1` is the legacy warn-only release
(Bugs program: see
[fritzlab/agenthub#557](https://code.fritzlab.net/fritzlab/agenthub/issues/557)).
## Standard
```
Branch: <role>/t-<ticket-id>/<kebab-description> e.g. dev/t-mazzph405ay0/fix-terminal-resize
<role>/bug-<id>/<kebab-description> retired Bug ids remain accepted
Mission: mission/mi-<mission-id> the work_branch AgentHub supplies to a Mission
Chore: chore/<kebab-description> untracked trivia only (dep bumps, typos, CI tweaks)
Title: [t-mazzph405ay0] fix(terminal): preserve resize state
fix(terminal): preserve resize state on a Mission branch
```
- `<role>` must be a roster handle: `dev` | `ux` | `ops` | `security` | `perf` | `architect` | `support`
- `<ticket-id>` is a native AgentHub Ticket id: `t-` and twelve characters from `0123456789abcdefghjkmnpqrstvwxyz`; `bug-<id>` (lowercase alphanumerics) is the retired form
- `<mission-id>` is `mi-` and twelve of the same characters; a Mission branch's title is `type(scope): description` with no tracked-id prefix and no `## Tracking` section
- `<kebab-description>` is lowercase alphanumeric with hyphens, starting with a letter or digit
- When both the branch and the title carry a tracked id they **must match**
- Break-glass: PRs authored by `dfritz` are exempt from all checks
## Usage
```yaml
on:
pull_request:
types: [opened, synchronize, reopened, edited]
jobs:
naming:
runs-on: fritzlab
timeout-minutes: 5
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: https://code.fritzlab.net/action/check-naming@<commit-sha>
with:
head-branch: ${{ github.head_ref }}
pr-title: ${{ github.event.pull_request.title }}
pr-author: ${{ github.event.pull_request.user.login }}
server-url: ${{ github.server_url }}
token: ${{ github.token }}
base-sha: ${{ github.event.pull_request.base.sha }}
head-sha: ${{ github.event.pull_request.head.sha }}
```
The explicit `edited` activity is part of the enforcement contract: changing
the PR description must issue a new naming status for the same commit.
Keep required code-validation jobs in a separate workflow that does not run on
`edited`; Gitea treats a skipped required context as passing.
To wire a new repo warn-only first, add `continue-on-error: true` to the
job — the step still fails, but the job cannot block the PR.
## Inputs
| Name | Required | Description |
|---|---|---|
| `head-branch` | yes | Head branch name — `github.head_ref` |
| `pr-title` | yes | PR title — `github.event.pull_request.title` |
| `pr-author` | no | PR author login — `github.event.pull_request.user.login`; `dfritz` is exempt |
| `server-url` | yes | Gitea server URL — `github.server_url` |
| `token` | yes | Gitea Actions token — `github.token` |
| `base-sha` | yes | Base commit — `github.event.pull_request.base.sha` |
| `head-sha` | yes | Head commit — `github.event.pull_request.head.sha` |
## Behavior
The check validates four things for every non-break-glass Agent PR:
1. **Branch form** — must be `<role>/bug-<id>/<kebab>` or `chore/<kebab>`.
Unknown roles, missing `bug-` segment, uppercase bug-ids, and empty
kebab descriptions all produce a `FAIL[check-naming]` log line.
2. **Title form** — for a `role/bug` branch the title must be
`[bug-<id>] type(scope): description`. The type starts with a lowercase
letter and the type and one-component scope contain only lowercase letters,
digits, and hyphens. An optional `!` may follow the scope, and the description
must contain a non-whitespace character. For a `chore` branch the title must
have no `[bug-id]` prefix. If both carry a bug-id they must match.
3. **Tracking and attribution** — on Bug-backed work, `## Tracking` contains both the literal
`Fixes bug-<id>` automation token and the matching navigable
`https://agenthub.fritzlab.net/bug-<id>` URL. Every PR has a separate
`## Attribution` section containing the canonical `Authored-By`
product/model watermark. The action loads the body from Gitea by repository
and PR number, then asks Gitea to render it; both calls have a bounded
5-second connection and 15-second total wait. It then checks visible
`<h2>` sections outside collapsed `<details>` content. Fenced, commented,
scripted, or collapsed copies do not satisfy the visible provenance contract.
4. **Commit range** — `base-sha` and `head-sha` must identify available commits,
and `base-sha..head-sha` must contain at least one PR commit.
The naming job must check out full history before this action.
Attribution is required only in the PR description; commit messages are not
inspected. Existing commit trailers remain valid history, but no trailer is
required for a new commit.
Every violation prints a `FAIL[check-naming]: ...` line and the step
exits 1. To make the check required on a repo: drop any
`continue-on-error: true` from the consuming workflow and add the job's
context to the repo's `status_check_contexts` in agenthub `hub/hub.yaml`.
## Versions
- unreleased — requires Bug tracking and visible PR attribution, without commit-message watermarks.
- `v2` — enforces branch and title naming.
- `v1` — legacy warn-only: logs `WARN` lines, always exits 0.
## Tests
```
bash tests/run
```