From b00e7a49fd1d03bac1ff5ee864986e14566f2c46 Mon Sep 17 00:00:00 2001 From: boban Date: Mon, 22 Jun 2026 21:43:38 +0200 Subject: [PATCH] docs: move maintainer release-pipeline guide out of the public README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The release-pipeline + one-time-wiring section named the private staging runner label and described internal setup — not public-facing. Move it to docs/release-pipeline.md (export-ignore, never published) so the public README stays clean and no private repo name leaks via the published tree. Co-Authored-By: Claude Opus 4.8 --- README.md | 39 ---------------------------------- docs/release-pipeline.md | 46 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 39 deletions(-) create mode 100644 docs/release-pipeline.md diff --git a/README.md b/README.md index 5a88725..9d4d826 100644 --- a/README.md +++ b/README.md @@ -159,45 +159,6 @@ e-mail are preserved. (The older two-step `git pull && sudo ./install.sh` still --- -## Release pipeline (maintainers) - -Clusev is promoted across three repositories, dev → staging → public: - -1. **Gitea (private)** — sole development source. Commit + tag here. -2. **GitHub private** — a push-mirror of Gitea (Gitea → Settings → Mirror). Runs CI; betas are tested - on the staging server. -3. **GitHub public** — receives only released versions: one clean commit per release, beta and stable - tags. Public users install/update from here. - -Channels follow semver tags: **beta** = `vX.Y.Z-betaN`, **stable** = `vX.Y.Z`. - -No private repo URL is committed: `config/clusev.php` defaults `repository` to empty, `install.sh` -derives `CLUSEV_REPOSITORY` from the clone origin into the (gitignored) `.env`, so dev points at Gitea, -staging at GitHub-private, and public users at GitHub-public — automatically. - -### One-time wiring (when the GitHub repos exist) - -- Gitea push-mirror → the GitHub-private URL + a GitHub PAT. -- GitHub-private repo settings: - - Variable `PUBLIC_REPO_SLUG` = `owner/repo` of the public repo (the only variable the promotion - workflows read). - - Secret `PUBLIC_REPO_TOKEN` = a token with push to the public repo. - - (Optional staging) Variable `STAGING_ENABLED=true`, `STAGING_PROJECT_DIR`, and a self-hosted - runner labelled `clusev-staging` on the internal network (GitHub-hosted runners cannot reach an - internal staging host). - - Environment `production` with a required reviewer (gates the promotion workflows). -- Public repo's clone command goes in its own README; set `CLUSEV_REPOSITORY` default in - `config/clusev.php` to the public URL once known. - -### Promoting - -- **To staging:** push a beta tag `vX.Y.Z-betaN` (CI tests; staging deploys if enabled, else update it - from the Versions page). -- **To public (beta):** run the `Promote to public (beta channel)` workflow with the beta tag. -- **To stable:** run the `Promote beta to stable` workflow with the beta tag + the stable tag. - ---- - ## Security & recovery The **forgot-password** screen offers self-service recovery: an **e-mail reset link** (valid 15 diff --git a/docs/release-pipeline.md b/docs/release-pipeline.md new file mode 100644 index 0000000..a1efd2b --- /dev/null +++ b/docs/release-pipeline.md @@ -0,0 +1,46 @@ +# Release pipeline (maintainers — INTERNAL) + +> This file is `export-ignore` (see `.gitattributes`) — it never reaches the public repo. It may +> name the private repositories. + +Clusev is promoted across three repositories, dev → staging → public: + +| Repo | URL | Role | +|---|---|---| +| Gitea (dev) | `https://git.bave.dev/boban/clusev` | Sole development source. Commit + tag here. | +| GitHub private (staging) | `https://github.com/boksbc/clusev-staging` | Push-mirror of Gitea. Runs CI; betas tested on staging. | +| GitHub public (release) | `https://github.com/clusev/clusev` | Receives only released versions — one clean commit per release, beta + stable tags. Public users install/update from here. | + +Channels follow semver tags: **beta** = `vX.Y.Z-betaN`, **stable** = `vX.Y.Z`. + +No private repo URL is committed: `config/clusev.php` defaults `repository` to the public URL, +`install.sh` derives `CLUSEV_REPOSITORY` from the clone origin into the (gitignored) `.env`, so dev +points at Gitea, staging at GitHub-private, and public users at GitHub-public — automatically. + +## One-time wiring + +1. **Gitea push-mirror** (Gitea → repo → Settings → Mirror → Push Mirror): + - Remote: `https://github.com/boksbc/clusev-staging.git` + - Auth: GitHub username + a GitHub PAT (scope `repo`) as the password. + - Enable "sync when new commits are pushed". +2. **`boksbc/clusev-staging` → Settings:** + - Variable `PUBLIC_REPO_SLUG = clusev/clusev` (the only variable the promotion workflows read). + - Secret `PUBLIC_REPO_TOKEN` = a PAT/deploy token with push to `clusev/clusev`. + - Environment `production` with a required reviewer (gates the promotion workflows). + - (Optional staging deploy) Variable `STAGING_ENABLED=true`, `STAGING_PROJECT_DIR`, and a + self-hosted runner labelled `clusev-staging` on the internal network — GitHub-hosted runners + cannot reach the internal staging host (`.165`). Until then, update staging from its Versions page. + +## Promoting + +- **To staging:** push a beta tag `vX.Y.Z-betaN` to Gitea → mirror → CI tests it; staging runs the beta. +- **To public (beta):** on `boksbc/clusev-staging` → Actions → run **Promote to public (beta channel)** + with the beta tag → publishes it to `clusev/clusev` (beta channel). +- **To stable:** run **Promote beta to stable** with the beta tag + the stable tag → publishes + `vX.Y.Z` to `clusev/clusev` (stable channel). + +There are no custom webhooks: Gitea's push-mirror + GitHub Actions (`on: push tags` / `workflow_dispatch`) +replace them. `promote.sh` copies the release tree with `git archive`, which honours `export-ignore`, so +internal docs (`CLAUDE.md`, `rules.md`, `handoff.md`, `docs/`) never reach the public repo. Phase B will +drive the `workflow_dispatch` promotions from the dev dashboard via the GitHub API with a deploy token in +the encrypted vault — see `docs/superpowers/specs/2026-06-22-3-repo-release-promotion-design.md`.