0 Fork 0

mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2026-11-06 02:54:26 +00:00

Files

T

kevinveenbirkenbachandClaude Opus 5 d8c6bd242d test(ci): require every secret and variable a workflow reads to be documented

An unset secret or variable resolves to the empty string, not to an error, so
an undocumented one is invisible twice: the administrator cannot know to set it,
and the run that needed it degrades quietly instead of failing. The guard reads
every ${{ secrets.X }} and ${{ vars.X }} out of .github/workflows and demands
the name in the page that owns it, secrets.md or configuration.md.

It compares the reference against the page rather than the page against itself,
so it also catches a doc naming something the workflows no longer read.

Three gaps were already there. DOCKERHUB_USERNAME and DOCKERHUB_TOKEN
authenticate the image mirror against Docker Hub and lift the anonymous
pull-rate limit; both are declared required: false and the login step is gated
on them being non-empty, so their absence does not fail a run, it walks the
mirror into the rate limit. Neither was documented anywhere.

PLAYWRIGHT_KEEP_ALL is the sharper one: configuration.md listed
INFINITO_PLAYWRIGHT_KEEP, which is the name the workflow forwards it under, not
the name an administrator sets. Following the documentation produced a variable
nothing reads.

Commented-out lines are skipped. cron-security-scorecard.yml carries
`# repo_token: ${{ secrets.SCORECARD_TOKEN }}` as an option nobody has taken,
and demanding a doc row for it would describe an input no run asks for.

GITHUB_TOKEN is exempt in _PROVIDED_SECRETS because GitHub mints it per run; it
is not administered and cannot be set. A second case asserts the scan finds
workflow files at all, so the guard cannot pass vacuously.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-09-14 19:59:10 +02:00

8.3 KiB

Raw Permalink Blame History

CI Secrets 🔐

This page lists every repository secret that GitHub Actions workflows in this repository consume, and documents the failure mode when a secret is missing. For repository variables see configuration.md. For the workflow catalog see workflows.md.

Repository secrets MUST be set under Settings → Secrets and variables → Actions → Secrets.

Secrets 📋

Secret	Workflow	Purpose	Required when
`BOT_APP_CLIENT_ID`	cron-update.yml	GitHub App Client ID (OAuth-style `Iv…` identifier shown on the App's General page) used to mint a short-lived installation token for the update PR.	`CI_ENABLE_AUTO_UPDATES == 'true'`
`BOT_APP_PRIVATE_KEY`	cron-update.yml	PEM-encoded private key of the same GitHub App. Used to sign the JWT that exchanges for the installation token.	`CI_ENABLE_AUTO_UPDATES == 'true'`
`API_OPENAI_KEY`	call-test-deploy.yml	Publishes the `openai/*` models on the LiteLLM gateway and lets the CLI test exercise the route.	Never. Unset leaves the route unpublished.
`API_ANTHROPIC_KEY`	call-test-deploy.yml	Publishes the `anthropic/*` models.	Never.
`API_OPENROUTER_KEY`	call-test-deploy.yml	Publishes `openrouter/auto`.	Never.
`DOCKERHUB_USERNAME`	cron-images-mirror-all.yml, call-images-mirror-missing.yml	Authenticates the mirror job against Docker Hub, which raises the anonymous pull-rate limit the mirror would otherwise hit.	Never. Both workflows declare the secret `required: false` and gate the login step on both values being non-empty.
`DOCKERHUB_TOKEN`	cron-images-mirror-all.yml, call-images-mirror-missing.yml	The access token paired with `DOCKERHUB_USERNAME`.	Never, and only together with the username.

`API_OPENAI_KEY`, `API_ANTHROPIC_KEY`, `API_OPENROUTER_KEY` 🤖

These are optional and fail soft: unset means the provider's route is never published, and the deployment falls back to whatever local backend the round deploys. The workflow reads each as ${{ secrets.X || vars.X }}, so the same name works as a repository variable; see configuration.md for why the secret is the better half of that pair.

Set them the same way as the App credentials: Settings → Secrets and variables → Actions → Secrets → New repository secret, one per provider, the value being the provider's key verbatim.

The shape each key must have is declared per role rather than here, in roles/svc-ai-litellm/meta/secrets.yml with a type: and a regex:. The pattern rejects a truncated or whitespace-carrying paste and deliberately accepts any vendor prefix, so a provider changing its issuance format cannot turn a valid key into a failed inventory run.

`BOT_APP_CLIENT_ID` and `BOT_APP_PRIVATE_KEY` 🤖

Why these secrets exist 🎯

Actions performed with the workflow-provided GITHUB_TOKEN do not start further workflow runs. When cron-update.yml opens an update PR with GITHUB_TOKEN, the pull_request and pull_request_target events that drive entry-pr-change-orchestrate.yml do not fire on that PR, so the CI orchestrator never runs against it.

Opening the PR through a GitHub App installation token bypasses this restriction. The App counts as a distinct actor, so PR-lifecycle events fire normally and the full CI pipeline runs against every update PR.

Why a GitHub App and not a PAT 🏷️

A GitHub App installation token SHOULD be used because:

The token lifetime is bounded to one hour, and a new token is minted on every workflow run.
Permissions are scoped at the App installation level, independent of any user account.
No personal account footprint appears in audit logs.

A classic personal access token MAY be used as a fallback for unrelated automation, but it MUST NOT be used here because user-bound credentials expand the blast radius and require manual rotation.

How to generate the App 🛠️

Create a new GitHub App under Organization settings → Developer settings → GitHub Apps → New GitHub App.
Disable the webhook (uncheck Active under Webhook). The App MUST NOT receive events.
Grant the following repository permissions and nothing else:
- Contents: Read and write (the update script force-pushes to update/* branches).
- Pull requests: Read and write (gh pr create / gh pr edit).
- Metadata: Read (default, cannot be removed).
Restrict installation to the owning account only.
Generate a private key and download the PEM file.
Install the App on the core repository only. The App MUST NOT be installed on unrelated repositories.

How to hand the credentials to CI 📥

Open the repository on GitHub.
Go to Settings → Secrets and variables → Actions.
Stay on the Secrets tab.
Click New repository secret and add BOT_APP_CLIENT_ID with the App's Client ID (shown on the App's General page under About, in the Iv… format — not the numeric App ID).
Click New repository secret and add BOT_APP_PRIVATE_KEY with the complete PEM content, including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- lines.

How the workflow consumes the secrets ⚙️

Each PR-opening job in cron-update.yml runs an actions/create-github-app-token@v2 step gated on steps.diff.outputs.changed == 'true', then forwards the minted token as GH_TOKEN and the resolved APP_SLUG to the subsequent PR step. The job's permissions: block keeps the workflow-provided GITHUB_TOKEN read-only; write access is provided exclusively by the App token, scoped to the App's repository permissions.

Commit identity propagation 🪪

pr.sh reads APP_SLUG from the environment and resolves the App's bot user via gh api /users/<slug>[bot]. The resolved login and numeric user ID are written into git config user.name and git config user.email in the <id>+<slug>[bot]@users.noreply.github.com form that GitHub accepts for verified commits. When APP_SLUG is unset, the script falls back to the github-actions[bot] identity. That branch is reached only when the script is invoked outside the workflow, for example a local smoke test where the caller has set GH_TOKEN to something other than an App token.

Failure mode when secrets are missing 💥

A missing secret resolves to an empty string in workflow expressions. The workflow run starts and proceeds normally until the token-minting step:

Stage	Behaviour when both secrets are missing
Workflow parse	Run starts. GitHub emits the warning `The following secrets are referenced but not defined: BOT_APP_CLIENT_ID, BOT_APP_PRIVATE_KEY`.
`Generate app token` step	`actions/create-github-app-token` declares both inputs as required and fails with `Error: Input required and not supplied: client-id`.
`Open PR if … changed` step	Skipped. Its implicit `if:` condition is `success() && (steps.diff.outputs.changed == 'true')`, and `success()` is false after the token step failed.
`pr.sh`	Not executed. No commit, no push, no PR.
Outcome	The run is marked failed. GitHub notifies repository admins. No PR is created with a wrong identity.

The behaviour is fail-loud by design. Missing or mistyped secret names MUST surface as a failed workflow run rather than as a PR with an unintended author.

configuration.md: repository variables that gate the same workflows.
workflows.md: full workflow catalog.
pipeline.md: how the orchestrator routes PR runs.

8.3 KiB Raw Permalink Blame History