From 40690a7f7b5172c66e2df2fb0ba58f95f991180c Mon Sep 17 00:00:00 2001 From: Geno Roupsky <185580+groupsky@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:56:20 +0200 Subject: [PATCH] docs: releasing.md stands alone and asks for no required reviewer Closes #5 Closes #6 Co-Authored-By: Claude Opus 5.5 --- docs/releasing.md | 117 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 95 insertions(+), 22 deletions(-) diff --git a/docs/releasing.md b/docs/releasing.md index 55553f4..05d47c3 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -1,8 +1,8 @@ # Releasing pullgate -pullgate uses [release-please](https://github.com/googleapis/release-please) -and the same release setup as nodkey. A release is the merge of the release -pull request. **Only the owner merges it.** +pullgate uses [release-please](https://github.com/googleapis/release-please). +A release is the merge of the release pull request. **Only the owner merges +it.** ## Pull request titles @@ -45,30 +45,103 @@ in a new `fix:` pull request and merge the next release pull request. ## One-time setup -Until this is done, the `release-please` job skips itself. - -1. Install the organization's release GitHub App (the one nodkey uses) on - `code6x/pullgate`, and make a new private key for this repository. The - steps are in [nodkey's `docs/releasing.md`](https://github.com/code6x/nodkey/blob/main/docs/releasing.md), section "One-time setup: a - GitHub App". -2. Save the App's Client ID and the key's fingerprint as repository - variables, and the key as a secret of the `release` environment: +Until this setup is done, the `release-please` job skips itself. In the +**Release** workflow runs it shows as "skipped". Nothing else breaks. + +### Why a GitHub App + +release-please could use the built-in `GITHUB_TOKEN`. But GitHub does not +start workflows for a pull request or a push that `GITHUB_TOKEN` made. So CI +and the PR title check would not run on the release pull request, and it +could not pass the required checks. A token from a GitHub App does start +workflows. + +An App is also better than a personal access token: it does not belong to a +person, it has only the permissions it needs, and each token from it expires +after one hour. + +### Steps + +One App can serve several repositories of the organization. Give each +repository its own private key. Then you can delete one key without +breaking the others. The keys do not keep the repositories apart: any key +of the App can get a token for every repository the App is installed on. +If a repository must be kept apart, give it its own App. + +If the organization already has a release App, skip step 1, and check in +step 2 that its settings match step 1. + +1. Create the App. In the organization, open + **Settings → Developer settings → GitHub Apps → New GitHub App**. + - **GitHub App name**: any free name, for example `-release`. + - **Homepage URL**: the URL of this repository. + - **Webhook**: clear the **Active** box. The App needs no webhook. + - **Repository permissions**: + - **Contents**: Read and write. It creates the release branch, the tag + and the release. + - **Pull requests**: Read and write. It opens the release pull request + and adds labels and comments to it. + - Leave all other permissions at "No access". GitHub adds + **Metadata: Read-only** by itself. + - **Where can this GitHub App be installed?**: **Only on this account**. + - Click **Create GitHub App**. +2. Open the App page: **Settings → Developer settings → GitHub Apps → + Edit** next to the App. Copy the **Client ID**. +3. Open **Credentials → Key pairs** and click **New key**. Your browser + downloads a `.pem` file. Use this key only for this repository. +4. Find the key's fingerprint: ```sh - gh variable set RELEASE_APP_CLIENT_ID --repo code6x/pullgate --body '' - gh variable set RELEASE_APP_KEY_FINGERPRINT --repo code6x/pullgate --body '' - gh secret set RELEASE_APP_PRIVATE_KEY --repo code6x/pullgate --env release < key.pem + echo "SHA256:$(openssl rsa -in path/to/key.pem -pubout -outform DER | openssl sha256 -binary | openssl base64 -A)" ``` - The workflow does not use the fingerprint. It is only a record, so you - can check later which key belongs to this repository. + Check that the **Key pairs** page shows this exact value next to the new + key. If it does not, stop: the path is wrong, or the file is not the new + key. +5. Install the App: **Install App** → your organization → + **Only select repositories** → add `/pullgate` → + **Install** (or **Save**, if the App is already installed on other + repositories). +6. Make the `release` environment first: **Settings → Environments → New + environment**, name `release`, and set **Deployment branches and tags** + to **Selected branches** with only `main`. Then only runs on `main` can + read its secrets. Save the private key as a secret of this environment, + then the Client ID and the fingerprint as repository variables: + + ```sh + gh secret set RELEASE_APP_PRIVATE_KEY --repo /pullgate --env release < path/to/key.pem + gh variable set RELEASE_APP_CLIENT_ID --repo /pullgate --body '' + gh variable set RELEASE_APP_KEY_FINGERPRINT --repo /pullgate --body '' + ``` -3. Settings: a ruleset for `main` (pull requests only, required checks, no - force push), two rulesets for `v*` tags (nobody moves or deletes a tag; - only the App creates one), immutable releases on, and the `release` - environment limited to `main`. Add the owner as a required reviewer of the `release` - environment, so every release waits for the owner's approval in the - Actions page, whoever merged the release pull request. + Do not save the key as a repository secret: then workflow runs on other + branches could read it too. The workflow does not use the fingerprint. + It tells you which key on the **Key pairs** page belongs to this + repository. +7. Delete the `.pem` file from your computer. +8. Repository settings: + - a ruleset for `main`: pull requests only, the required checks, no + force push; + - two rulesets for `v*` tags. **release tags**: **Restrict updates** + and **Restrict deletions**, with an empty bypass list. **release tag + creation**: **Restrict creations**, with only the App in the bypass + list. Two rulesets are needed because a bypass entry skips every rule + of its ruleset; with one, the App could also move or delete tags; + - immutable releases on. + +The `release` environment has **no required reviewer**. The +`release-please` job uses it on every push to `main`, so a reviewer would +hold every merge, not only releases. The gate is the merge of the release +pull request, which only the owner does. This holds only while the owner is +the only person who can merge to `main`. If you give someone else write +access, limit who can merge in the ruleset for `main`. + +The next push to `main` runs release-please with the App. + +If a key leaks, delete it on the **Key pairs** page at once, make a new key +(steps 3 to 7), and look for tags, releases and merged pull requests that +you did not expect. A token made with the old key can still work for up to +one hour. ## Verify a download