Verify GitHub governance

GitHub repository and organization settings form part of Vexcalibur’s release security boundary. They are not stored in Git, so a normal code review cannot show when one changes. The read-only governance checker compares those live settings with the policy documented here.

Run the live check

Authenticate the GitHub CLI as an organization owner or a repository administrator who can read rulesets, security settings, environments, and organization Actions policy. Then run:

gh auth status
make governance-check

The checker issues fixed GET requests through gh api. It never writes a setting, creates a token, or prints the output of a failed authentication request. It uses the credentials already available to gh; do not put a token in this repository or in a command-line argument.

The exit status distinguishes the result:

Status	Meaning
0	Every required endpoint was readable and the live controls matched.
1	Every required endpoint was readable and policy drift was found.
2	At least one required endpoint or snapshot was inaccessible or malformed. No policy result was produced.

An authorization failure is not a passing or partial check. Reauthenticate with the required read access and run the complete check again.

Committed policy

The checker requires these default-branch controls:

Repository	Strict GitHub Actions checks
vexcalibur	CI result, Analyze Python, dependency-review, pre-commit
vexcalibur-action	CI result, Analyze (actions), Analyze (python)
vexcalibur-orb	Quality, Analyze (actions), Analyze (python)
.github	Validate workflow templates, Smoke Python security commands, Analyze (actions)

Every repository’s default branch must remain main. Every check is bound to the GitHub Actions App integration, not merely to a matching status name. Each active ruleset applies to the default branch, requires a pull request, resolves review threads, prevents deletion and non-fast-forward updates, and uses strict required checks. The rulesets have no branch bypass actors. They allow zero required approvals so a solo maintainer can merge a passing pull request without fabricating an independent reviewer. Changing that tradeoff requires an explicit policy review.

Core, Action, and Orb each have two active refs/tags/v* rulesets:

• a creation rule permits only the Vexcalibur release integration for core and Action. Orb uses the organization administrator as its explicit publishing path until its CircleCI publishing identity is configured.

• a separate update-and-deletion rule has no bypass, so an existing release tag is immutable even for the actor allowed to create it.

Organization policy enforces immutable GitHub Releases for every repository and requires full commit-SHA pinning for GitHub Actions. Core’s pypi environment accepts deployments only from tags matching v* through a custom deployment policy during normal operation. GitHub currently allows an administrator to bypass that environment policy; the checker records that exception so it cannot change silently.

The Orb repository also requires Dependabot vulnerability alerts and automated security updates, secret scanning, push protection, automated security fixes, and private vulnerability reporting. CodeQL default setup must run weekly with the extended query suite and the remote_and_local threat model for Action, Orb, and .github. Action and Orb scan Actions and Python; .github scans Actions. Core uses its checked-in advanced CodeQL workflow instead of default setup.

Each of the four repositories commits a CODEOWNERS file. Core’s file records @dannysauer as the primary owner and repeats ownership for workflows, release controls, dependency policy, and this drift check; the other files name their equivalent release and consumer boundaries. The zero-approval solo-maintainer ruleset means these are explicit ownership and review-routing controls, not a claim of independent approval.

Controls that still need external administration

The checker records the current safe baseline; it does not claim every desired control is complete. Core and Action still use one long-lived automation App key. GitHub rejects the built-in Actions integration as a tag-ruleset bypass actor, so removing that key without a separately scoped App or credential broker would weaken restricted v* tag creation. The checker confirms that the App is unsuspended and has only contents-write plus metadata-read permission. It also records the current, undesirably broad all-repositories installation selection; narrowing that scope requires an intentional checker and documentation update. The private-key lifecycle is not API-readable and remains tracked with the App scope as a release-governance finding.

Future releases are immutable, but release notes and assets created before that organization policy remain legacy-mutable; their tag refs are protected. The pypi environment has no independent reviewer because the organization currently has one maintainer, and its administrator-bypass setting remains enabled. Orb publication still depends on the external CircleCI account, namespace, context, and token setup described in its repository issue tracker.

When to run it

Run the live check after changing repository, organization, environment, security, or release settings. Also run it periodically and during release or security reviews. The normal test suite validates the checker against the committed offline fixture, but that fixture is not proof of the live state.

There is intentionally no scheduled workflow with a stored administrator credential. A repository GITHUB_TOKEN cannot read every organization and administrative endpoint covered here. Silently skipping those endpoints would produce a misleading result, while storing a broad token would add a new release-adjacent secret. Periodic execution therefore uses an authenticated maintainer’s local gh session and fails closed when access is insufficient.

Use the offline mode only to test or investigate a captured, reviewed fixture:

uv run --frozen python scripts/check_github_governance.py \
  --snapshot tests/fixtures/governance/expected.json

Respond to drift

Do not edit the fixture merely to make a failure disappear.

1. Read every reported difference and confirm the live setting independently.

2. Restore an accidentally weakened setting before the next release.

3. For an intentional policy change, review the threat-model impact and update the checker, fixture, and this page together in a pull request.

4. Run the live checker again with sufficient access and retain the successful command result in the associated issue or pull request.

The checker is deliberately diagnostic. It has no repair mode and cannot mutate GitHub configuration.