Repository activation

Talos is an existing repository adopting governance tooling. Preserve its package, history, version source, examples and documentation. This runbook configures the external services; it does not recreate or reseed the repository.

Current boundary

Governance is active on master as of 1 October 2026. Ruleset 24306812 matches the checked-in snapshot, requires all ten declared gates and an eligible non-author approval, and has no bypass actors. PR 608 merged as 9783406eafd0c9d72d00010aeffb379a534a5349 after approval from bit-mis. The integrated CodeQL analysis and privileged ruleset audit passed. The audit used RULESET_AUDIT_TOKEN and inspected bypass actors.

These are dated observations, not a permanent assertion about remote settings. The steps below remain the activation and recovery runbook. Preserve classic protection and compare the complete live snapshot when changing settings. The maintainer authorizes automatic release after successful protected-master CI. PyPI publishing requires the trusted publisher and branch-restricted pypi environment described below.

Prerequisites

• Administration access to autonomio/talos and access to Actions settings.
• GitHub Actions and CodeQL availability for this public repository.
• An eligible non-author code owner with write access for governed surfaces. .github/CODEOWNERS designates mikkokotila, zero-bang and bit-mis; governance.yml retains mikkokotila as the approving authority. The ownership declaration was integrated through PR 608; adding a collaborator alone does not satisfy code-owner approval.
• Copilot code review availability for the intended ruleset.
• A protected repository-administration environment for activation and a protected pypi environment for release/publication.
• A read-only ruleset audit token and, only for the activation operation, a separately scoped administrator credential.

Credentials and variables

Name	Use	Required permissions
REPO_BOOTSTRAP_TOKEN	Explicit existing-repository activation	Administration, Variables and Issues read/write; Metadata read
RULESET_AUDIT_TOKEN	Post-merge live ruleset audit, including bypass actors	Administration and Metadata read
RULESET_ID	Identify the installed ruleset	Set after the ruleset is created

Use repository secrets or organization secrets restricted to Talos. Never print token values or store them in source. GITHUB_TOKEN cannot administer rulesets and events it creates generally do not start another workflow run; it cannot replace an activation credential.

.github/labels.json supplies the standard labels locally. Activation creates or updates the declared labels and preserves unrelated pre-existing labels; it does not depend on another organization's repository.

Activate existing-repository governance

1. Review the adopted policy, all local evidence and the proposed snapshot in .github/rulesets/master.json. Reconcile the standard labels without deleting existing labels.
2. Verify the selected code owners still have write access and obtain an eligible non-author review of the integration change. Protect the repository-administration environment and use read-only default workflow permissions.
3. Provision RULESET_AUDIT_TOKEN for Talos only. Verify its actual response includes bypass_actors; the permission label alone cannot prove complete observability. Keep the existing broad CLI OAuth credential out of Actions.
4. Open and validate the adoption PR through the existing protection, then integrate the reviewed workflows. The initial ruleset check cannot pass while its live prerequisite is absent; record that bootstrap boundary explicitly. Do not install mandatory check contexts before their workflows are available and validated.
5. Wait for the integrated master CodeQL analysis. Analysis/upload success is separate from the native code_scanning rule, which blocks new security findings at every severity. Copilot's rule requests reviews automatically; it does not itself require completion or an approving verdict.
6. Apply the reviewed labels and ruleset with scripts/configure_repository.py --apply using the authorized local administrator credential, or dispatch the protected bootstrap_repository.yml workflow from master after separately provisioning its activation credential. Neither path renames Talos, rewrites authored docs or resets history. The script records the installed identifier in RULESET_ID.
7. Verify exact live snapshot parity, including bypass actors, all required checks, CodeQL security thresholds, non-author/code-owner approval, resolved threads, up-to-date branches and force-push/deletion blocks. Preserve existing classic protection.
8. Dispatch the integrated privileged audit and confirm the scoped credential can read the complete live ruleset. Validate enforcement on a subsequent PR; do not declare activation complete from source tests or an API write alone.

For read-only verification, use gh variable list --repo autonomio/talos, gh api repos/autonomio/talos/rulesets and gh label list --repo autonomio/talos. The configured ruleset name and gate list come from governance.yml; compare the responses rather than merely checking that an API call succeeded.

Configure automatic releases

Making a release defines the merge-to-release sequence. A successful full protected-master CI run starts deploy.yml, which selects the tested source, creates the matching version tag, signs and attaches artifacts, and publishes Talos to PyPI.

Configure the PyPI project's trusted publisher with owner autonomio, repository talos, workflow deploy.yml and environment pypi. Set that GitHub environment's deployment branch policy to protected branches, with no required reviewers. The protected-master merge review authorizes the release; do not add another manual approval gate. Verify package identity, version and burned-version guard. Legacy PyPI username/password or API tokens are not used by this OIDC path, and no PYPI_PUBLISH_ENABLED variable is required.

On 5 October 2026, the matching PyPI publisher was configured and the GitHub pypi environment was restricted to protected branches without required reviewers. These are dated activation observations; verify the live settings when recovering publication.

Failure modes

Symptom	Cause	Resolution
No required checks on a PR	Workflows have not reached the target branch or the live ruleset is absent	Integrate through review, then install and verify the intended policy
Ruleset gate cannot read a target	RULESET_ID missing, wrong or unreadable	Set the actual identifier and verify repository/credential access
Audit cannot inspect bypass actors	Audit token lacks Administration read	Repair the read-only token scope; do not suppress the check
Review does not satisfy protection	Reviewer lacks write access, authored the PR or code-owner approval is missing	Obtain an eligible non-author review
Copilot review unavailable	Account or repository capability not configured	Configure it before declaring the intended protection active
Publication is skipped	Failed or superseded master CI	Inspect the current master run; a failed or obsolete head must not publish
PyPI guard rejects a version	That version has already been served	Advance the version; never reuse a burned identity

Read next

• Configuration
• Security assurance case
• Making a release

Publish the verified documentation

Set Settings → Pages → Build and deployment → Source to GitHub Actions. The docs_pages.yml workflow consumes only the successful protected-master Test and build artifact and publishes the documentation and measured statement coverage badge. It carries Pages and identity-token write access only in the deployment job; the source testing workflow stays read-only. The initial coverage asset reports awaiting publication until a complete measured report passes the statement gate.

First deployment requires the Pages workflow and static-site artifact changes to be merged. Check the public documentation URL and coverage report after that deployment; local build evidence does not prove the public site is available.