Automate and validate the release flow (#998)

* improve release flow

* limit permission

* Test and harden the release workflow

* Keep workspace lockfile versions aligned

* Run release regression tests in CI

.github/workflows/finalise-release.yml

@@ -0,0 +1,92 @@
+name: Finalise Release Tags
+
+on:
+    workflow_dispatch:
+        inputs:
+            version:
+                description: Release version, for example 0.25.81
+                required: true
+                type: string
+            release_branch:
+                description: Release PR branch. Defaults to the version with dots replaced by underscores.
+                required: false
+                type: string
+            expected_head_sha:
+                description: Full head commit SHA reviewed in the release PR
+                required: true
+                type: string
+
+jobs:
+    finalise:
+        runs-on: ubuntu-latest
+        environment: release
+        permissions:
+            contents: write
+        steps:
+            - name: Resolve release branch
+              id: branch
+              env:
+                  VERSION: ${{ inputs.version }}
+                  RELEASE_BRANCH_INPUT: ${{ inputs.release_branch }}
+              run: |
+                  set -euo pipefail
+                  BRANCH="${RELEASE_BRANCH_INPUT}"
+                  if [[ -z "${BRANCH}" ]]; then
+                    BRANCH="${VERSION//./_}"
+                  fi
+                  echo "name=${BRANCH}" >> "$GITHUB_OUTPUT"
+
+            - uses: actions/checkout@v4
+              with:
+                  ref: ${{ steps.branch.outputs.name }}
+                  fetch-depth: 0
+                  submodules: recursive
+
+            - name: Use Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: "24.x"
+
+            - name: Validate release head
+              env:
+                  VERSION: ${{ inputs.version }}
+                  EXPECTED_HEAD_SHA: ${{ inputs.expected_head_sha }}
+              run: |
+                  set -euo pipefail
+                  ACTUAL_HEAD_SHA="$(git rev-parse HEAD)"
+                  if [[ "${ACTUAL_HEAD_SHA}" != "${EXPECTED_HEAD_SHA}" ]]; then
+                    echo "Release branch head is ${ACTUAL_HEAD_SHA}, expected ${EXPECTED_HEAD_SHA}." >&2
+                    exit 1
+                  fi
+                  node utils/release-notes.mjs validate "${VERSION}"
+                  git fetch --tags --force
+                  if git rev-parse --verify --quiet "refs/tags/${VERSION}" >/dev/null; then
+                    echo "Tag already exists: ${VERSION}" >&2
+                    exit 1
+                  fi
+                  if git rev-parse --verify --quiet "refs/tags/${VERSION}-cli" >/dev/null; then
+                    echo "Tag already exists: ${VERSION}-cli" >&2
+                    exit 1
+                  fi
+
+            - name: Create and push release tags
+              env:
+                  VERSION: ${{ inputs.version }}
+              run: |
+                  set -euo pipefail
+                  git tag "${VERSION}"
+                  git tag "${VERSION}-cli"
+                  git push origin "${VERSION}" "${VERSION}-cli"
+
+            - name: Summarise next steps
+              env:
+                  VERSION: ${{ inputs.version }}
+              run: |
+                  {
+                    echo "Created tags \`${VERSION}\` and \`${VERSION}-cli\`."
+                    echo ""
+                    echo "The plug-in release workflow is triggered by the \`${VERSION}\` tag and creates a draft release by default."
+                    echo "The CLI Docker workflow is triggered by the \`${VERSION}-cli\` tag and publishes the version, major-minor, latest, and SHA-qualified image tags."
+                    echo ""
+                    echo "To create a pre-release instead of the default draft flow, run \`Release Obsidian Plugin\` manually with \`tag=${VERSION}\`, \`draft=false\`, and \`prerelease=true\`."
+                  } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/prepare-release.yml

@@ -0,0 +1,108 @@
+name: Prepare Release PR
+
+on:
+    workflow_dispatch:
+        inputs:
+            version:
+                description: Release version, for example 0.25.81
+                required: true
+                type: string
+            base_branch:
+                description: Base branch for the release PR
+                required: false
+                type: string
+                default: main
+            release_branch:
+                description: Release branch name. Defaults to the version with dots replaced by underscores.
+                required: false
+                type: string
+            release_date:
+                description: Release date in ordinal format. Defaults to the current UTC date.
+                required: false
+                type: string
+            allow_empty_updates:
+                description: Allow an empty Unreleased section
+                required: false
+                type: boolean
+                default: false
+
+jobs:
+    prepare:
+        runs-on: ubuntu-latest
+        permissions:
+            contents: write
+            pull-requests: write
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  ref: ${{ inputs.base_branch }}
+                  fetch-depth: 0
+                  submodules: recursive
+
+            - name: Use Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: "24.x"
+                  cache: npm
+
+            - name: Install dependencies
+              run: npm ci
+
+            - name: Prepare release changes
+              id: prepare
+              env:
+                  VERSION: ${{ inputs.version }}
+                  RELEASE_BRANCH_INPUT: ${{ inputs.release_branch }}
+                  RELEASE_DATE: ${{ inputs.release_date }}
+                  ALLOW_EMPTY_UPDATES: ${{ inputs.allow_empty_updates }}
+              run: |
+                  set -euo pipefail
+                  git config user.name "github-actions[bot]"
+                  git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+                  BRANCH="${RELEASE_BRANCH_INPUT}"
+                  if [[ -z "${BRANCH}" ]]; then
+                    BRANCH="${VERSION//./_}"
+                  fi
+
+                  if git ls-remote --exit-code --heads origin "${BRANCH}" >/dev/null 2>&1; then
+                    echo "Release branch already exists: ${BRANCH}" >&2
+                    exit 1
+                  fi
+
+                  git switch -c "${BRANCH}"
+                  npm version "${VERSION}" --no-git-tag-version
+                  node utils/release-notes.mjs prepare "${VERSION}"
+                  npm run pretty:json
+
+                  git add package.json package-lock.json manifest.json versions.json updates.md src/apps/cli/package.json src/apps/webpeer/package.json src/apps/webapp/package.json
+                  git diff --cached --check
+                  git commit -m "Releasing ${VERSION}"
+                  git push --set-upstream origin "${BRANCH}"
+
+                  echo "branch=${BRANCH}" >> "$GITHUB_OUTPUT"
+
+            - name: Create draft release PR
+              env:
+                  GH_TOKEN: ${{ github.token }}
+                  VERSION: ${{ inputs.version }}
+                  BASE_BRANCH: ${{ inputs.base_branch }}
+                  RELEASE_BRANCH: ${{ steps.prepare.outputs.branch }}
+              run: |
+                  cat > /tmp/release-pr-body.md <<EOF
+                  ## Release checklist
+
+                  - [ ] Review and polish \`updates.md\`
+                  - [ ] Confirm the release date
+                  - [ ] Confirm \`manifest.json\`, \`versions.json\`, and workspace package versions
+                  - [ ] Confirm CI has passed
+                  - [ ] Run the finalise release workflow with this PR's fixed head SHA
+                  - [ ] Merge this PR with a merge commit after the draft or pre-release has been created
+                  EOF
+
+                  gh pr create \
+                    --base "${BASE_BRANCH}" \
+                    --head "${RELEASE_BRANCH}" \
+                    --draft \
+                    --title "Releasing ${VERSION}" \
+                    --body-file /tmp/release-pr-body.md

.github/workflows/release.yml

@@ -6,10 +6,26 @@ on:
     - '*' # Push events to matching any tag format, i.e. 1.0, 20.15.10
     - '!*-cli' # Exclude command-line interface tags
   workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to build
+        required: true
+        type: string
+      draft:
+        description: Create the GitHub Release as a draft
+        required: false
+        type: boolean
+        default: true
+      prerelease:
+        description: Mark the GitHub Release as a pre-release
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build:
     runs-on: ubuntu-latest
+    environment: release
     permissions:
       contents: write
       id-token: write
@@ -19,6 +35,7 @@ jobs:
       with:
         fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
         submodules: recursive
+        ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }}
     - name: Use Node.js
       uses: actions/setup-node@v4
       with:
@@ -27,7 +44,18 @@ jobs:
     - name: Get Version
       id: version
       run: |
-        echo "tag=$(git describe --abbrev=0 --tags)" >> $GITHUB_OUTPUT
+        if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+          TAG="${{ inputs.tag }}"
+          DRAFT="${{ inputs.draft }}"
+          PRERELEASE="${{ inputs.prerelease }}"
+        else
+          TAG="${GITHUB_REF_NAME}"
+          DRAFT="true"
+          PRERELEASE="false"
+        fi
+        echo "tag=${TAG}" >> $GITHUB_OUTPUT
+        echo "draft=${DRAFT}" >> $GITHUB_OUTPUT
+        echo "prerelease=${PRERELEASE}" >> $GITHUB_OUTPUT
     # Build the plugin
     - name: Build
       id: build
@@ -58,4 +86,5 @@ jobs:
           styles.css
         name: ${{ steps.version.outputs.tag }}
         tag_name: ${{ steps.version.outputs.tag }}
-        draft: true
+        draft: ${{ steps.version.outputs.draft }}
+        prerelease: ${{ steps.version.outputs.prerelease }}

.github/workflows/unit-ci.yml

@@ -17,6 +17,13 @@ on:
       - 'vitest.config*.ts'
       - 'esbuild.config.mjs'
       - 'eslint.config.mjs'
+      - 'update-workspaces.mjs'
+      - 'version-bump.mjs'
+      - 'utils/release-*.mjs'
+      - 'utils/release-*.unit.spec.ts'
+      - '.github/workflows/prepare-release.yml'
+      - '.github/workflows/finalise-release.yml'
+      - '.github/workflows/release.yml'
       - '.github/workflows/unit-ci.yml'
   pull_request:
     paths:
@@ -29,6 +36,13 @@ on:
       - 'vitest.config*.ts'
       - 'esbuild.config.mjs'
       - 'eslint.config.mjs'
+      - 'update-workspaces.mjs'
+      - 'version-bump.mjs'
+      - 'utils/release-*.mjs'
+      - 'utils/release-*.unit.spec.ts'
+      - '.github/workflows/prepare-release.yml'
+      - '.github/workflows/finalise-release.yml'
+      - '.github/workflows/release.yml'
       - '.github/workflows/unit-ci.yml'
 
 permissions:
@@ -113,4 +127,4 @@ jobs:
         if: always()
         run: |
           npm run test:docker-couchdb:stop || true
-          npm run test:docker-s3:stop || true
+          npm run test:docker-s3:stop || true