check-naming/README.md

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).

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): preserve resize state

• <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

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 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