diff --git a/.github/workflows/release-sign.yml b/.github/workflows/release-sign.yml index 42ce8b76..6f9ffaad 100644 --- a/.github/workflows/release-sign.yml +++ b/.github/workflows/release-sign.yml @@ -1,8 +1,12 @@ name: release-sign # Builds, signs, notarizes and publishes Coder Desktop. release.yml calls main's copy of this -# file, also when a release tag starts the run. Google Cloud only lets that copy sign, so a tag -# chooses the commit to release, but not the steps that sign it. +# file. Google Cloud only lets that copy sign, so a release chooses the commit to build, but not +# the steps that sign it. +# +# A run with a version is a release: it only runs on main, for a commit on main, and creates the +# vX.Y.Z tag itself once it is approved. Any other run builds the head of main, as the preview +# build or as a dry run. # # The Developer ID keys live in Google Cloud KMS and cannot be exported. # Xcode cannot sign with a key there, and the library that reaches it only @@ -22,11 +26,10 @@ name: release-sign # Each job records the SHA-256 of what it uploads as a job output, and the job that downloads # it checks the file against that before using it. # -# The three signing jobs run in the "signing" environment, which only main and -# v* tags may use. The publish job runs in the "publish" environment, under -# the same restriction. Neither environment has reviewers, so that preview -# builds from main need no approval. A release waits for one approval, in the -# approve job. See RELEASING.md. +# The three signing jobs run in the "signing" environment and the publish job +# in the "publish" environment. Neither environment has reviewers, so that +# preview builds from main need no approval. A release waits for one approval, +# in the approve job, before it is tagged, built or signed. See RELEASING.md. on: workflow_call: @@ -35,13 +38,27 @@ on: description: 'Run in dry-run mode (upload as artifact instead of release asset)' type: boolean default: false + version: + description: 'Version to release, e.g. v0.8.7. Empty for a preview build or a dry run' + type: string + default: '' + commit: + description: 'Full SHA of the commit on main to release. Required with a version' + type: string + default: '' + release_notes: + description: 'Release notes, also shown in the update prompt. Required with a version' + type: string + default: '' permissions: {} jobs: - # A release tag chooses the commit, and the jobs below run that commit's scripts and actions. - # So only a commit that went through review on main may be built and signed. - on-main: - name: Require a commit on main + # The jobs below run the scripts and actions of the commit they build. So only a commit that + # went through review on main may be built and signed: the head of main, or for a release the + # commit input, once this job has checked it. Every later job checks out + # `inputs.commit || github.sha` and runs only if this job passed. + validate: + name: Check the request runs-on: ubuntu-22.04 if: ${{ github.repository_owner == 'coder' }} permissions: @@ -53,18 +70,135 @@ jobs: fetch-depth: 0 persist-credentials: false - - name: Require a commit on main + - name: Check the request + env: + VERSION: ${{ inputs.version }} + COMMIT: ${{ inputs.commit }} + RELEASE_NOTES: ${{ inputs.release_notes }} + DRYRUN: ${{ inputs.dryrun }} run: | - if ! git merge-base --is-ancestor HEAD refs/remotes/origin/main; then - echo "::error::${GITHUB_REF_NAME} points at ${GITHUB_SHA}, which is not on main." - exit 1 + set -euo pipefail + fail() { echo "::error::$*"; exit 1; } + + # Also stops a run started from a tag or from another branch. + [[ "$GITHUB_REF" == "refs/heads/main" ]] || fail "This workflow only runs on main, not on $GITHUB_REF." + + if [[ -z "$VERSION" ]]; then + [[ -z "$COMMIT" && -z "$RELEASE_NOTES" ]] || fail "commit and release_notes are only for a release: give a version too." + exit 0 fi + [[ "$DRYRUN" != "true" ]] || fail "A release cannot be a dry run: leave version empty for a dry run." + [[ "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || fail "version must look like v1.2.3, got '$VERSION'." + [[ "$COMMIT" =~ ^[0-9a-f]{40}$ ]] || fail "commit must be a full 40-character SHA, got '$COMMIT'." + [[ -n "$RELEASE_NOTES" ]] || fail "A release needs release notes." + git merge-base --is-ancestor "$COMMIT" "$GITHUB_SHA" || fail "$COMMIT is not on main." + + # A release is tagged only after a reviewer of the "release-approval" environment approves + # this job, and it is built and signed only once it is tagged. The job runs for releases only. + # + # Only the coder-release-publisher App may create a tag (ruleset "Release tags (App only)"). + # Its key is in Cloud KMS, and in this repository only this job (main's copy of this file, in + # release-approval) may sign with it. So the tag is created here, at a commit on main, and + # nobody can push one beforehand. + approve: + name: Approve and tag the release + needs: validate + runs-on: ubuntu-22.04 + if: ${{ github.repository_owner == 'coder' && inputs.version != '' }} + environment: release-approval + permissions: + contents: read + id-token: write # Cloud KMS signs the App's JWT + steps: + # For the tags and the history of main. Nothing from the tree runs in this job. + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + fetch-tags: true + persist-credentials: false + + # Here and not in the validate job, because the tags can change while the run waits for + # approval. + - name: Check the tag + id: check + env: + VERSION: ${{ inputs.version }} + COMMIT: ${{ inputs.commit }} + run: | + set -euo pipefail + fail() { echo "::error::$*"; exit 1; } + + # Checked by the validate job too, and again in the job that may tag. + [[ "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || fail "version must look like v1.2.3, got '$VERSION'." + [[ "$COMMIT" =~ ^[0-9a-f]{40}$ ]] || fail "commit must be a full 40-character SHA, got '$COMMIT'." + git merge-base --is-ancestor "$COMMIT" "$GITHUB_SHA" || fail "$COMMIT is not on main." + + # A re-run finds the tag that the first attempt created. + if existing="$(git rev-parse --verify --quiet "refs/tags/$VERSION^{commit}")"; then + [[ "$existing" == "$COMMIT" ]] || fail "Tag $VERSION already exists at $existing, not at $COMMIT." + echo "Tag $VERSION already exists at $COMMIT." + echo "create=false" >> "$GITHUB_OUTPUT" + exit 0 + fi + + # scripts/version.sh reads the version from the tag on the commit, so each release + # needs a commit of its own. + released="$(git tag --points-at "$COMMIT" --list 'v*' | paste -sd ' ' -)" + [[ -z "$released" ]] || fail "$COMMIT was already released as $released. Release a newer commit." + + # Versions only go up, and a release never comes from before the last one. + tags="$(git tag --list 'v*' --sort=-version:refname)" + latest="$(grep -E -m 1 '^v[0-9]+\.[0-9]+\.[0-9]+$' <<<"$tags" || true)" + if [[ -n "$latest" ]]; then + printf '%s\n' "$latest" "$VERSION" | sort -V -C || fail "$VERSION is not newer than $latest, the latest release." + git merge-base --is-ancestor "$latest" "$COMMIT" || fail "$COMMIT is older than the commit released as $latest." + fi + + echo "create=true" >> "$GITHUB_OUTPUT" + + # The App can also write to coder/coder, so the token is asked for this repository only. + - name: Generate release App token + id: app_token + if: ${{ steps.check.outputs.create == 'true' }} + uses: coder/github-app-token-action@00eaec58ee1bfea9c8b48655b7ab7470b07739e5 # main 2026-11-17 + with: + client-id: ${{ secrets.CODER_RELEASE_PUBLISHER_APP_ID }} + kms-key: ${{ secrets.CODER_RELEASE_PUBLISHER_APP_KMS_KEY }} + workload-identity-provider: ${{ secrets.APP_KEYS_WORKLOAD_ID_PROVIDER }} + owner: coder + repositories: coder-desktop-macos + permissions: | + contents: write + workflows: write + + # An annotated tag, through the API: nothing is pushed from this job's checkout. + - name: Create the tag + if: ${{ steps.check.outputs.create == 'true' }} + env: + GH_TOKEN: ${{ steps.app_token.outputs.token }} + VERSION: ${{ inputs.version }} + COMMIT: ${{ inputs.commit }} + run: | + set -euo pipefail + tag_object="$(gh api "repos/$GITHUB_REPOSITORY/git/tags" \ + -f tag="$VERSION" -f message="Release $VERSION" -f object="$COMMIT" -f type=commit \ + --jq .sha)" + gh api "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/tags/$VERSION" -f sha="$tag_object" >/dev/null + echo "Created tag $VERSION at $COMMIT." + + # The approve job is skipped unless this is a release. A job is skipped by default when any + # job before it was, however far back, so this job and every job after it state what they + # need instead. build: name: Build Coder Desktop - needs: on-main + needs: [validate, approve] runs-on: ${{ github.repository_owner == 'coder' && 'depot-macos-26' || 'macos-26'}} - if: ${{ github.repository_owner == 'coder' }} + if: >- + ${{ !cancelled() && github.repository_owner == 'coder' && + needs.validate.result == 'success' && + (needs.approve.result == 'success' || needs.approve.result == 'skipped') }} permissions: contents: read outputs: @@ -74,10 +208,24 @@ jobs: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + ref: ${{ inputs.commit || github.sha }} fetch-depth: 0 fetch-tags: true persist-credentials: false + # The build takes its version from the tag, so stop here if that is not the one asked for. + - name: Check the version + if: ${{ inputs.version != '' }} + env: + VERSION: ${{ inputs.version }} + run: | + set -euo pipefail + tagged="v$(./scripts/version.sh)" + if [[ "$tagged" != "$VERSION" ]]; then + echo "::error::The tags give this commit the version $tagged, not $VERSION." + exit 1 + fi + - name: Switch XCode Version uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0 with: @@ -121,7 +269,7 @@ jobs: # can write that branch's caches. rcodesign: name: Build rcodesign - needs: on-main + needs: validate runs-on: ubuntu-22.04 if: ${{ github.repository_owner == 'coder' }} permissions: @@ -132,6 +280,7 @@ jobs: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + ref: ${{ inputs.commit || github.sha }} persist-credentials: false - name: Build rcodesign @@ -151,22 +300,8 @@ jobs: path: /tmp/rcodesign-bin/rcodesign retention-days: 1 - # A release is signed only after a reviewer of the "release-approval" environment approves - # this job. It runs for releases only. The environment holds no secrets. - approve: - name: Approve the release - needs: on-main - runs-on: ubuntu-22.04 - if: ${{ github.repository_owner == 'coder' && github.event_name == 'release' }} - environment: release-approval - permissions: {} - steps: - - name: Approved - run: echo "Approved." - - # The approve job is skipped unless this is a release. A job is skipped by default when any - # job before it was, however far back, so this job and every job after it state what they - # need instead. + # Needs the approve job itself and not only the build that waited for it, so that nothing is + # signed for a release without the approval, whatever happens to the build job. sign-app: name: Sign and notarize the app needs: [build, rcodesign, approve] @@ -177,7 +312,7 @@ jobs: (needs.approve.result == 'success' || needs.approve.result == 'skipped') }} # Holds the signing identity. The Google Cloud workload identity provider # only exchanges tokens for main's copy of this file, from this environment, - # on main or a release tag. + # which only main may use. environment: signing permissions: contents: read @@ -189,6 +324,7 @@ jobs: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + ref: ${{ inputs.commit || github.sha }} persist-credentials: false # Tools first, before any credential is written to disk. rcodesign comes from the @@ -359,6 +495,7 @@ jobs: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + ref: ${{ inputs.commit || github.sha }} persist-credentials: false - name: Download signed app @@ -423,6 +560,7 @@ jobs: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + ref: ${{ inputs.commit || github.sha }} persist-credentials: false # Tools first, as in the sign-app job. @@ -656,6 +794,7 @@ jobs: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + ref: ${{ inputs.commit || github.sha }} fetch-depth: 0 fetch-tags: true persist-credentials: false @@ -721,13 +860,28 @@ jobs: if: ${{ !inputs.dryrun }} uses: google-github-actions/setup-gcloud@aa5489c8933f4cc7a4f7d45035b3b1440c9c10db # v3.0.1 - # Upload to release in non-dry-run mode - - name: Upload Release Assets - if: ${{ !inputs.dryrun }} - run: gh release upload "$RELEASE_TAG" build/out/* --clobber + # The preview build replaces the assets of the "preview" release. + - name: Upload Preview Assets + if: ${{ !inputs.dryrun && inputs.version == '' }} + run: gh release upload preview build/out/* --clobber + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + # The approve job created the tag, and --verify-tag stops gh from creating one here. A + # re-run finds the release that the first attempt created, and replaces its assets. + - name: Create Release + if: ${{ !inputs.dryrun && inputs.version != '' }} + run: | + set -euo pipefail + if gh release view "$VERSION" >/dev/null 2>&1; then + gh release upload "$VERSION" build/out/* --clobber + else + gh release create "$VERSION" build/out/* --verify-tag --title "$VERSION" --notes "$RELEASE_NOTES" + fi env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - RELEASE_TAG: ${{ github.event_name == 'release' && github.event.release.tag_name || 'preview' }} + VERSION: ${{ inputs.version }} + RELEASE_NOTES: ${{ inputs.release_notes }} - name: Update Appcast if: ${{ !inputs.dryrun }} @@ -743,17 +897,17 @@ jobs: popd gsutil -h "Cache-Control:no-cache,max-age=0" cp ./appcast.xml "gs://releases.coder.com/coder-desktop/mac/appcast.xml" env: - VERSION_DESCRIPTION: ${{ (github.event_name == 'release' && github.event.release.body) || (github.event_name == 'push' && github.event.head_commit.message) || '' }} + VERSION_DESCRIPTION: ${{ inputs.release_notes || (github.event_name == 'push' && github.event.head_commit.message) || '' }} update-cask: name: Update homebrew-coder cask runs-on: ${{ github.repository_owner == 'coder' && 'depot-macos-26' || 'macos-26'}} if: >- - ${{ !cancelled() && github.repository_owner == 'coder' && github.event_name == 'release' && + ${{ !cancelled() && github.repository_owner == 'coder' && inputs.version != '' && needs.publish.result == 'success' }} needs: publish - # Only this job (main's release-sign.yml, in release-publish: release tags only, approved by a - # release manager) may sign with the coder-package-publisher App's Cloud KMS key. + # Only this job (main's release-sign.yml, in release-publish, approved by a release manager) + # may sign with the coder-package-publisher App's Cloud KMS key. environment: release-publish permissions: id-token: write # Cloud KMS signs the App's JWT @@ -761,6 +915,7 @@ jobs: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + ref: ${{ inputs.commit || github.sha }} fetch-depth: 0 fetch-tags: true persist-credentials: false @@ -785,7 +940,7 @@ jobs: shell: nix develop .#ci --command bash --noprofile --norc -eo pipefail {0} env: GH_TOKEN: ${{ steps.publisher_token.outputs.token }} - RELEASE_TAG: ${{ github.event.release.tag_name }} + RELEASE_TAG: ${{ inputs.version }} ASSIGNEE: ${{ github.actor }} run: | git config --global user.email "ci@coder.com" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 1c28b55b..4cdf3e5f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,17 +1,28 @@ name: release -# Starts the build of Coder Desktop: the preview build on a push to main, a release when one is -# published. The jobs are in release-sign.yml. See RELEASING.md. +# Starts the build of Coder Desktop: the preview build on a push to main, a release when the +# workflow is dispatched on main with a version, which scripts/release.sh does. The jobs are in +# release-sign.yml. See RELEASING.md. on: push: branches: - main - release: - types: [published] workflow_dispatch: inputs: + version: + description: 'Version to release, e.g. v0.8.7. Leave empty for a preview build or a dry run' + required: false + type: string + commit: + description: 'Full SHA of the commit on main to release. Required with a version' + required: false + type: string + release_notes: + description: 'Release notes, also shown in the update prompt. Required with a version' + required: false + type: string dryrun: description: 'Run in dry-run mode (upload as artifact instead of release asset)' required: true @@ -20,20 +31,23 @@ on: permissions: {} # Cancel in-progress runs for when multiple PRs get merged -# in quick succession. Ignore this for tag releases though. +# in quick succession. A release has its own group, so that a merge to main never cancels it. concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: ${{ !contains(github.ref, 'tags/')}} + group: ${{ github.workflow }}-${{ inputs.version || github.ref }} + cancel-in-progress: ${{ !inputs.version }} jobs: release: # Runs main's copy of release-sign.yml, not this commit's. Google Cloud only lets that copy - # sign, so a release tag chooses the commit to release, but not the steps that sign it. + # sign, so a release chooses the commit to build, but not the steps that sign it. uses: coder/coder-desktop-macos/.github/workflows/release-sign.yml@main # zizmor: ignore[secrets-inherit,unpinned-uses] with: dryrun: ${{ inputs.dryrun || false }} + version: ${{ inputs.version || '' }} + commit: ${{ inputs.commit || '' }} + release_notes: ${{ inputs.release_notes || '' }} # The environment secrets only reach the called jobs if the caller passes them. secrets: inherit permissions: - contents: write # upload the release assets + contents: write # create the release and upload its assets id-token: write # authenticate to Google Cloud diff --git a/RELEASING.md b/RELEASING.md index 5cdde12b..9e0d0663 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -6,29 +6,55 @@ this repository. ## Releasing a new version Versions come from Git tags of the form `vX.Y.Z` (see `scripts/version.sh`). -Pushing a tag doesn't start a workflow, but the GitHub release needs a tag to -point at. - -1. Tag the commit on `main` that you want to release, and push the tag: +Nobody can push a tag to this repository. The `release` workflow creates the +tag, and the GitHub release, after another release manager has approved the +run. + +1. Merge what you want to release to `main`, and wait for the `release` + workflow run of the last push to `main` to finish. That run publishes the + `preview` build and updates the appcast, and so does a release, so two of + them at once can lose one of the two updates. For the same reason, don't + merge to `main` while a release is running. +2. Write the release notes. They become the description of the GitHub release + and the update description in the Sparkle appcast. +3. Start the release: ```bash - git tag vX.Y.Z - git push origin vX.Y.Z + ./scripts/release.sh vX.Y.Z ``` -2. Wait for the `release` workflow run for that commit on `main` to finish. - It publishes the `preview` build and updates the appcast, so publishing the - release while it is still running can race on the appcast update. -3. [Create a GitHub release](https://github.com/coder/coder-desktop-macos/releases/new) - from the tag and write the release notes. The release notes are used as the - update description in the Sparkle appcast, so write them before publishing. -4. Publishing the release starts the `release` workflow, which builds, signs, - and notarizes the app, uploads the assets to the release, updates the - appcast, and opens a pull request to update the - [homebrew-coder](https://github.com/coder/homebrew-coder) cask. The run - waits for approval twice: once before anything is signed, and once before - the cask pull request is opened (see [Approvals](#approvals)). Wait for it - to finish, then review and merge the cask pull request. + The script releases the head of `main` unless you pass `--commit`, and + opens your editor for the release notes unless you pass `--notes-file`. It + checks the version and the commit, shows what it is about to release, and + asks before it starts the `release` workflow. With `--dry-run` it stops + after the checks. +4. Ask another member of `coder/coder-desktop-release-managers` to approve the + run (see [Approvals](#approvals)). You cannot approve a release you started. +5. Once approved, the run creates the tag, builds, signs and notarizes the + app, creates the GitHub release with its assets, updates the appcast, and + opens a pull request to update the + [homebrew-coder](https://github.com/coder/homebrew-coder) cask. It waits + for a second approval before it opens that pull request. Wait for it to + finish, then review and merge the cask pull request. + +The workflow refuses a release unless all of these hold. `scripts/release.sh` +checks them first, so that a mistake shows before anyone is asked to approve. + +- The run is on `main`, and the commit is on `main`. +- The version looks like `vX.Y.Z` and is higher than the latest release. +- The commit comes after the latest release and has no release tag yet. +- There are release notes. + +### When a release run fails + +The tag is created before the app is built. If a later job fails, fix the +cause and re-run the failed jobs, or start the same version for the same +commit again: the run finds the tag, and the release if there is one, and goes +on from there. Starting it again takes a new approval, and uses the newest +`release-sign.yml` on `main`, which re-running the failed jobs does not. + +If the commit itself needs a fix, release the fixed commit as the next +version. A tag is never moved to another commit. ## How releases are signed @@ -67,7 +93,7 @@ that the key is never next to the tools `publish` downloads. ### Secrets `sign-app`, `sign-installer` and `sign-sparkle` run in the `signing` -environment, which only `main` and `v*` tags may use. Its secrets: +environment, which only `main` may use. Its secrets: | Secret | What it is | | ------------------------------ | ----------------------------------------------------------------- | @@ -87,22 +113,38 @@ environment, which only `main` and `v*` tags may use. Its secrets: Google Cloud only gives a job the signing identity when the job comes from the copy of `release-sign.yml` on `main` and runs in the `signing` -environment, on `main` or a release tag. +environment. -`publish` runs in the `publish` environment, which also only `main` and `v*` -tags may use. It holds no signing secret, so that the tools `publish` downloads -never run next to one. Its secrets: +`publish` runs in the `publish` environment, which also only `main` may use. +It holds no signing secret, so that the tools `publish` downloads never run +next to one. Its secrets: | Secret | What it is | | -------------------------- | --------------------------------------------------------- | | `GCP_WORKLOAD_ID_PROVIDER` | Google Cloud workload identity provider for publishing | | `GCP_SERVICE_ACCOUNT` | Service account that may write the appcast to the releases bucket | +`approve` runs in the `release-approval` environment and creates the release +tag as the `coder-release-publisher` GitHub App, the App that also tags +coder/coder's releases. The App's key is in Cloud KMS, like the signing keys, +so the environment holds no key, only what the job needs to ask for a +signature: + +| Secret | What it is | +| ------------------------------------- | ---------------------------------------------------- | +| `CODER_RELEASE_PUBLISHER_APP_ID` | The App's client ID | +| `CODER_RELEASE_PUBLISHER_APP_KMS_KEY` | Resource name of the App's key in Cloud KMS | +| `APP_KEYS_WORKLOAD_ID_PROVIDER` | Google Cloud workload identity provider for App keys | + +In this repository, Google Cloud only signs with that key for a job that comes +from the copy of `release-sign.yml` on `main` and runs in the +`release-approval` environment. + ### Approvals Every push to `main` is signed and published as the `preview` build, so the `signing` and `publish` environments must have no required reviewers. A release is approved -once, in the `approve` job, before anything is signed. +once, in the `approve` job, before it is tagged, built or signed. | Environment | Required reviewers | Used by | Approval asked | | ------------------ | --------------------------------------- | -------------------------------------------- | ---------------- | @@ -111,34 +153,40 @@ once, in the `approve` job, before anything is signed. | `release-approval` | `coder/coder-desktop-release-managers` | `approve` | Once per release | | `release-publish` | `coder/release-managers` | `update-cask` | Once per release | -`release-approval` holds no secrets, and only `v*` tags may use it. Neither -reviewed environment lets the person who published the release approve it, so -a release needs a second person. The environments are managed in +All four environments only accept `main`, which is where a release runs. +Neither reviewed environment lets the person who started the release approve +it, so a release needs a second person. The environments are managed in [coder/github-org-terraform](https://github.com/coder/github-org-terraform). `release.yml` only starts the run. It calls the copy of `release-sign.yml` on -`main`, also when a release tag starts the run, and Google Cloud lets no other -copy sign. So a tag chooses the commit to release, but not the jobs that sign -it, and it cannot leave out the `approve` job. The first job stops the run if -that commit is not on `main`. The jobs come from the newest `main`, while the -scripts they run come from the tagged commit. +`main`, and Google Cloud lets no other copy sign. So a release chooses the +commit to build, but not the jobs that sign it, and it cannot leave out the +`approve` job. The first job stops the run unless it is on `main` and the +commit is on `main`. The jobs come from the newest `main`, while the scripts +they run come from the released commit. The approval is a job in `release-sign.yml`, so a change to that file on `main` could sign without it. What protects against that is the review of changes to `main`. -The approval does not protect the secrets of the `signing` environment. GitHub -gives them to any job in that environment on a `v*` tag, whatever workflow -file the tag carries. Two of them are keys: `SPARKLE_PRIVATE_KEY` and -`AC_APIKEY_P8_BASE64`. The same holds for the `publish` environment, whose -identity may write the appcast. What protects those is that only -`coder/coder-desktop-release-managers` may push a `v*` tag. +The approval does not protect the secrets of the `signing` environment, which +every push to `main` uses without one. Two of them are keys: +`SPARKLE_PRIVATE_KEY` and `AC_APIKEY_P8_BASE64`. The same holds for the +`publish` environment, whose identity may write the appcast. What protects +those is that both environments only accept `main`, and the review of changes +to `main`. + +Only the `coder-release-publisher` App may create, move or delete a tag. A +ruleset stops everyone else, admins included, and in this repository the App +can only be used from the `approve` job. So a release tag always points at a +commit on `main` that a second release manager approved. ### Trying a change -Run the `release` workflow manually on `main` with **dryrun** enabled. The -build is uploaded as a workflow artifact instead of a release asset. The -signing jobs cannot run from any other branch. A dry run needs no approval. +Run the `release` workflow manually on `main` with **dryrun** enabled and no +version. The build is uploaded as a workflow artifact instead of a release +asset. The workflow does not run from any other branch. A dry run needs no +approval. Every run uses the copy of `release-sign.yml` on `main`, so a change to that file cannot be tried before it is merged. diff --git a/scripts/release.sh b/scripts/release.sh new file mode 100755 index 00000000..207aaa73 --- /dev/null +++ b/scripts/release.sh @@ -0,0 +1,180 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Starts a release of Coder Desktop: checks the version and the commit, then dispatches the +# release workflow on main. Nobody pushes the vX.Y.Z tag: the run creates it once another +# release manager approves it. See RELEASING.md. +# +# The checks here are the workflow's own, repeated so that a mistake shows before the run +# asks anyone for approval. The workflow is what enforces them. +# +# Requires: git, and gh logged in to an account with write access to the repository. + +REPO="coder/coder-desktop-macos" +REMOTE_URL="https://github.com/$REPO.git" +WORKFLOW="release.yml" + +usage() { + echo "Usage: $0 [--commit ] [--notes-file ] [--dry-run] " + echo " Version to release, e.g. v0.8.7" + echo " --commit Commit on main to release (default: the head of main)" + echo " --notes-file Read the release notes from instead of opening an editor" + echo " --dry-run Run the checks and show the release, without starting it" + echo " -h, --help Display this help message" +} + +die() { + echo "Error: $*" >&2 + exit 1 +} + +VERSION="" +COMMIT="" +NOTES_FILE="" +DRY_RUN=false + +while [[ "$#" -gt 0 ]]; do + case $1 in + --commit) + [[ "$#" -ge 2 ]] || die "--commit needs a value" + COMMIT="$2" + shift 2 + ;; + --notes-file) + [[ "$#" -ge 2 ]] || die "--notes-file needs a value" + NOTES_FILE="$2" + shift 2 + ;; + --dry-run) + DRY_RUN=true + shift + ;; + -h | --help) + usage + exit 0 + ;; + -*) + echo "Unknown parameter passed: $1" + usage + exit 1 + ;; + *) + [[ -z "$VERSION" ]] || die "Only one version can be released at a time" + VERSION="$1" + shift + ;; + esac +done + +[[ -n "$VERSION" ]] || { + usage + exit 1 +} +[[ "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || die "The version must look like v1.2.3, got '$VERSION'" +[[ -z "$NOTES_FILE" || -f "$NOTES_FILE" ]] || die "No such file: $NOTES_FILE" + +command -v gh >/dev/null || die "gh is not installed" +gh auth status >/dev/null 2>&1 || die "gh is not logged in. Run 'gh auth login'" + +# The notes file may be a relative path, so resolve it before changing directory. +if [[ -n "$NOTES_FILE" ]]; then + NOTES_FILE="$(cd "$(dirname "$NOTES_FILE")" && pwd)/$(basename "$NOTES_FILE")" +fi +cd "$(dirname "${BASH_SOURCE[0]}")/.." + +# From GitHub and not from a remote of this clone, which may be a fork or out of date. +git fetch --quiet "$REMOTE_URL" refs/heads/main +main_head="$(git rev-parse FETCH_HEAD)" +git fetch --quiet "$REMOTE_URL" 'refs/tags/v*:refs/tags/v*' + +commit="$(git rev-parse --verify --quiet "${COMMIT:-$main_head}^{commit}")" || + die "'$COMMIT' is not a commit in this clone" +git merge-base --is-ancestor "$commit" "$main_head" || + die "$commit is not on main. Merge it through a pull request first" + +tag_exists=false +if existing="$(git rev-parse --verify --quiet "refs/tags/$VERSION^{commit}")"; then + [[ -n "$(git ls-remote --tags "$REMOTE_URL" "refs/tags/$VERSION")" ]] || + die "Tag $VERSION exists in this clone but not on GitHub. The release run creates the tag: delete yours with 'git tag -d $VERSION'" + [[ "$existing" == "$commit" ]] || die "Tag $VERSION already exists at $existing, not at $commit" + tag_exists=true +fi + +tags="$(git tag --list 'v*' --sort=-version:refname)" +latest="$(grep -E -m 1 '^v[0-9]+\.[0-9]+\.[0-9]+$' <<<"$tags" || true)" +if [[ "$tag_exists" == false ]]; then + # scripts/version.sh reads the version from the tag on the commit, so each release needs a + # commit of its own. + released="$(git tag --points-at "$commit" --list 'v*' | paste -sd ' ' -)" + [[ -z "$released" ]] || die "$commit was already released as $released. Release a newer commit" + + # Versions only go up, and a release never comes from before the last one. + if [[ -n "$latest" ]]; then + printf '%s\n' "$latest" "$VERSION" | sort -V -C || + die "$VERSION is not newer than $latest, the latest release" + git merge-base --is-ancestor "$latest" "$commit" || + die "$commit is older than the commit released as $latest" + fi +fi + +# Every push to main publishes a preview build and rewrites the appcast, and so does a release. +# Two runs doing that at once can lose one of the two updates. +running="$(gh run list --repo "$REPO" --workflow "$WORKFLOW" --branch main --event push \ + --json status,url --jq '.[] | select(.status != "completed") | .url')" +[[ -z "$running" ]] || die "A preview build is still running. Wait for it to finish: $running" + +# A commit whose preview build failed will likely fail as a release too, after it is tagged. +preview="$(gh run list --repo "$REPO" --workflow "$WORKFLOW" --branch main --event push \ + --commit "$commit" --limit 1 --json conclusion --jq '.[0].conclusion // empty')" + +notes="" +if [[ -n "$NOTES_FILE" ]]; then + notes="$(<"$NOTES_FILE")" +elif [[ "$DRY_RUN" == false ]]; then + notes_file="$(mktemp)" + trap 'rm -f "$notes_file"' EXIT + # Through sh, as git does, because the variable may hold a command with arguments, like + # "code --wait". + sh -c "${VISUAL:-${EDITOR:-vi}} \"\$1\"" -- "$notes_file" + notes="$(<"$notes_file")" +fi +if [[ -n "$NOTES_FILE" || "$DRY_RUN" == false ]]; then + [[ -n "${notes//[[:space:]]/}" ]] || die "The release notes are empty" +fi + +echo "Release $VERSION of $REPO" +echo " Commit: $commit" +echo " $(git log -1 --format='%s (%cs)' "$commit")" +echo " Latest release: ${latest:-none}" +echo " Preview build: ${preview:-none found for this commit}" +if [[ "$tag_exists" == true ]]; then + echo " Tag: $VERSION already exists at this commit. The run will use it" +fi +if [[ -n "$notes" ]]; then + echo " Release notes:" + while IFS= read -r line; do + echo " $line" + done <<<"$notes" +fi +echo + +if [[ "$DRY_RUN" == true ]]; then + echo "Dry run: nothing was started." + exit 0 +fi + +answer="" +read -r -p "Start the release? [y/N] " answer || true +[[ "$answer" =~ ^[Yy]$ ]] || { + echo "Nothing was started." + exit 0 +} + +gh workflow run "$WORKFLOW" --repo "$REPO" --ref main \ + -f version="$VERSION" -f commit="$commit" -f release_notes="$notes" -f dryrun=false + +echo +echo "The release run has started:" +echo " https://github.com/$REPO/actions/workflows/$WORKFLOW?query=event%3Aworkflow_dispatch" +echo "It now waits for a release manager other than you to approve it. Once approved, it creates" +echo "the tag $VERSION, then builds, signs and publishes the release. See RELEASING.md."