Skip to content

Commit 8cc4e3a

Browse files
groupskyclaude
andauthored
docs: releasing.md stands alone and asks for no required reviewer (#12)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent dd7638d commit 8cc4e3a

1 file changed

Lines changed: 95 additions & 22 deletions

File tree

‎docs/releasing.md‎

Lines changed: 95 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# Releasing pullgate
22

3-
pullgate uses [release-please](https://github.com/googleapis/release-please)
4-
and the same release setup as nodkey. A release is the merge of the release
5-
pull request. **Only the owner merges it.**
3+
pullgate uses [release-please](https://github.com/googleapis/release-please).
4+
A release is the merge of the release pull request. **Only the owner merges
5+
it.**
66

77
## Pull request titles
88

@@ -45,30 +45,103 @@ in a new `fix:` pull request and merge the next release pull request.
4545

4646
## One-time setup
4747

48-
Until this is done, the `release-please` job skips itself.
49-
50-
1. Install the organization's release GitHub App (the one nodkey uses) on
51-
`code6x/pullgate`, and make a new private key for this repository. The
52-
steps are in [nodkey's `docs/releasing.md`](https://github.com/code6x/nodkey/blob/main/docs/releasing.md), section "One-time setup: a
53-
GitHub App".
54-
2. Save the App's Client ID and the key's fingerprint as repository
55-
variables, and the key as a secret of the `release` environment:
48+
Until this setup is done, the `release-please` job skips itself. In the
49+
**Release** workflow runs it shows as "skipped". Nothing else breaks.
50+
51+
### Why a GitHub App
52+
53+
release-please could use the built-in `GITHUB_TOKEN`. But GitHub does not
54+
start workflows for a pull request or a push that `GITHUB_TOKEN` made. So CI
55+
and the PR title check would not run on the release pull request, and it
56+
could not pass the required checks. A token from a GitHub App does start
57+
workflows.
58+
59+
An App is also better than a personal access token: it does not belong to a
60+
person, it has only the permissions it needs, and each token from it expires
61+
after one hour.
62+
63+
### Steps
64+
65+
One App can serve several repositories of the organization. Give each
66+
repository its own private key. Then you can delete one key without
67+
breaking the others. The keys do not keep the repositories apart: any key
68+
of the App can get a token for every repository the App is installed on.
69+
If a repository must be kept apart, give it its own App.
70+
71+
If the organization already has a release App, skip step 1, and check in
72+
step 2 that its settings match step 1.
73+
74+
1. Create the App. In the organization, open
75+
**Settings → Developer settings → GitHub Apps → New GitHub App**.
76+
- **GitHub App name**: any free name, for example `<organization>-release`.
77+
- **Homepage URL**: the URL of this repository.
78+
- **Webhook**: clear the **Active** box. The App needs no webhook.
79+
- **Repository permissions**:
80+
- **Contents**: Read and write. It creates the release branch, the tag
81+
and the release.
82+
- **Pull requests**: Read and write. It opens the release pull request
83+
and adds labels and comments to it.
84+
- Leave all other permissions at "No access". GitHub adds
85+
**Metadata: Read-only** by itself.
86+
- **Where can this GitHub App be installed?**: **Only on this account**.
87+
- Click **Create GitHub App**.
88+
2. Open the App page: **Settings → Developer settings → GitHub Apps →
89+
Edit** next to the App. Copy the **Client ID**.
90+
3. Open **Credentials → Key pairs** and click **New key**. Your browser
91+
downloads a `.pem` file. Use this key only for this repository.
92+
4. Find the key's fingerprint:
5693

5794
```sh
58-
gh variable set RELEASE_APP_CLIENT_ID --repo code6x/pullgate --body '<Client ID>'
59-
gh variable set RELEASE_APP_KEY_FINGERPRINT --repo code6x/pullgate --body '<fingerprint>'
60-
gh secret set RELEASE_APP_PRIVATE_KEY --repo code6x/pullgate --env release < key.pem
95+
echo "SHA256:$(openssl rsa -in path/to/key.pem -pubout -outform DER | openssl sha256 -binary | openssl base64 -A)"
6196
```
6297

63-
The workflow does not use the fingerprint. It is only a record, so you
64-
can check later which key belongs to this repository.
98+
Check that the **Key pairs** page shows this exact value next to the new
99+
key. If it does not, stop: the path is wrong, or the file is not the new
100+
key.
101+
5. Install the App: **Install App** → your organization →
102+
**Only select repositories** → add `<organization>/pullgate` →
103+
**Install** (or **Save**, if the App is already installed on other
104+
repositories).
105+
6. Make the `release` environment first: **Settings → Environments → New
106+
environment**, name `release`, and set **Deployment branches and tags**
107+
to **Selected branches** with only `main`. Then only runs on `main` can
108+
read its secrets. Save the private key as a secret of this environment,
109+
then the Client ID and the fingerprint as repository variables:
110+
111+
```sh
112+
gh secret set RELEASE_APP_PRIVATE_KEY --repo <organization>/pullgate --env release < path/to/key.pem
113+
gh variable set RELEASE_APP_CLIENT_ID --repo <organization>/pullgate --body '<Client ID>'
114+
gh variable set RELEASE_APP_KEY_FINGERPRINT --repo <organization>/pullgate --body '<the line from step 4>'
115+
```
65116

66-
3. Settings: a ruleset for `main` (pull requests only, required checks, no
67-
force push), two rulesets for `v*` tags (nobody moves or deletes a tag;
68-
only the App creates one), immutable releases on, and the `release`
69-
environment limited to `main`. Add the owner as a required reviewer of the `release`
70-
environment, so every release waits for the owner's approval in the
71-
Actions page, whoever merged the release pull request.
117+
Do not save the key as a repository secret: then workflow runs on other
118+
branches could read it too. The workflow does not use the fingerprint.
119+
It tells you which key on the **Key pairs** page belongs to this
120+
repository.
121+
7. Delete the `.pem` file from your computer.
122+
8. Repository settings:
123+
- a ruleset for `main`: pull requests only, the required checks, no
124+
force push;
125+
- two rulesets for `v*` tags. **release tags**: **Restrict updates**
126+
and **Restrict deletions**, with an empty bypass list. **release tag
127+
creation**: **Restrict creations**, with only the App in the bypass
128+
list. Two rulesets are needed because a bypass entry skips every rule
129+
of its ruleset; with one, the App could also move or delete tags;
130+
- immutable releases on.
131+
132+
The `release` environment has **no required reviewer**. The
133+
`release-please` job uses it on every push to `main`, so a reviewer would
134+
hold every merge, not only releases. The gate is the merge of the release
135+
pull request, which only the owner does. This holds only while the owner is
136+
the only person who can merge to `main`. If you give someone else write
137+
access, limit who can merge in the ruleset for `main`.
138+
139+
The next push to `main` runs release-please with the App.
140+
141+
If a key leaks, delete it on the **Key pairs** page at once, make a new key
142+
(steps 3 to 7), and look for tags, releases and merged pull requests that
143+
you did not expect. A token made with the old key can still work for up to
144+
one hour.
72145

73146
## Verify a download
74147

0 commit comments

Comments
 (0)