Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 95 additions & 22 deletions docs/releasing.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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 `<organization>-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 '<Client ID>'
gh variable set RELEASE_APP_KEY_FINGERPRINT --repo code6x/pullgate --body '<fingerprint>'
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 `<organization>/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 <organization>/pullgate --env release < path/to/key.pem
gh variable set RELEASE_APP_CLIENT_ID --repo <organization>/pullgate --body '<Client ID>'
gh variable set RELEASE_APP_KEY_FINGERPRINT --repo <organization>/pullgate --body '<the line from step 4>'
```

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

Expand Down
Loading