vibey-gh

Release automation for a GitHub repository: provenance fingerprints, derived version bumps, exact-head AI review and repair, a merge train, dual-channel releases, comprehensive documentation maintenance, and post-release branch realignment.

No dependencies. Everything is stdlib. This runs in every CI job of every repository that adopts it, so a dependency it grows is a dependency all of them grow.

In one sentence: install vibey-gh once, describe your repository in .vibey-gh.toml, and let exact-head gates carry a change from its first push through review, bounded repair, protected-branch merge, release, documentation, packages, and provenance—while stopping for conditions that require an operator.

Start here

• Evaluating the project? Read Why vibey-gh, then What happens after a push.
• Installing it? Follow Requirements, Quick start, and Adoption checklist.
• Operating it? Keep Workflows, Failure and recovery model, Troubleshooting, and .github/README.md (workflow inventory, AI trust boundary, and admin recovery paths) nearby.
• Extending it? Begin with Architecture, Security model, and CONTRIBUTING.md.

What vibey-gh does—and does not do

vibey-gh is a repository delivery control plane, not a replacement for your test suite, package builder, or application runtime. Your repository owns what “correct” means. This project owns the transitions around that evidence: when a result is current, when a repair is permitted, when a protected branch may advance, which release channel receives an artifact, and what proof travels with it.

It is deliberately opinionated about four invariants:

1. Only exact-head evidence counts. A green check or review for an older commit cannot authorize the current commit.
2. Repair may improve the work, never the standard. Automation cannot lower coverage, remove a required job, soften an assertion, or disguise an operational failure as code.
3. Permanent branches may advance but may never be deleted. Managed workflows can merge into develop and main; no managed path emits a deletion refspec for either.
4. Untrusted work is data in privileged jobs. Source and logs may be inspected or edited, but contributor-controlled commands are not executed beside write credentials.

Why vibey-gh

GitHub can run tests, but a dependable open-source delivery system needs much more than a green test job. It must intake branches, keep documentation honest, review outside work, repair actionable failures without weakening gates, merge through protected branches, derive versions, publish to the correct registry, create releases and packages, deploy discoverable documentation, preserve provenance, and recover safely when a trusted post-merge job fails. vibey-gh installs that complete event-driven path as one portable, auditable contract.

Use it when you want develop to be the integration channel, main to be production, and every transition between them to be reproducible and policy checked.

Requirements

• Python 3.11 or newer, Git, and the GitHub CLI (gh).
• A GitHub repository with Actions enabled and Pages configured for Actions deployments.
• ANTHROPIC_API_KEY for AI review, repair, conflict resolution, and documentation upkeep.
• AUTOMERGE_TOKEN when the default Actions token cannot merge or manage repository settings.
• PyPI and TestPyPI trusted-publishing environments when Python publication is enabled.

The installed Python runtime has no third-party dependencies. Workflow-only tools are pinned to immutable action revisions and run in GitHub-hosted jobs.

Quick start

pip install vibey-gh
vibey-gh install

Commit the generated hooks, workflows, assets, and configuration; configure the required secrets and publishing environments; then verify the complete installation:

vibey-gh check --ci
git status --short

Push a topic branch. Branch intake creates a draft PR, exact-head scans decide when it is stable, and the event chain handles review, repair, merge, promotion, publication, docs, tagging, GitHub Release creation, and repository-profile reconciliation.

Adoption checklist

1. Create or confirm permanent develop and main branches.
2. Install vibey-gh on a topic branch and review every generated file before committing.
3. Author your own CI and Release workflows with those exact names; install does not render them, and the rest of this checklist assumes they exist. See What gets installed for the required Release behavior.
4. Add a repository-level ANTHROPIC_API_KEY; environment-only secrets are not available to the PR automation jobs that perform guarded review and repair.
5. Add AUTOMERGE_TOKEN when the default Actions token cannot merge through your ruleset, update repository settings, or create the required pull requests.
6. In Settings → Actions → General, grant read/write workflow permissions and allow Actions to create and approve pull requests.
7. Configure GitHub Pages to deploy from GitHub Actions.
8. Configure testpypi and pypi trusted-publishing environments if this is a Python package. develop is the preview channel; main is production.
9. Configure the branch ruleset. Require your ordinary scans plus PR automation / gate; do not use a rule that automatically deletes develop after a promotion merge.
10. Run vibey-gh check --ci, inspect git diff, commit the generated assets, and push.
11. Confirm the first branch creates one draft PR and that the exact-head gate—not an older workflow result—controls its merge.

What gets installed

The installer manages .githooks/, selected files under .github/workflows/, and the release-site assets used by the dual-channel Pages deployment. Existing hooks are moved to <hook>.local and chained. Managed workflow files are replaced when their rendered source changes; opt out of individual workflows with [install].workflows rather than editing a generated copy that the next installation will overwrite.

install does not render CI or Release workflows: every repository's build, test, and publish steps are different, so these two stay hand-authored by the adopting repository. This is intentional, not an oversight, but the names and behavior are load bearing: release-repair.yml watches for a workflow_run named exactly CI, and github-release.yml, release-surfaces.yml, and release-repair.yml all watch for one named exactly Release. Your Release workflow must run on develop and main, derive and apply the version with vibey-gh version --apply (or an equivalent explicit --dev/--since invocation), build the package, and publish it through the testpypi (from develop) and pypi (from main) trusted-publishing environments named in Requirements. Skip or misname either workflow and the installer, gate, and docs will all stay green while GitHub Release creation, release surfaces, repository-profile reconciliation, and release repair silently never trigger.

What happens after a push

topic branch push
      │
      ▼
one reusable draft PR
      │
      ▼
all configured scans settle for the exact head SHA
      │
      ├── actionable failure ──► bounded AI repair ──► new SHA ──► rescan
      ├── conflict ────────────► guarded conflict repair ────────► rescan
      ├── operator-only issue ─► explicit blocked state and required action
      └── green ───────────────► semantic docs review (+ outside-author code review)
                                      │
                                      ├── findings ─► bounded repair ─► rescan + rereview
                                      └── pass ─────► exact-head gate
                                                            │
                                                            ▼
                                            squash merge to develop
                                                            │
                                                            ▼
                                             promotion PR to main
                                                            │
                                                            ▼
                                             rebase merge + release

Every new commit invalidates earlier evidence and starts evaluation for the new SHA. The repair budget is three attempts per contributor lineage by default. Bot-authored repair commits do not reset it; a new human/contributor commit does.

Your first successful run

On a healthy installation you should observe, in order:

• a draft PR for the topic branch;
• ordinary CI, provenance, security, API-drift, and documentation scans;
• an exact-head semantic documentation verdict—even for a trusted author;
• an outside-author code review when applicable;
• a successful PR automation / gate attached to the current SHA;
• a squash merge into develop;
• a TestPyPI development release and Preview documentation update;
• a develop → main promotion PR;
• a rebase merge into main, followed by PyPI, tag, GitHub Release, GHCR, Production documentation, and repository-profile verification.

No single repository must enable every publishing surface. Disable or omit workflows that do not match the repository, then keep the remaining contract explicit and testable.

Architecture

Configuration value objects describe desired state; deterministic evaluators judge versions, PRs, documentation, and interface parity; CLI adapters call those policies; and rendered workflows provide the privileged GitHub edge. Managed templates are the source of truth, and dogfood tests require this repository's installed copies to match them. Every decision is tied to an exact commit SHA, and stale workflow events are ignored. See Architecture, Workflows, and Threat model.

Security model

Privileged jobs treat PR content, logs, model output, and repository instructions as untrusted. They inspect or edit constrained files but never execute contributor-controlled package managers, tests, builds, or scripts while write credentials are present. Ordinary PR CI validates resulting commits. Managed automation never sends a deletion refspec for main or develop, and automatic branch deletion stays disabled because develop is itself the head of production promotion PRs. See SECURITY.md.

Repair and conflict publication recheck the PR's exact head immediately before committing and again after any non-fast-forward push rejection; a concurrent human or bot update is discarded as a stale no-op rather than force-pushed over, consumes no repair attempt, and never mutates a permanent branch from an obsolete checkout—including when develop or main is itself the PR head during a promotion. See docs/security.md.

The sole history-rewrite exception is Conventional Commits self-healing: only a same-repository linear topic branch may be normalized and pushed with an exact-head --force-with-lease. Forks, stale heads, merge commits, develop, and main fail closed, and contributor-controlled code is never executed by that privileged job.

Webhook delivery IDs are claimed atomically in a persistent local state directory, so replay rejection survives CLI process restarts and concurrent receivers. Deployments must place VIBEY_GH_WEBHOOK_STATE_DIR on durable, access-controlled storage and retain the raw request bytes for HMAC verification; see the CLI and adapter reference.

Commands

Run vibey-gh --help and read docs/cli.md for the full reference.

install writes the git hooks and workflow files into your repository and points core.hooksPath at them. A hook you already have is moved aside to <name>.local and chained, never discarded — adopting this should not silently drop checks somebody thought were important.

What it does

Provenance, enforced in two places

Every code change carries a fingerprint. Source files get a header comment; every commit gets a Conventional Commit subject and a trailer. The local hook normalizes the subject before appending provenance, and CI audits the complete PR range. The trailer is what makes the rule total — a change to a Markdown file or a JSON manifest still arrives as a commit, and the commit is fingerprinted even when the file cannot be.

vibey-gh check                 # are the hooks installed and the fingerprints intact?
vibey-gh check --apply         # add missing file headers and dedupe a repeated header
vibey-gh check --commits main..HEAD    # and every commit trailer in a range

The pre-push hook refuses the push if either half is missing, to any branch, local or remote. git push --no-verify still works, because a hook that cannot be bypassed in an emergency gets uninstalled instead; CI applies the same rule server-side, so skipping it locally defers the failure rather than avoiding it.

Advanced, fully traceable branch diagnostics

Every configured Python source is compiled during vibey-gh check, and every control-flow opcode must be supported by the package-wide branch tracer. Enable it only when diagnosing a run; normal commands remain quiet:

VIBEY_GH_DEBUG=1 vibey-gh check
VIBEY_GH_DEBUG=1 VIBEY_GH_DEBUG_LOG=.vibey-gh/branch-trace.jsonl vibey-gh merge-train

The JSONL stream records each branch evaluation and, when CPython exposes the successor, its taken or fallthrough outcome. Every event includes a schema version, trace ID, monotonic sequence, UTC and monotonic timestamps, PID, thread ID, source, function, line, bytecode offset/opcode/target, GitHub run/attempt/SHA correlation, the previous event hash, and its own SHA-256 hash. That produces an ordered, tamper-evident chain that can be joined back to a CI invocation. It records control-flow metadata only—never locals, arguments, return values, exception messages, environment values, or secrets. Set VIBEY_GH_TRACE_ID to propagate an existing correlation ID; otherwise a UUID is generated.

vibey-gh itself only ever instruments its own installed package: VIBEY_GH_DEBUG traces vibey_gh's internals, not a consuming project's source tree. Projects embedding vibey_gh.debugging.enable(roots=(your_package_dir,)) directly get branch tracing scoped to their own code instead.

Versions derived, not remembered

vibey-gh version --since origin/main --explain     # what should this release be?
vibey-gh version --since origin/main --apply       # write it to every version file
vibey-gh version --dev "$GITHUB_RUN_NUMBER"        # <release>.dev<n> for a TestPyPI build

none is a legitimate answer. This has to be automatic: a PyPI upload with skip-existing turns an unbumped release into a green run that publishes nothing, silently, with no warning anywhere. A human-maintained version is a silent-failure generator.

Version files may be Python (__version__ = "..."), JSON (a version key, at the top level or under metadata), or TOML (the [project] table — and only that table, because pyproject.toml has others carrying a version key and bumping the wrong one is worse than not bumping).

The merge train

vibey-gh merge-train --dry-run
vibey-gh merge-train --method squash

The normal path is event-driven: the PR-automation gate dispatches vibey-gh merge-train --pr NUMBER as soon as the exact current head is green. The weekly and manual modes remain recovery backstops. A ready PR is open, current with its target, conflict-free, green, free of requested changes, and carries a successful exact-head PR automation / gate when an outside-author review is required.

Outside authors receive a fresh structured Claude review after scans pass. Findings feed the same bounded repair loop as failed scans. Forks are never mutated with privileged credentials; when a fork needs edits, automation preserves its exact head in a linked repository-owned replacement PR.

PR review and repair automation

branch-intake.yml opens exactly one draft PR when a new same-repository topic branch is first pushed. It ignores the integration branch, release branch, and automation-owned fork repair branches. Later pushes reuse the existing PR. Once the configured scans for the exact draft head are complete and green, PR automation marks it ready and immediately continues through review, repair, gating, and the merge train. Pending, failing, stale, conflicting, closed, and fork draft heads are no-ops; they are never promoted prematurely.

pr-automation.yml reacts to configured scan-workflow completions, re-reads the entire current-head check rollup, and publishes an explicit check run on that exact SHA. It waits for pending scans, separates cancelled infrastructure from actionable failures, and allows at most three repair commits per contributor lineage. A new contributor commit starts a new lineage; bot repair pushes do not reset the counter.

Conflicting same-repository PRs enter a bounded conflict-resolution job instead of failing permanently. The job materializes Git's exact unresolved path set without executing repository code, gives the constrained agent read/search/edit access only, rejects edits outside that set, rechecks the head SHA, and publishes one ordinary non-force resolution commit. Fork conflicts continue through the repository-owned replacement-PR path. Conflict attempts share the three-attempt repair budget, so an ambiguous merge cannot loop forever.

Review and repair use the immutable-pinned Claude Code Action with selected vibey-skills. The privileged jobs may inspect source and CI logs but may not execute contributor package managers, tests, builds, scripts, or binaries. Ordinary PR CI validates every repair push. The agent has no Git mutation tool: one trusted publisher may push a non-empty source (HEAD:refs/heads/<exact-pr-branch>) only to the exact PR branch. This deliberately permits forward updates to develop or main when either is the PR head, while making a Git deletion refspec (:branch) structurally impossible. Managed merges automatically update develop and main, but no managed command uses --delete, --delete-branch, an empty-source refspec, or a branch-deletion API. Repositories must configure ANTHROPIC_API_KEY; AUTOMERGE_TOKEN is required where the default Actions token cannot push or merge through the repository ruleset. Installation does not create either secret.

vibey-gh pr-automation evaluate --pr 123 --head-sha HEAD_SHA
vibey-gh pr-automation ready-draft --pr 123 --head-sha HEAD_SHA
vibey-gh pr-automation mirror-fork --pr 123
vibey-gh merge-train --pr 123

The promotion

vibey-gh promote --dry-run
vibey-gh promote

Moves the integration branch to the release branch, which is what publishes. Three things it gets right that a hand-written workflow usually does not:

• It compares by content, not by commit count. The release branch is rebase-merged, so its commits are rewritten copies with different SHAs; the integration branch always looks "ahead" even when the trees are identical. A diff is the only honest test.
• It derives the version before opening anything. An upload with skip-existing turns an unbumped promotion into a green run that publishes nothing, silently.
• It hands the PR to the same event gate as every other change. promote no longer holds a runner open with gh pr checks --watch; scans, automated review, and the exact-head merge train finish the promotion asynchronously. --wait retains the legacy synchronous mode for recovery.

Realignment

vibey-gh realign

When the release branch is rebase-merged its commits are rewritten copies with new SHAs, so the integration branch's tip is never an ancestor of it and a fast-forward is impossible — yet a ruleset with a strict up-to-date policy treats it as behind, which blocks the next promotion.

The guard is tree equality, not ancestry: this runs only when a diff between the two branches is empty, so it converges two identical contents onto one history and cannot discard work. If the integration branch has anything the release branch does not, it is left alone and says so.

Configuration

[pr_automation]
enabled = true
scan_workflows = ["CI", "Provenance", "CodeQL", "Docs", "API drift (Cloud Agents OpenAPI)"]
ignored_checks = ["PR automation / gate", "gate", "Merge train / merge"]
max_repair_attempts = 3
model = "claude-sonnet-5"
review_untrusted_authors = true
repair_untrusted_authors = true
replace_fork_prs = true
retain_schedule_backstop = true

[pr_automation.observability]
sanitized_progress = true
archive_execution_file = true
allow_private_full_output = false

[github_release]
enabled = true
tag_prefix = "v"
generate_notes = true

[repository_profile]
enabled = true
description = "A configurable repository description"
topics = ["automation", "documentation", "github-actions"]
has_issues = true
has_projects = true
has_wiki = false
has_discussions = true
allow_squash_merge = true
allow_merge_commit = false
allow_rebase_merge = true
allow_auto_merge = true
delete_branch_on_merge = false
web_commit_signoff_required = true
vulnerability_alerts = true
automated_security_fixes = true

[documentation]
enabled = true
ai_maintenance = true
model = "claude-sonnet-5"
production_label = "Production"
preview_label = "Preview"
production_indexing = true
preview_indexing = false
generate_robots = true
generate_sitemap_index = true
generate_llms_txt = true
generate_llms_full_txt = true
generate_json_ld = true

CodeQL is a real managed Python security-analysis workflow using an immutably pinned official action. API drift (Cloud Agents OpenAPI) executes the capability registry and requires identical coverage through MCP, API, CLI, SDK, and webhook adapters. The scan names above therefore map to concrete required checks rather than advisory placeholders.

Sanitized progress is the safe default. Claude's progress-comment mode is enabled only for the direct PR/issue events the action supports; workflow_run, workflow_dispatch, and pull_request_target retain safe phase-level job visibility without requesting that unsupported mode. Raw Claude JSON is never emitted during ordinary PR or scan-triggered runs. A repository may opt into private diagnostics with allow_private_full_output = true, then manually dispatch PR automation with full_claude_output = true. The workflow fails closed unless the event is manual and the repository visibility is private. Execution records remain 90-day artifacts when archive_execution_file is enabled.

Comprehensive documentation and AI maintenance

The Docs workflow enforces the deterministic FOSS and multi-agent documentation contract on every push and pull request. That structural check is intentionally necessary but not sufficient: after scans settle, PR automation performs an exact-head semantic audit for every author. It compares the README and complete documentation suite with source, tests, configuration, packaging, workflows, releases, and the CLI/SDK/API/MCP/webhook capability registry. A PR cannot pass merely by containing expected filenames or headings. It must be accurate, complete, human-readable, operationally useful, and free of actionable findings.

Findings enter the same bounded repair loop as a failing scan. The repaired SHA is rescanned and rereviewed; an older documentation verdict never satisfies the gate. A scheduled or manually dispatched maintenance job remains a repository-wide backstop: it creates missing documentation, repairs stale claims, and opens a guarded documentation PR. It never executes repository code in the privileged job, commits application changes, or mutates a permanent branch directly. It must return complete=true with no remaining gaps before a documentation PR may be published; PR-creation errors fail loudly.

The required suite includes README, changelog, license, conduct, contribution, security, support, architecture, operations, testing, release, governance, accessibility, dependency, threat-model, troubleshooting, ADR, GitHub, hooks, Claude, Cursor, Gemini, Codex/Agents, and generic-agent documentation. The repository also contains a Claude-standard plugin marketplace at .claude-plugin/marketplace.json with development, documentation, release-security, and PR-automation plugins. Each plugin ships manifests, skills, commands, specialist agents, and supporting references; .claude/settings.json registers and enables the marketplace for project sessions.

The Pages build emits production and preview sitemaps, a root sitemap index, robots.txt, llms.txt, llms-full.txt, canonical links, indexing policy, Open Graph/Twitter metadata, Schema.org JSON-LD, and repository/revision provenance. Repository identity and URLs are derived at build time, so adopting repositories never inherit vibey-gh metadata.

Five-surface capability parity

Every canonical capability is exposed and tested through all five supported surfaces:

• Python SDK: vibey_gh.surfaces.invoke(...)
• CLI: the native command and the sdk, api, mcp, and webhook projections
• JSON API: api_dispatch and /v1/capabilities/<name>
• MCP: initialize, tools/list, and tools/call
• Webhook: HMAC-SHA256 authenticated, delivery-ID replay-safe dispatch

The two Conventional Commit commands are deliberately outside this canonical registry: they are local git-hook/CI helpers that consume stdin, commit-message files, or revision ranges. Exposing those host-specific mutation primitives through a remote API, MCP tool, or webhook would expand privilege without adding an automation capability. Every repository automation capability in surfaces.CAPABILITIES remains available through all five forms.

The parity contract enumerates every capability from one registry, invokes every adapter, and fails CI if any surface is absent or divergent. Because Docs is a configured scan, missing documentation or interface parity blocks the exact-head PR gate and enters the bounded repair loop before merge.

After the configured Release workflow succeeds on main, the managed github-release.yml workflow tags that exact commit and creates a generated-notes GitHub Release. It is safe to rerun: an existing matching tag/release is reused, while an existing tag at a different SHA is never moved and fails loudly.

The managed release-surfaces.yml workflow follows every successful release on either branch. It builds two persistent ProperDocs sites under the repository's GitHub Pages domain: /develop/ is the test documentation released with TestPyPI, while /main/ is the production documentation released with PyPI. A small root page links both channels. Because GitHub Pages has one deployment per repository, each run restores the latest successful artifact for the other channel before deploying; one branch never erases the other branch's site.

GitHub Packages does not provide a PyPI registry. The workflow therefore publishes the exact wheel and source distribution from the successful Release run as an OCI artifact at ghcr.io/<owner>/<repository>/python. Every artifact receives its immutable version and sha-<commit> tags, plus develop for test releases or main and latest for production releases. The normal TestPyPI and PyPI uploads remain authoritative and are unchanged.

After release surfaces succeed, repository-profile.yml reconciles the repository's description, topics, homepage, collaboration features, merge methods, automatic merge, commit signoff, branch retention, vulnerability alerts, and automated security fixes. An empty description derives a repository-specific description from the consuming repository name. It verifies that Pages, a GitHub Release, a deployment, and the OCI package really exist—the public API does not expose fictional “show Releases/Deployments/Packages” switches. Profile updates use AUTOMERGE_TOKEN when available and never create, update, push, or delete a branch.

If a trusted post-merge workflow fails on develop or main, release-repair.yml reviews its logs with the same constrained agent used for PR repair. A fixable problem is committed to a new vibey-gh/repair/release-* branch and returned through a normal PR, where all checks and the merge train apply. It never pushes a repair directly to—and can never delete—develop or main. Credential, billing, repository-setting, registry, and other operator-only failures are reported with an explicit required action instead of being disguised as code fixes.

Everything project-specific lives in .vibey-gh.toml, so the logic beside it stays general. Every key has a default; a repository that agrees with them needs no file at all.

[fingerprint]
text    = "Made with love by ..."          # the source-header comment
trailer = "Made-With: ..."                 # the commit trailer
sources = ["src/**/*.py", ".github/workflows/*.yml"]

[version]
files         = ["pyproject.toml", "src/pkg/__init__.py"]
content_paths = ["plugins/"]               # a change here is a MINOR release
code_paths    = ["src/"]                   # a change here alone is a PATCH

[branches]
integration = "develop"
release     = "main"

[merge_train]
owner           = "your-login"
trusted_authors = ["your-login", "dependabot[bot]"]

Workflows

* CI and Release are not rendered by vibey-gh install; see What gets installed for the exact name and behavior contract every other row in this table depends on.

Scheduled and manual triggers are recovery backstops; normal delivery is event driven.

Failure and recovery model

The automation distinguishes failures by what can safely resolve them:

Repair jobs can read and edit files but cannot run contributor-controlled package managers, tests, builds, scripts, or binaries while privileged credentials are present. The ordinary unprivileged PR scans execute the repaired code. This separation is why a repair result is always followed by a new scan rather than being treated as proof of correctness.

Day-two operations

If Conventional Commits rewrites your topic branch, preserve unpushed work, run git fetch origin, and rebase it onto the new explicit origin/<topic-branch> head. With no unpushed work, reset only that local topic branch to its remote counterpart. Never reset or force-push develop or main.

Upgrade vibey-gh

Upgrade the package on a topic branch, rerun vibey-gh install, and commit the rendered workflow and asset differences. Never hand-copy only one generated workflow: templates, configuration rendering, tests, and the dogfood copies form one versioned contract.

python -m pip install --upgrade vibey-gh
vibey-gh install
vibey-gh check --ci
git diff -- .github .githooks

Disable a managed surface intentionally

Use configuration rather than deleting a generated file. For example, a repository that publishes no Python package can omit the release workflows from [install].workflows. vibey-gh check then verifies the chosen subset instead of repeatedly reinstalling a file the repository does not want.

Recover a missed event

Use the workflow’s manual dispatch with the PR number and exact current head SHA. Scheduled backstops also redispatch open PR evaluations. Re-running an old workflow is harmless: the exact-head comparison prevents its result from authorizing a newer commit.

Audit an automation decision

Start with the PR’s PR automation / gate, then follow the linked workflow run. The job summary contains the evaluated SHA, aggregate scans, trust classification, repair attempt, semantic review result, and merge decision. Review artifacts are retained for 90 days. State comments use machine-readable markers and are updated idempotently rather than creating an unbounded comment stream.

Project documentation map

Troubleshooting

• Empty Anthropic key: define ANTHROPIC_API_KEY as a repository secret, not only an environment secret, and confirm the privileged workflow can read it.
• Review-blocked promotion: verify the exact-head PR automation / gate; admin fallback is permitted only after all independent policy checks pass.
• Pages 404: select GitHub Actions as the Pages source and rerun Release surfaces.
• Repository profile failure: give AUTOMERGE_TOKEN the administration and security permissions required to reconcile the configured settings.
• Wrong package index: develop must select TestPyPI and main must select PyPI.

See docs/troubleshooting.md and SUPPORT.md; include the workflow URL, exact SHA, and redacted failing-step output when asking for help.

Contributing

Read CONTRIBUTING.md, CODE_OF_CONDUCT.md, and AGENTS.md. Changes must preserve the dependency-free runtime, Python 3.11, 100% line and branch coverage, immutable action pins, provenance, and permanent-branch non-deletion guarantee. Report vulnerabilities through SECURITY.md, not a public issue.

Taking the hooks without the workflows

install writes the managed workflows alongside the hooks. A repository that already has richer ones of its own can decline them:

[install]
workflows = []          # hooks and the CLI only
# workflows = ["provenance.yml"]   # or just the ones you want

This is not cosmetic. check verifies that everything it manages is present and current, so without it a repository that deliberately keeps its own workflows would fail the check forever — and a check that cannot pass is a check people route around.

trusted_authors is matched after normalising app/name and name[bot] to the same thing. gh reports a bot author with the app/ prefix while the rest of GitHub writes [bot]; a literal allow-list matches whichever spelling it happens to contain and silently distrusts the other, which once caused an automation to quarantine its own pull request as an outside contribution.

What is deliberately not fingerprinted

• Files whose bytes are meaningful — generated documents verified against a source, Markdown loaded into a model's context. A header would be a diff against the source.
• Anything without comment syntax — JSON, most notably.

The commit trailer covers both without touching them. A naive "comment in every changed file" rule cannot express itself in JSON and corrupts content that is checked byte for byte.

Licence

MIT. See LICENSE.

Made with ❤️ by Vibey, Developed by Adam Matthew Steinberger (@adammatthewsteinberger).