|
1 | 1 | # Releasing pullgate |
2 | 2 |
|
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.** |
6 | 6 |
|
7 | 7 | ## Pull request titles |
8 | 8 |
|
@@ -45,30 +45,103 @@ in a new `fix:` pull request and merge the next release pull request. |
45 | 45 |
|
46 | 46 | ## One-time setup |
47 | 47 |
|
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: |
56 | 93 |
|
57 | 94 | ```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)" |
61 | 96 | ``` |
62 | 97 |
|
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 | + ``` |
65 | 116 |
|
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. |
72 | 145 |
|
73 | 146 | ## Verify a download |
74 | 147 |
|
|
0 commit comments