@ebalzan/ci 0.0.0-stage → 3.0.0

package/docs/GITHUB_ACTIONS_SETUP.md

@@ -0,0 +1,315 @@
+# GitHub Actions — secrets & variables
+
+Where every Actions secret and variable lives, **why it lives there**, how
+shared values reach every repo, and how one command syncs it all. Read
+[§1](#1-the-rule) before adding any new value, and [§2](#2-shared-vs-repo-the-layers)
+before deciding whether it goes in the shared layer or in a repo.
+
+The tools: `ebalzan-ci bootstrap` sets values, `ebalzan-ci reset` deletes them
+([CLI.md](CLI.md)). Every key, with its default: [CONFIGURATION.md](CONFIGURATION.md).
+
+---
+
+## 1. The rule
+
+> **Environments** hold config that describes **a specific running system you
+> deploy to**.
+> **Repository** ("Settings → Secrets and variables → Actions") holds config
+> that describes **the repository's own automation**.
+
+That is the whole decision. It is _not_ "production goes in Environments" and
+_not_ "the sensitive ones go in Environments". The only question is:
+
+**Does this value point at, or grant access to, one particular deployed
+system?**
+
+- **Yes** → environment secret/variable, in the environment named after that
+  system (`production`, `staging`). Examples: a host address, an SSH key, a
+  database URL, a registry pull token used _by that host_, live-vs-test API keys
+  of a third party.
+- **No — it configures the repo's own bots and CI** → repository
+  secret/variable. Examples: an LLM key used to write PR descriptions, a PAT for
+  the project board, lint/label tuning.
+
+```mermaid
+flowchart TD
+  A["New value to configure"] --> B{"Would you mind seeing it<br/>printed in a workflow log?"}
+  B -- No --> V["VARIABLE"]
+  B -- Yes --> S["SECRET"]
+  V --> C{"Does the value depend on WHICH<br/>deployed system the job touches?"}
+  S --> C
+  C -- "Yes (host, DB, live keys)" --> E["Environment scope<br/>production / staging"]
+  C -- "No (same for all runs)" --> R["Repository scope"]
+```
+
+### Why the rule is the rule
+
+Environments are not a folder. They change _who can read the value_:
+
+1. **Reachability gating.** An environment secret is invisible to any job that
+   does not declare `environment: <name>`. `AWS_DEPLOY_ROLE_ARN` cannot be read by
+   `pr-checks.yml` — not by convention, by mechanism. A repository secret is
+   readable by **every job in every workflow** in the repo.
+2. **Deployment history.** The Environments page records which release went to
+   `production` and when.
+3. **Protection rules** (required reviewers, wait timer, branch policy) — free
+   on public repos, **paid on private ones**, see [§3](#3-plan-reality).
+
+Point 1 is the reason to use environments at all. Everything else follows from
+it: put a value in an environment when you want it _unreachable_ from jobs that
+have no business with that system.
+
+### Precedence — most specific wins
+
+Both secrets and variables exist at two scopes here, and they are **not
+merged**; the nearest one wins:
+
+```text
+environment  >  repository
+```
+
+(GitHub has a third, wider scope — organization — but personal accounts have
+none, and the tools never write to it. That is why the shared layer here is
+read at run time for variables and merged in at sync time for secrets: see
+§2. It works the same for repos owned by an organization.)
+
+So defining e.g. `DEPLOY_HOST` at the repo _and_ on the `production`
+environment means `environment: production` jobs get the environment value
+and everyone else gets the repo value. That is a legitimate **override**, but
+only do it on purpose — an accidental duplicate is the hardest Actions bug to see,
+because both values are masked in logs.
+
+### Secret or variable?
+
+Same two scopes, different visibility. **Variables are plain text** — printed
+in logs, readable by anyone who can view repo settings. Secrets are masked and
+write-only after creation. If you would not paste it into a public issue, it is
+a secret. Non-secret-but-environment-specific config (a region, a health-check
+URL, a log level) is a legitimate **environment variable** — the two axes are
+independent.
+
+---
+
+## 2. Shared vs repo: the layers
+
+> **A value goes in the shared layer only when it is the same for every repo.**
+> Anything that differs — a board number, a deploy host, a milestone — is that
+> repo's, and lives in that repo.
+
+```text
+                  shared (lower precedence)               <repo>/.github/ (wins)
+variables         config/actions.env                  +   actions.env              → shared read at run time; repo's → repository variables
+repo secrets      <shared secrets dir>/secrets.env    +   secrets.env ¹            → repository secrets
+env secrets       <shared secrets dir>/secrets.<env>.env + secrets.<env>.env ¹    → environment <env> secrets
+```
+
+`config/actions.env` ships inside this repo (and the npm package). The
+**shared secrets dir** is wherever you keep your shared secrets — they are never
+committed: `$CI_SECRETS_DIR` if set, else `config/` when you run the tools from
+a git checkout of ebalzan/ci, else `~/.config/ebalzan-ci/`.
+
+¹ A repo's own secrets files live in `repos/<owner>/<repo>/` inside the shared
+secrets dir when that folder exists — recommended: every repo's secrets in one
+place, outside any git working tree, synced without checkouts. Otherwise they
+are the gitignored files in the repo's `.github/`.
+
+The two columns combine key by key — **the repo's value wins**. For secrets,
+`bootstrap` merges them and writes the result onto the repository. For
+variables it pushes only the repo's column; the shared one is read at run time
+(below). So a repo can:
+
+- **inherit** a shared key by not mentioning it;
+- **override** it by setting the same key in its own file;
+- **add** any key of its own, in any scope (including a new environment: the
+  file `secrets.staging.env` creates and fills environment `staging`).
+
+The dry run labels every key `shared`, `repo`, `repo (overrides shared)` or
+`repo (same as shared: redundant)` — delete the redundant ones from the repo's
+file so the repo keeps only what is really its own.
+
+**Shared variables are read at run time.** In a reusable workflow `vars` are
+the caller repo's — but `config/actions.env` is committed, and the runner
+downloads the whole of ebalzan/ci for `uses: ebalzan/ci/actions/…@v2`. So the
+actions (`actions/auto-work-items/src/sharedVars.ts`, also used by
+`scripts/release/promote-dev-to-main.mjs`) load that file and fill every key
+the repo leaves unset. Consequences:
+
+- A shared variable changes when it is released and **the major tag moves** —
+  no bootstrap run, and nothing stale is left on any repo.
+- A repo's Settings page shows only its own variables; the run log line
+  `Shared variables from config/actions.env: …` lists what was filled.
+- The shared workflows pass the repo's variables whole
+  (`REPO_VARS_JSON: ${{ toJSON(vars) }}`), so any `AUTO_*` key a repo sets
+  reaches the actions with no workflow edit.
+- Only the shared actions see shared variables. A workflow that lives in a repo
+  and reads `vars.X` itself must have `X` in that repo's `actions.env`.
+- An empty repo variable counts as unset, so a repo cannot blank out a shared
+  value — override it with a real one.
+
+**Shared secrets are merged at sync time** — they are not committed, so there
+is nothing to read at run time. After changing one, re-run
+`ebalzan-ci bootstrap --all`.
+
+**Removing a key** from a file does not delete it on GitHub. `--prune` deletes
+every variable/secret in a synced scope that no layer defines (after listing
+them and asking). Environments that no file names are never touched.
+
+---
+
+## 3. Plan reality
+
+What the GitHub plan decides, for the repos this targets:
+
+| Feature                                                       | Public repo | Private, free plan | Private, Pro/Team |
+| ------------------------------------------------------------- | ----------- | ------------------ | ----------------- |
+| Environments and environment secrets                          | ✅          | ✅                 | ✅                |
+| Environment protection rules (required reviewers, wait timer) | ✅          | ❌                 | ¹                 |
+| Branch rulesets ([REPO_RULES.md](REPO_RULES.md))              | ✅          | ❌ (skipped)       | ✅                |
+| Organization-level secrets/variables                          | org only    | org only           | org only          |
+
+¹ At the time of writing GitHub's docs reserve required reviewers and wait
+timers on private repos for GitHub Enterprise; check the current plan matrix
+before relying on them. Environments themselves (and their secrets) were
+verified working on private free-plan repos.
+
+Without required reviewers, **merging the `dev → main` promotion PR is the
+deploy approval**: review it as the approval it is.
+
+---
+
+## 4. File mechanics
+
+| File                                              | Contains                             | Committed?   |
+| ------------------------------------------------- | ------------------------------------ | ------------ |
+| `config/actions.env`, `.github/actions.env`       | variables                            | ✅ Yes       |
+| `secrets.env` (shared dir), `.github/secrets.env` | repository secrets                   | ❌ **Never** |
+| `…/secrets.<env>.env`                             | secrets for GitHub environment `env` | ❌ **Never** |
+| `…/secrets*.env.example`                          | placeholders / templates             | ✅ Yes       |
+| `.github/bootstrap.conf`                          | per-repo tool settings (below)       | ✅ Yes       |
+
+Secrets files kept in a checkout must be gitignored — `onboard` adds
+`/.github/secrets*.env` (keeping the `.example` files) to `.gitignore`.
+
+> **The filename is the destination.** `actions.env` / `secrets.env` land on
+> the repository; a `.<name>` infix always targets the GitHub environment it is
+> named after.
+
+- **`_FILE` suffix.** A secret key ending in `_FILE` is a path: the secret is
+  created under the stripped name from that file's **contents** (dotenv cannot
+  hold a multiline value). `~` expands; a relative path is relative to the env
+  file. `FOO_FILE` in one layer and `FOO` in the other are the same key.
+- **Local-only keys.** `LOCAL_ONLY_KEYS=A B C` in a repo's
+  `.github/bootstrap.conf` are never pushed — for values only a local tool
+  reads (a provisioning script, say).
+- **Guards.** Empty values and placeholders (`xxxx`, `sk-ant-xxx`,
+  `github_pat_xxx`) are refused: a secret cannot be read back to notice a bad
+  write. A missing secrets file is seeded from its `.example` on first run.
+- **Remote mode** (`bootstrap -R owner/repo` with no local checkout) reads the
+  repo's committed files through the API and its secrets from
+  `repos/<owner>/<repo>/`. Without that folder it syncs only the shared secrets,
+  and never prunes secrets.
+
+Real secrets never enter git. These are **Actions** secrets, unrelated to any
+app's runtime `.env`.
+
+---
+
+## 5. Setup
+
+### Prerequisites
+
+1. **GitHub CLI** — <https://cli.github.com> (`gh --version`), authenticated
+   with the `project` scope if you use boards: `gh auth login && gh auth refresh -s project`.
+2. **Admin** on every target repo.
+3. Each repo's own secrets in `~/.config/ebalzan-ci/repos/<owner>/<repo>/` —
+   then `--all` needs no checkouts. (Alternatively in each checkout's
+   `.github/`, with the repos side by side under `CI_REPOS_ROOT`.)
+
+### Fill in the secrets
+
+```bash
+mkdir -p ~/.config/ebalzan-ci
+cp "$(npx --no-install ebalzan-ci path)/config/secrets.env.example" ~/.config/ebalzan-ci/secrets.env
+$EDITOR ~/.config/ebalzan-ci/secrets.env
+# plus each repo's own, e.g.:
+mkdir -p ~/.config/ebalzan-ci/repos/owner/my-api
+$EDITOR ~/.config/ebalzan-ci/repos/owner/my-api/secrets.production.env
+```
+
+> **Why a separate `GH_PROJECT_TOKEN`?** The built-in `GITHUB_TOKEN` cannot write
+> to Projects (v2) boards, which are owned by the account, not the repo — and a
+> PR it opens does not trigger other workflows, so PR Checks would not run on
+> the bots' PRs.
+>
+> **Why classic and not fine-grained?** Fine-grained PATs expose a `Projects`
+> permission only under **Organization** permissions. There is no account-level
+> equivalent, so a fine-grained token cannot reach a board owned by a personal
+> account. A classic PAT with the `project` scope is the only option there. It
+> also needs `repo`, because the automation creates issues and pull requests,
+> not just reads them.
+>
+> The trade-off: `repo` on a classic PAT covers **every** repository the account
+> can reach and cannot be narrowed to selected repos. Keep the expiry short, and
+> reissue rather than extend. One token serves every repo; the bootstrap writes
+> it as a repository secret in each of them, from one line in the shared
+> `secrets.env`.
+
+### Run the bootstrap
+
+```bash
+ebalzan-ci bootstrap --all --dry-run          # preview every repo — run this first
+ebalzan-ci bootstrap --all                    # sync every repo
+ebalzan-ci bootstrap -C ../my-repo            # one repo, from its checkout
+ebalzan-ci bootstrap -R owner/my-repo         # one repo, no checkout
+```
+
+It is idempotent — re-run it to update any value; nothing needs clicking
+together in the GitHub UI. Options: [CLI.md](CLI.md#bootstrap).
+
+---
+
+## 6. Verify
+
+```bash
+gh variable list --repo owner/my-repo
+gh secret   list --repo owner/my-repo
+gh secret   list --repo owner/my-repo --env production
+```
+
+Repository values are under **Settings → Secrets and variables → Actions**;
+environment values under **Settings → Environments → _name_**. Then the real
+check: push a branch (work items appear) and open a PR (title check green).
+
+---
+
+## 7. Resetting / deleting
+
+Prefer `bootstrap --prune` to remove keys no file defines any more.
+`ebalzan-ci reset` is the blunt tool: it lists what exists, then requires a
+typed confirmation. Always `--dry-run` first.
+
+```bash
+ebalzan-ci reset -R owner/my-repo --dry-run           # repo variables that would go
+ebalzan-ci reset -R owner/my-repo --include-secrets   # variables + repo secrets
+ebalzan-ci reset -R owner/my-repo --match '^AUTO_'    # only matching names
+ebalzan-ci reset -R owner/my-repo --env production --secrets-only --dry-run
+```
+
+---
+
+## 8. Troubleshooting
+
+| Symptom                                             | Cause / fix                                                                                                                                   |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| Secret is set but the job sees an **empty string**  | The job does not declare `environment:`. Environment secrets resolve **only** inside a job that names the environment — no error, just empty. |
+| Shared change has no effect in a repo               | Secret: not re-synced (`--all`). Variable: not released yet, or the repo overrides that key — the dry run says which.                         |
+| Key removed from a file still on GitHub             | Removal never deletes. Re-run with `--prune`.                                                                                                 |
+| Two scopes, wrong value wins                        | Precedence is environment > repository. Delete the duplicate you did not mean to create.                                                      |
+| `gh is not authenticated`                           | `gh auth login`, then `gh auth refresh -s project`.                                                                                           |
+| `… is still a placeholder` / `… has an empty value` | Fill the value in, or comment the line out.                                                                                                   |
+| Multiline secret arrives mangled                    | Use the `_FILE` suffix.                                                                                                                       |
+| `Could not verify …/projects/N`                     | `gh auth refresh -s project`, or fix `AUTO_PROJECT_NUMBER` in the repo's `actions.env`.                                                       |
+| Shared secrets not picked up                        | Check the `shared secrets:` path the bootstrap prints; set `CI_SECRETS_DIR` if it is not where your file is.                                  |
+
+Naming constraints: names are case-insensitive, cannot start with `GITHUB_` or a
+digit, and secrets are capped at 48 KB (100 per repo, 100 per environment).

package/docs/MIGRATION.md

@@ -0,0 +1,175 @@
+# Migrating from `tracebim-ci` v1 to `ebalzan/ci` v2
+
+v2 is the same pipeline under a new name, made generic and public:
+
+| v1 (`ebalzan/tracebim-ci`, private)                                | v2 (`ebalzan/ci`, public, `@ebalzan/ci` on npm)                                 |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| `uses: ebalzan/tracebim-ci/.github/workflows/X.yml@v1`             | `uses: ebalzan/ci/.github/workflows/X.yml@v2`                                   |
+| Only repos owned by `ebalzan` could call it                        | Any repo can call it                                                            |
+| Hook ran `../tracebim-ci/managed/…` (or a synced copy)             | Hook runs `ebalzan-ci commit-msg` from the npm devDependency                    |
+| `bash ../tracebim-ci/bin/gh-bootstrap.sh --repo-dir .`             | `npx ebalzan-ci bootstrap`                                                      |
+| `REPOS=` checkout names next to the CI checkout                    | Repos tagged `ebalzan-ci`, plus optional `OWNER/REPO` slugs                     |
+| Shared `AUTO_MILESTONE_TITLE=oct-26`, `AUTO_PROJECT_OWNER=ebalzan` | Removed: a milestone is per project; the board owner defaults to the repo owner |
+| No board configured → the work-items run failed (strict mode)      | No board configured → the board step is skipped                                 |
+| Release needed `package.json` + `package-lock.json`                | Tag-only release without `package.json`; any lockfile                           |
+| Settings and branch protection by hand                             | `bootstrap` applies `repo-settings.json` and `rulesets/`                        |
+| `TRACEBIM_CI_DIR`, `TRACEBIM_REPOS_ROOT`                           | `CI_DIR`, `CI_REPOS_ROOT` (the old `TRACEBIM_REPOS_ROOT` still works)           |
+
+Repos stay on v1 until they change their `uses:` lines: `v1` is never moved
+again, so nothing breaks on its own.
+
+---
+
+## Part 1 — cutting v2 (this repo, once)
+
+The code is ready on the `feat/generic-ci` branch. The GitHub side, in this
+order:
+
+1. **Rename** the repo, then point your checkout at the new name:
+
+   ```bash
+   gh repo rename ci -R ebalzan/tracebim-ci
+   git remote set-url origin git@github.com:ebalzan/ci.git
+   ```
+
+   Tags move with the repo, so `ebalzan/ci/actions/<name>@v1` resolves right
+   away — this repo's own workflows rely on that until step 5. GitHub redirects
+   the old name for git and the web; do not rely on the redirect for `uses:` in
+   the caller repos — migrate them (Part 2).
+
+2. **Make it public.** The history was scanned for credentials before this
+   change: the only key-shaped string is the `sk-ant-xxxx…` placeholder in
+   `config/secrets.env.example`; `config/secrets.env` was never committed. To
+   re-check: `gitleaks git .` (or `git log --all -p | grep -E 'sk-ant-[A-Za-z0-9]{20}|ghp_[A-Za-z0-9]{30}'`).
+
+   ```bash
+   gh repo edit ebalzan/ci --visibility public --accept-visibility-change-consequences
+   gh api -X PUT repos/ebalzan/ci/private-vulnerability-reporting   # SECURITY.md points here
+   ```
+
+3. **Push the branch.** `self-auto-pr.yml` opens the PR into `dev`:
+
+   ```bash
+   git push -u origin feat/generic-ci
+   ```
+
+   **Retitle the PR** `feat!: make the CI repo generic and public (ebalzan/ci)`
+   — the `!` is what makes the release `v2.0.0` instead of `v1.3.0`. The title
+   check accepts `!` on a `feat/` branch.
+
+4. **Squash-merge** it into `dev`, then squash-merge the `dev → main` PR that
+   appears (titled `feat!: promote dev to main (v2.0.0)`). The release creates
+   `v2.0.0` and the `v2` tag, and warns that the internal refs still say `@v1`.
+   That is expected.
+
+5. **Point the internal refs at v2** (a PR naming `@v2` could not pass its
+   checks before `v2` existed):
+
+   ```bash
+   git switch dev && git pull
+   git switch -c ci/internal-refs-v2
+   sed -i 's#\(ebalzan/ci/actions/[a-z-]*\)@v1#\1@v2#' .github/workflows/*.yml
+   sed -i 's#renovate/tooling\#v1#renovate/tooling\#v2#' renovate.json
+   git commit -am "ci: point internal refs at v2" && git push -u origin ci/internal-refs-v2
+   ```
+
+   Merge it and its promotion PR: `v2.0.1`, with consistent refs.
+
+6. **Apply the rules to this repo** (now public, so the rulesets apply too):
+
+   ```bash
+   npm run gh:bootstrap -- --dry-run
+   npm run gh:bootstrap -- --prune
+   gh repo edit ebalzan/ci --add-topic ebalzan-ci     # optional: include it in --all
+   ```
+
+7. **Publish to npm** — see [CONTRIBUTING.md → Publishing to
+   npm](../CONTRIBUTING.md#publishing-to-npm): one manual `npm publish`, then
+   trusted publishing and `NPM_PUBLISH=true` for every later release.
+
+8. **Optional:** rename the local checkout to match (`mv tracebim-ci ci`).
+   Hooks in repos not migrated yet look for `../tracebim-ci`; until they are,
+   they warn instead of checking (CI still checks), or set
+   `TRACEBIM_CI_DIR=../ci`.
+
+9. **Release `@ebalzan/config` 0.2.0**, which drops its copy of the commit rule
+   (the hook and the PR-title check use `@ebalzan/ci`'s). In its checkout, merge
+   the `refact/move-commit-rules-to-ci` branch into `main`, then
+   `npm version minor && git push --follow-tags` (its `publish.yml` publishes
+   the tag).
+
+---
+
+## Part 2 — moving a repo to v2
+
+For each repo (e.g. `tracebim-api`), on a `ci/…` branch:
+
+1. **Workflow refs:**
+
+   ```bash
+   sed -i 's#ebalzan/tracebim-ci/#ebalzan/ci/#; s#\(ebalzan/ci/[^@]*\)@v1#\1@v2#' .github/workflows/*.yml
+   sed -i 's#github>ebalzan/tracebim-ci//renovate/tooling\#v1#github>ebalzan/ci//renovate/tooling\#v2#' renovate.json
+   grep -rn 'uses: .*tracebim-ci\|tracebim-ci//' .github/workflows renovate.json   # must print nothing
+   grep -rn 'tracebim-ci' .github/workflows   # only comments left: reword them
+   ```
+
+2. **Variables the shared file no longer sets.** If the repo used the shared
+   milestone, add it to the repo's `.github/actions.env`:
+
+   ```dotenv
+   AUTO_MILESTONE_TITLE=oct-26
+   ```
+
+   `AUTO_PROJECT_OWNER` now defaults to the repo owner, which was the old shared
+   value for repos owned by `ebalzan` — nothing to do there.
+
+3. **Hook and scripts** (Node repos):
+
+   ```bash
+   npm install --save-dev @ebalzan/ci
+   npx ebalzan-ci path   # check it is installed
+   ```
+
+   Replace `.husky/commit-msg` with [templates/.husky/commit-msg](../templates/.husky/commit-msg)
+   (placeholders: `ebalzan/ci`, `ci`, `@ebalzan/ci`), and delete any local copy
+   of `scripts/release/validate-conventional-subject.sh`.
+
+   **Remove the `gh:bootstrap` and `gh:reset` npm scripts.** In v2 the admin
+   commands run from your ebalzan/ci checkout (`npm run gh:bootstrap -- -R
+owner/repo` or `--all`) or with `npx @ebalzan/ci bootstrap`, so the repo
+   needs none ([ARCHITECTURE.md §6–7](ARCHITECTURE.md#6-packagejson)).
+
+   Repo scripts that sourced `${TRACEBIM_CI_DIR:-../tracebim-ci}/bin/_lib.sh`
+   become `source "$(npx --no-install ebalzan-ci path)/bin/_lib.sh"`.
+
+   **Code style:** adopt [`@ebalzan/config`](https://www.npmjs.com/package/@ebalzan/config)
+   (≥ 0.2.0, which no longer has a commit rule of its own). For a repo whose
+   `.prettierrc.json` already holds the shared options, that is
+   `npm install --save-dev --save-exact @ebalzan/config`, deleting
+   `.prettierrc.json`, setting `"prettier": "@ebalzan/config/prettier"`, and
+   replacing the shared part of `eslint.config.*` with
+   `...node` from `@ebalzan/config/eslint/node` (keep the repo's own ignores
+   and blocks). `npx ebalzan-config verify` confirms it.
+
+   **Secrets (optional, recommended):** move the repo's `.github/secrets*.env`
+   into `~/.config/ebalzan-ci/repos/<owner>/<repo>/`. Local scripts that read
+   those files (via `LOCAL_ONLY_KEYS`) must then read them from there too, so
+   move a repo with such scripts last, or leave its secrets in the checkout.
+
+4. **Topic**, so `--all` finds the repo: `gh repo edit owner/repo --add-topic ebalzan-ci`.
+
+5. **Bootstrap** and read the plan — v2 adds repository settings (squash only,
+   PR-title commit subjects, delete merged branches) and rulesets:
+
+   ```bash
+   npx ebalzan-ci bootstrap --dry-run
+   npx ebalzan-ci bootstrap
+   ```
+
+   A private repo on the free plan skips the rulesets with a warning.
+
+6. Commit as `ci: move to ebalzan/ci v2`, push, merge. Done when the PR's
+   `title / Validate PR Title` check runs from `ebalzan/ci@v2`.
+
+`--all` finds a repo by its topic from step 4 on; v2 ships with an empty
+`REPOS` list in `config/repos.env`.

package/docs/ONBOARDING.md

@@ -0,0 +1,166 @@
+# Onboarding a repo
+
+Two ways: one command, or by hand. Both end in the same state.
+
+- [Before the first repo](#before-the-first-repo)
+- [With `onboard`](#with-onboard)
+- [By hand](#by-hand)
+- [What each generated file is for](#what-each-generated-file-is-for)
+- [After onboarding](#after-onboarding)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Before the first repo
+
+Once per machine:
+
+1. **GitHub CLI**, logged in as an account with **admin** on the repos:
+   `gh auth login`. If you will use Projects (v2) boards, also
+   `gh auth refresh -s project`.
+2. **Node.js ≥ 20**, git and bash.
+3. **Shared secrets** in `~/.config/ebalzan-ci/secrets.env` (or any directory,
+   with `CI_SECRETS_DIR` pointing at it):
+
+   ```dotenv
+   ANTHROPIC_API_KEY=sk-ant-...   # optional: AI-written issue/PR descriptions
+   GH_PROJECT_TOKEN=ghp_...       # recommended: classic PAT, scopes repo + project
+   ```
+
+   [config/secrets.env.example](../config/secrets.env.example) explains each one,
+   and [CONFIGURATION.md](CONFIGURATION.md#secrets) explains why the token must be
+   classic. A repo's **own** secrets (deploy credentials, …) go next to them, in
+   `~/.config/ebalzan-ci/repos/<owner>/<repo>/secrets.env` and
+   `secrets.<environment>.env` ([ARCHITECTURE §7](ARCHITECTURE.md#7-where-you-run-commands)).
+
+---
+
+## With `onboard`
+
+From a clean checkout of the repo:
+
+```bash
+npx @ebalzan/ci onboard --dry-run
+```
+
+```text
+Onboard   owner/my-repo  ←  ebalzan/ci@v2 (runs-on: ubuntu-latest)
+
+  files (branch ci/onboard-ebalzan-ci from origin/main)
+    create     .github/actions.env
+    create     .github/workflows/auto-pr.yml
+    create     .github/workflows/pr-checks.yml
+    create     .github/workflows/promote-dev-to-main.yml
+    create     .github/workflows/release.yml
+    create     .husky/commit-msg
+    create     eslint.config.mjs
+    create     renovate.json
+    update     .gitignore (ignore .github/secrets*.env)
+    update     package.json "prettier": "@ebalzan/config/prettier"
+  npm
+    install --save-dev @ebalzan/ci@^2.0.0 (and husky, if missing)
+    install --save-dev --save-exact @ebalzan/config (and eslint, prettier, if missing)
+  GitHub (owner/my-repo)
+    create branch dev from origin/main
+    add topic 'ebalzan-ci'
+    bootstrap: variables, secrets, settings, rulesets
+    push ci/onboard-ebalzan-ci → auto-pr.yml opens the PR into dev
+```
+
+If the plan looks right, run it without `--dry-run`. It asks once before
+touching GitHub, and the bootstrap asks once more before pushing config.
+
+Useful options: `--runs-on self-hosted` for self-hosted runners, `--no-push`
+to only make the local commit (inspect it with `git show --stat`, push it
+yourself later), `--force` to replace files the repo already has. All options:
+[CLI.md](CLI.md#onboard).
+
+**Existing files are kept.** If the repo already has, say, a `release.yml`,
+`onboard` leaves it and says so; compare it with
+[templates/](../templates/.github/workflows/) and merge by hand, or re-run with
+`--force` on a fresh branch.
+
+---
+
+## By hand
+
+1. **Branches.** Create `dev` from the default branch, and make `main` the
+   default branch if it is not.
+2. **Workflows.** Copy the four files in
+   [templates/.github/workflows/](../templates/.github/workflows/) into the
+   repo's `.github/workflows/`, replacing `__CI_REPO__` with `ebalzan/ci`,
+   `__CI_REF__` with `v2` and `__RUNS_ON__` with your runner label.
+3. **Variables.** Copy [templates/.github/actions.env](../templates/.github/actions.env)
+   to `.github/actions.env` and set what the repo needs (often nothing, or just
+   `AUTO_PROJECT_NUMBER`). Add `/.github/secrets.env`, `/.github/secrets.*.env`
+   and `!/.github/secrets*.env.example` to `.gitignore`.
+4. **Hook** (Node repos): `npm install --save-dev @ebalzan/ci husky`, add
+   `"prepare": "husky"` to `scripts`, and copy
+   [templates/.husky/commit-msg](../templates/.husky/commit-msg) to
+   `.husky/commit-msg` (fill `__CI_REPO__`, `__CI_REPO_NAME__`, `__CI_PACKAGE__`).
+   **Code style** (Node repos): `npm install --save-dev --save-exact
+@ebalzan/config eslint prettier`, set `"prettier": "@ebalzan/config/prettier"`
+   in `package.json`, copy [templates/eslint.config.mjs](../templates/eslint.config.mjs),
+   and make `tsconfig.json` extend `@ebalzan/config/tsconfig/node.json`. Check
+   with `npx ebalzan-config verify`.
+5. **Renovate** (optional): install the [Renovate app](https://github.com/apps/renovate)
+   on the repo and commit `renovate.json` extending
+   `github>ebalzan/ci//renovate/tooling#v2`.
+6. **Topic:** `gh repo edit owner/my-repo --add-topic ebalzan-ci`, so `--all`
+   finds it.
+7. **Config:** `npx @ebalzan/ci bootstrap --dry-run`, then without `--dry-run`.
+8. Push on a `ci/…` branch and merge the PR.
+
+---
+
+## What each generated file is for
+
+| File                                        | Runs on                   | Does                                                                                                      |
+| ------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `.github/workflows/auto-pr.yml`             | push to any work branch   | Tracking issue + PR into `dev` + board card. [Details](AUTO_WORK_ITEMS_WORKFLOW.md)                       |
+| `.github/workflows/pr-checks.yml`           | PRs into `dev` and `main` | The shared title check, plus **your** build/test jobs — add them here.                                    |
+| `.github/workflows/promote-dev-to-main.yml` | push to `dev`             | Opens/updates the single `dev → main` PR.                                                                 |
+| `.github/workflows/release.yml`             | push to `main`            | Bump, tag, GitHub Release, sync `dev` — plus **your** deploy job, chained on `needs.release.outputs.tag`. |
+| `.github/actions.env`                       | `bootstrap`               | The repo's own variables.                                                                                 |
+| `.husky/commit-msg`                         | every local commit        | Rejects non-conventional messages early. Never blocks when the package is missing.                        |
+| `renovate.json`                             | Renovate, weekly          | One `chore(deps): update dev tooling` PR into `dev`.                                                      |
+
+---
+
+## After onboarding
+
+What is shared and what is now the repo's own, stage by stage:
+[ARCHITECTURE.md](ARCHITECTURE.md).
+
+- **Add the repo's own checks** to `pr-checks.yml` — the template has a
+  commented `validate` job (`npm ci`, `ebalzan-config verify`, `npm run
+validate`). They run in parallel with `title`.
+- **Own Prettier/ESLint/TypeScript config?** `onboard` keeps it and says so.
+  Make it extend `@ebalzan/config` instead of copying rules, then
+  `npx ebalzan-config verify` passes ([ARCHITECTURE §10](ARCHITECTURE.md#10-the-two-packages-ebalzanci-and-ebalzanconfig)).
+- **Add the deploy** to `release.yml` — the template has a commented `deploy`
+  job. Gate it with `if: needs.release.outputs.tag != ''`. For anything beyond
+  a one-liner, use a repo-local `deploy.yml` plus a manual `redeploy.yml`:
+  [ARCHITECTURE.md §4](ARCHITECTURE.md#4-deploys-are-yours).
+- **A board?** Set `AUTO_PROJECT_NUMBER` in `.github/actions.env` and re-run
+  `ebalzan-ci bootstrap`. The board needs the fields listed in
+  [CONFIGURATION.md](CONFIGURATION.md#project-board).
+- **Repo-specific values** (deploy hosts, keys) go in the repo's
+  `.github/secrets.<environment>.env` — see
+  [GITHUB_ACTIONS_SETUP.md](GITHUB_ACTIONS_SETUP.md).
+- **Not a Node repo?** Releases work tag-only (no version commit). There is no
+  husky hook; the PR-title check still enforces the convention on every merge.
+
+---
+
+## Troubleshooting
+
+| Symptom                                                  | Cause / fix                                                                                                                                                                                                                           |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `… has uncommitted changes`                              | Commit or stash first; onboarding always works on a fresh branch.                                                                                                                                                                     |
+| `Branch ci/onboard-ebalzan-ci already exists`            | A previous run left it. `git branch -D ci/onboard-ebalzan-ci` or pass `--branch`.                                                                                                                                                     |
+| `Could not install @ebalzan/ci`                          | No network, or a version that is not published. The hook skips the local check until it is installed; CI still checks.                                                                                                                |
+| No PR appeared after the push                            | Open the Actions tab: `Auto Create Work Items` failed or did not run. Check the repo allows actions from other repositories (Settings → Actions → General → "Allow all actions"). Open the PR from the compare URL `onboard` printed. |
+| `workflow was not found` / `… is not allowed to be used` | The repo's Actions policy blocks `ebalzan/ci`. Allow all actions, or add `ebalzan/ci/*` to the allowed list.                                                                                                                          |
+| `Rulesets are not available … skipped`                   | Private repo on the free plan. Everything else was applied. [REPO_RULES.md](REPO_RULES.md#plans)                                                                                                                                      |
+| PR checks did not run on the bot's PR                    | Opened with `GITHUB_TOKEN` because `GH_PROJECT_TOKEN` is not set. Set it, or push to the PR.                                                                                                                                          |