architect
e2e7c825a8
test / test (pull_request) Successful in 7s
Authored-By: Codex (GPT-5) <noreply@openai.com>
106 lines
4.4 KiB
Markdown
106 lines
4.4 KiB
Markdown
# action/check-naming
|
|
|
|
Composite Gitea Action that validates a pull request's branch, title, Bug
|
|
tracking, and AI authorship 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>/bug-<id>/<kebab-description> e.g. dev/bug-x7k2m9/fix-terminal-resize
|
|
Chore: chore/<kebab-description> bug-less trivia only (dep bumps, typos, CI tweaks)
|
|
Title: [bug-x7k2m9] Fix terminal resize loss (chore PRs: no [bug-id] prefix)
|
|
```
|
|
|
|
- `<role>` must be a roster handle: `dev` | `ux` | `ops` | `security` | `perf` | `architect` | `support`
|
|
- `<bug-id>` is `bug-` followed by lowercase alphanumeric characters
|
|
- `<kebab-description>` is lowercase alphanumeric with hyphens, starting with a letter or digit
|
|
- When both the branch and the title carry a bug-id they **must match**
|
|
- Break-glass: PRs authored by `dfritz` are exempt from all checks
|
|
|
|
## Usage
|
|
|
|
```yaml
|
|
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 }}
|
|
pr-body: ${{ github.event.pull_request.body }}
|
|
server-url: ${{ github.server_url }}
|
|
token: ${{ github.token }}
|
|
base-sha: ${{ github.event.pull_request.base.sha }}
|
|
head-sha: ${{ github.event.pull_request.head.sha }}
|
|
```
|
|
|
|
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 |
|
|
| `pr-body` | yes | PR description — `github.event.pull_request.body` |
|
|
| `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 start with
|
|
`[bug-<id>] `. For a `chore` branch the title must have no `[bug-id]`
|
|
prefix. If both carry a bug-id they must match. The description is a
|
|
plain-language imperative; Conventional Commit forms such as `fix(scope):`
|
|
are rejected.
|
|
|
|
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 asks Gitea to render the body with a
|
|
bounded 5-second connection and 15-second total wait, then checks visible
|
|
`<h2>` sections outside collapsed `<details>` content. Fenced, commented,
|
|
scripted, or collapsed copies do not satisfy the visible provenance contract.
|
|
|
|
4. **Commit attribution** — every commit in `base-sha..head-sha`, including
|
|
commits on `chore/` branches, ends with
|
|
the canonical `Authored-By` trailer, separated from the message body by a
|
|
blank line. The naming job must check out full history before this action.
|
|
|
|
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 — adds Bug tracking plus PR and commit attribution enforcement.
|
|
- `v2` — enforces branch and title naming.
|
|
- `v1` — legacy warn-only: logs `WARN` lines, always exits 0.
|
|
|
|
## Tests
|
|
|
|
```
|
|
bash tests/run
|
|
```
|