From 5b5d16c46f45373cf0a0c9074306a7de4a52bf06 Mon Sep 17 00:00:00 2001 From: Dave Kowalski Date: Sat, 25 Jul 2026 19:01:08 +0000 Subject: [PATCH] feat: branch/PR naming standard CI check Composite action that validates head branch and PR title against the fritzlab naming standard (role/bug-id/kebab + [bug-id] titles). Always exits 0 (warn-only) until the Bugs system is live. - check.sh: validation logic (branch form, title form, bug-id cross-check) - action.yaml: composite action wrapping check.sh - tests/run: 20-case test matrix (valid/invalid/chore/mismatch/dfritz) - .gitea/workflows/test.yaml: CI that runs the test suite Closes fritzlab/agenthub#559 --- .gitea/workflows/test.yaml | 13 ++++++++ README.md | 67 ++++++++++++++++++++++++++++++++++++++ action.yaml | 38 +++++++++++++++++++++ check.sh | 58 +++++++++++++++++++++++++++++++++ tests/run | 67 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 243 insertions(+) create mode 100644 .gitea/workflows/test.yaml create mode 100644 README.md create mode 100644 action.yaml create mode 100755 check.sh create mode 100755 tests/run diff --git a/.gitea/workflows/test.yaml b/.gitea/workflows/test.yaml new file mode 100644 index 0000000..cdb94dc --- /dev/null +++ b/.gitea/workflows/test.yaml @@ -0,0 +1,13 @@ +name: test +on: + push: + branches: [main] + pull_request: +jobs: + test: + runs-on: fritzlab + timeout-minutes: 5 + steps: + - uses: actions/checkout@v4 + - name: run tests + run: bash tests/run diff --git a/README.md b/README.md new file mode 100644 index 0000000..4f89d30 --- /dev/null +++ b/README.md @@ -0,0 +1,67 @@ +# action/check-naming + +Composite Gitea Action that validates a pull request's head branch name +and title against the fritzlab naming standard. Always exits 0 — +warn-only until the Bugs tracking system is live (see +[fritzlab/agenthub#557](https://code.fritzlab.net/fritzlab/agenthub/issues/557)). + +## Standard + +``` +Branch: /bug-/ e.g. dev/bug-x7k2m9/fix-terminal-resize +Chore: chore/ bug-less trivia only (dep bumps, typos, CI tweaks) +Title: [bug-x7k2m9] Fix terminal resize loss (chore PRs: no [bug-id] prefix) +``` + +- `` must be a roster handle: `dev` | `ux` | `ops` | `security` | `perf` | `architect` | `support` +- `` is `bug-` followed by lowercase alphanumeric characters +- `` 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 + continue-on-error: true # non-required until Bugs cutover + steps: + - uses: https://code.fritzlab.net/action/check-naming@v1 + with: + head-branch: ${{ github.head_ref }} + pr-title: ${{ github.event.pull_request.title }} + pr-author: ${{ github.event.pull_request.user.login }} +``` + +## 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 | + +## Behavior + +The check validates two things: + +1. **Branch form** — must be `/bug-/` or `chore/`. + Unknown roles, missing `bug-` segment, uppercase bug-ids, and empty + kebab descriptions all produce a `WARN[check-naming]` log line. + +2. **Title form** — for a `role/bug` branch the title should start with + `[bug-] `. For a `chore` branch the title should have no `[bug-id]` + prefix. If both carry a bug-id they must match. + +All violations print a `WARN[check-naming]: ...` line. The step always +exits 0 so it cannot block a PR. To harden to required after the Bugs +cutover: remove `continue-on-error: true` from the consuming workflow +and add the job's context to the repo's `status_check_contexts`. + +## Tests + +``` +bash tests/run +``` diff --git a/action.yaml b/action.yaml new file mode 100644 index 0000000..fbb7503 --- /dev/null +++ b/action.yaml @@ -0,0 +1,38 @@ +name: Check branch/PR naming +description: | + Validates that a PR's head branch and title follow the fritzlab naming + standard. Always exits 0 — warn-only until the Bugs system is live. + Produces WARN log lines for any violation. + + Standard: + branch: /bug-/ e.g. dev/bug-x7k2m9/fix-terminal-resize + chore: chore/ bug-less trivia only + title: [bug-] Description (chore PRs: no [bug-id] prefix) + + Role must be a roster handle: dev | ux | ops | security | perf | architect | support + Break-glass: PRs authored by dfritz are exempt. + +inputs: + head-branch: + description: Head branch name — github.head_ref on pull_request events. + required: true + pr-title: + description: PR title — github.event.pull_request.title. + required: true + pr-author: + description: | + PR author login — github.event.pull_request.user.login. + dfritz is exempt from all checks. + required: false + default: '' + +runs: + using: composite + steps: + - name: Validate naming + shell: bash + env: + HEAD_BRANCH: ${{ inputs.head-branch }} + PR_TITLE: ${{ inputs.pr-title }} + PR_AUTHOR: ${{ inputs.pr-author }} + run: bash "${{ github.action_path }}/check.sh" diff --git a/check.sh b/check.sh new file mode 100755 index 0000000..4631f78 --- /dev/null +++ b/check.sh @@ -0,0 +1,58 @@ +#!/usr/bin/env bash +# Branch and PR title naming-standard checker. +# Always exits 0 — warn-only until the Bugs system is live and STRICT=1 is set. +set -euo pipefail + +BRANCH="${HEAD_BRANCH:-}" +TITLE="${PR_TITLE:-}" +AUTHOR="${PR_AUTHOR:-}" + +# Break-glass: dfritz is exempt from all naming checks. +if [ "${AUTHOR}" = "dfritz" ]; then + echo "check-naming: dfritz break-glass — exempt" + exit 0 +fi + +WARN=0 +BRANCH_KIND="invalid" +BRANCH_BUG="" + +# ---- branch form ---- +# /bug-/ +if echo "${BRANCH}" | grep -qE "^(dev|ux|ops|security|perf|architect|support)/bug-[a-z0-9]+/[a-z0-9][a-z0-9-]*$"; then + BRANCH_KIND="role-bug" + BRANCH_BUG=$(echo "${BRANCH}" | sed -E 's|^[^/]+/(bug-[a-z0-9]+)/.*|\1|') +# chore/ +elif echo "${BRANCH}" | grep -qE "^chore/[a-z0-9][a-z0-9-]*$"; then + BRANCH_KIND="chore" +else + echo "WARN[check-naming]: branch '${BRANCH}' does not match convention" + echo " expected: /bug-/ (role: dev|ux|ops|security|perf|architect|support)" + echo " or: chore/" + WARN=1 +fi + +# ---- title form ---- +TITLE_BUG="" +if echo "${TITLE}" | grep -qE "^\[bug-[a-z0-9]+\] ."; then + TITLE_BUG=$(echo "${TITLE}" | sed -E 's|^\[(bug-[a-z0-9]+)\].*|\1|') +fi + +if [ "${BRANCH_KIND}" = "role-bug" ]; then + if [ -z "${TITLE_BUG}" ]; then + echo "WARN[check-naming]: title missing [${BRANCH_BUG}] prefix for branch '${BRANCH}'" + WARN=1 + elif [ "${TITLE_BUG}" != "${BRANCH_BUG}" ]; then + echo "WARN[check-naming]: bug-id mismatch — branch carries '${BRANCH_BUG}' but title carries '${TITLE_BUG}'" + WARN=1 + fi +elif [ "${BRANCH_KIND}" = "chore" ] && [ -n "${TITLE_BUG}" ]; then + echo "WARN[check-naming]: chore branch should not carry a [bug-id] title prefix" + WARN=1 +fi + +if [ "${WARN}" -eq 0 ]; then + echo "check-naming: ok" +fi + +exit 0 diff --git a/tests/run b/tests/run new file mode 100755 index 0000000..1e75f51 --- /dev/null +++ b/tests/run @@ -0,0 +1,67 @@ +#!/usr/bin/env bash +# Tests for check.sh — exercises valid/invalid branch+title matrices. +set -euo pipefail + +SCRIPT="$(cd "$(dirname "$0")/.." && pwd)/check.sh" +PASS=0 +FAIL=0 + +check() { + local desc="$1" want_warn="$2" branch="$3" title="$4" author="$5" + local out rc=0 + out=$(HEAD_BRANCH="$branch" PR_TITLE="$title" PR_AUTHOR="$author" bash "$SCRIPT" 2>&1) || rc=$? + if [ "$rc" -ne 0 ]; then + echo "FAIL [$desc]: script exited $rc (must always exit 0)" + echo " output: $out" + FAIL=$((FAIL + 1)) + return + fi + local got_warn=0 + echo "$out" | grep -qE "^WARN" && got_warn=1 || true + if [ "$got_warn" -eq "$want_warn" ]; then + echo "PASS [$desc]" + PASS=$((PASS + 1)) + else + echo "FAIL [$desc]: expected warn=$want_warn got=$got_warn" + echo " output: $out" + FAIL=$((FAIL + 1)) + fi +} + +# break-glass +check "dfritz exempt — invalid branch" 0 "totally/wrong-branch" "no prefix" "dfritz" +check "dfritz exempt — mismatch" 0 "dev/bug-abc/thing" "[bug-xyz] Thing" "dfritz" + +# valid role/bug — all roster handles +check "dev/bug matching title" 0 "dev/bug-x7k2m9/fix-terminal-resize" "[bug-x7k2m9] Fix terminal resize" "dev" +check "architect/bug matching title" 0 "architect/bug-abc123/refactor-auth" "[bug-abc123] Refactor auth" "architect" +check "ops/bug matching title" 0 "ops/bug-zz9/deploy-tweak" "[bug-zz9] Deploy tweak" "ops" +check "security/bug matching title" 0 "security/bug-s1a2/patch-cve" "[bug-s1a2] Patch CVE" "security" +check "perf/bug matching title" 0 "perf/bug-p0p0/reduce-latency" "[bug-p0p0] Reduce latency" "perf" +check "ux/bug matching title" 0 "ux/bug-u1u1/polish-modal" "[bug-u1u1] Polish modal" "ux" +check "support/bug matching title" 0 "support/bug-sup9/clarify-error" "[bug-sup9] Clarify error" "support" + +# valid chore form +check "chore — no title prefix" 0 "chore/bump-deps" "Bump dependency versions" "dev" +check "chore — plain title" 0 "chore/fix-a-typo" "Fix typo in README" "ops" + +# warn: role/bug branch but no [bug-id] title prefix +check "role/bug no title prefix" 1 "dev/bug-x7k2m9/fix-resize" "Fix resize" "dev" + +# warn: bug-id mismatch between branch and title +check "bug-id mismatch" 1 "dev/bug-x7k2m9/fix-resize" "[bug-zzzzz1] Fix resize" "dev" + +# warn: chore branch with [bug-id] title prefix +check "chore with bug-id title" 1 "chore/bump-deps" "[bug-abc123] Bump deps" "dev" + +# warn: invalid branch forms +check "invalid — no role prefix" 1 "feature/foo-bar" "Add feature" "dev" +check "invalid — missing bug segment" 1 "dev/fix-something" "Fix something" "dev" +check "invalid — unknown role" 1 "unknown/bug-abc/thing" "[bug-abc] Thing" "dev" +check "invalid — uppercase bug-id" 1 "dev/bug-ABC123/thing" "[bug-ABC123] Thing" "dev" +check "invalid — empty kebab" 1 "dev/bug-x7k2m9/" "[bug-x7k2m9] No kebab" "dev" +check "invalid — no bug prefix on seg" 1 "dev/x7k2m9/fix-resize" "Fix resize" "dev" + +echo "" +echo "Results: ${PASS} passed, ${FAIL} failed" +[ "${FAIL}" -eq 0 ]