chore: additional release automation (#9231)

* chore: add additional automated release capabilities

* "publish: stash of uncommitted changes by release script"

* beta script

* remove emtpy file

* update beta publishing

* "publish: stash of uncommitted changes by release script"

* update scripts

* update documentation

.github/workflows/release/promote-lts.yml

@@ -0,0 +1,54 @@
+name: Promote LTS Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'The existing version to promote (e.g. `4.0.0`)'
+        type: string
+      channel:
+        description: 'The NPM Distribution Tag (e.g. `lts` or `lts-4-8`)'
+        type: string
+      update-branch:
+        description: 'Whether to update the associated LTS branch to the same commit as the tag'
+        default: true
+        type: boolean
+
+env:
+  TURBO_API: http://127.0.0.1:9080
+  TURBO_TOKEN: this-is-not-a-secret
+  TURBO_TEAM: myself
+
+jobs:
+  release:
+    name: Run Release Script
+    runs-on: ubuntu-latest
+    environment: deployment
+    steps:
+      - name: Enforce Branch
+        # Note: we always checkout main in actions/checkout, but this enforces
+        # good hygiene.
+        if: github.ref != 'refs/heads/main'
+        run: |
+          echo "Releases may only be performed from the main branch."
+          exit 1
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+        with:
+          fetch-depth: 1
+          fetch-tags: true
+          progress: false
+          token: ${{ secrets.GH_DEPLOY_TOKEN }}
+      - uses: ./.github/actions/setup
+        with:
+          install: true
+          repo-token: ${{ secrets.GH_DEPLOY_TOKEN }}
+      - name: Make sure git user is setup
+        run: |
+          git config --local user.email ${{ secrets.GH_DEPLOY_EMAIL }}
+          git config --local user.name ${{ secrets.GH_DEPLOY_NAME }}
+      - name: Publish with script
+        run: bun release exec promote --v=${{ github.event.inputs.version }} --t=${{ github.event.inputs.channel }} -u ${{ github.event.inputs.update-branch }}
+        env:
+          FORCE_COLOR: 2
+          CI: true
+          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

.github/workflows/release/publish-beta.yml

@@ -0,0 +1,93 @@
+name: Publish Beta Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      # This input is used to determine whether to start/continue a beta-cycle vs mirror from canary.
+      #
+      # A beta-cycle "forks" from canary. It starts by updating the beta branch to the current state
+      # of main (canary). Thereafter any updates to the beta branch are cherry-picked from main or PR'd
+      # to the beta branch.
+      #
+      # The (default) mirror approach instead directly copies the canary release to the beta branch
+      # each time. This is useful when the changes in canary are relatively minor or safe to release
+      # and
+      # and then publishing a beta release. A mirror is a direct copy of the canary release.
+      kind:
+        description: 'Whether to start/continue a beta-cycle vs mirror from canary'
+        required: true
+        default: 'mirror'
+        type: choice
+        options:
+        - beta-cycle  # start or continue a beta-cycle.
+        - mirror      # mirror code from canary. This is the default.
+      # At cycle start we must always reset the beta branch to main.
+      is-cycle-start:
+        description: 'Whether this is the start of a new release cycle (either kind)'
+        required: true
+        default: false
+        type: boolean
+
+env:
+  TURBO_API: http://127.0.0.1:9080
+  TURBO_TOKEN: this-is-not-a-secret
+  TURBO_TEAM: myself
+
+jobs:
+  release:
+    name: Run publish script
+    runs-on: ubuntu-latest
+    environment: deployment
+    steps:
+      - name: Enforce Branch
+        # Note: we always checkout beta in actions/checkout, but this enforces
+        # good hygiene.
+        if: github.ref != 'refs/heads/main'
+        run: |
+          echo "Releases may only be performed from the main branch."
+          exit 1
+      - name: Make sure git user is setup
+        run: |
+          git config --local user.email ${{ secrets.GH_DEPLOY_EMAIL }}
+          git config --local user.name ${{ secrets.GH_DEPLOY_NAME }}
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+        with:
+          fetch-tags: true
+          progress: false
+          token: ${{ secrets.GH_DEPLOY_TOKEN }}
+          fetch-depth: 3
+          ref: beta
+      - run: git fetch origin main --depth=1
+      - name: Get last beta version from package.json
+        if: github.event.inputs.kind == 'mirror'
+        uses: sergeysova/jq-action@v2
+        id: version
+        with:
+          cmd: 'jq .version package.json -r'
+      - name: Reset the Beta Branch
+        if: github.event.inputs.kind == 'mirror' || github.event.inputs.is-cycle-start == 'true'
+        run: git reset --hard origin/main && git push origin beta -f
+      - uses: ./.github/actions/setup
+        with:
+          install: true
+          repo-token: ${{ secrets.GH_DEPLOY_TOKEN }}
+      - name: Publish New Release
+        # For beta-cycle we always increment from the branch state
+        # For mirror we increment from the last beta version, unless it's start of a new cycle.
+        if: github.event.inputs.kind == 'beta-cycle' || github.event.inputs.is-cycle-start == 'true'
+        run: bun release exec publish beta
+        env:
+          FORCE_COLOR: 2
+          CI: true
+          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
+      - name: Publish New Mirror Release
+        if: github.event.inputs.kind == 'mirror'
+        run: bun release exec publish beta --from=${{ steps.version.outputs.stdout }}
+        env:
+          FORCE_COLOR: 2
+          CI: true
+          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: tarballs
+          path: tmp/tarballs/**/*.tgz

.github/workflows/alpha-release.yml → .github/workflows/release/publish-canary.yml

@@ -1,4 +1,4 @@
-name: Alpha Releases
+name: Publish Canary Release
 
 on:
   workflow_dispatch:
@@ -27,12 +27,20 @@ jobs:
     runs-on: ubuntu-latest
     environment: deployment
     steps:
+      - name: Enforce Branch
+        # Note: we always checkout main in actions/checkout, but this enforces
+        # good hygiene.
+        if: github.ref != 'refs/heads/main'
+        run: |
+          echo "Releases may only be performed from the main branch."
+          exit 1
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
         with:
           fetch-depth: 1
           fetch-tags: true
           progress: false
           token: ${{ secrets.GH_DEPLOY_TOKEN }}
+          ref: main
       - name: Check should run if HEAD is untagged
         run: |
           echo "HEAD is $(git name-rev --tags --name-only $(git rev-parse HEAD))"
@@ -48,7 +56,7 @@ jobs:
           git config --local user.email ${{ secrets.GH_DEPLOY_EMAIL }}
           git config --local user.name ${{ secrets.GH_DEPLOY_NAME }}
       - name: Publish with script
-        run: bun run publish canary -i ${{ github.event.inputs.increment }}
+        run: bun release canary -i ${{ github.event.inputs.increment }}
         env:
           FORCE_COLOR: 2
           CI: true

.github/workflows/release/publish-lts.yml

@@ -0,0 +1,62 @@
+name: Publish LTS Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: 'The branch to publish from, e.g. `lts-4-12`'
+        required: true
+        type: string
+      channel:
+        description: 'The NPM Distribution Tag. `lts` for current lts. `lts-prev` for e.g. `lts-4-8`'
+        type: option
+        default: 'lts'
+        required: true
+        options:
+          - lts
+          - lts-prev
+
+env:
+  TURBO_API: http://127.0.0.1:9080
+  TURBO_TOKEN: this-is-not-a-secret
+  TURBO_TEAM: myself
+
+jobs:
+  release:
+    name: Run publish script
+    runs-on: ubuntu-latest
+    environment: deployment
+    steps:
+      - name: Enforce Branch
+        # Note: we always checkout the correct lts branch in actions/checkout, but this enforces
+        # good hygiene.
+        if: github.ref != 'refs/heads/main'
+        run: |
+          echo "Releases may only be performed from the main branch."
+          exit 1
+      - name: Make sure git user is setup
+        run: |
+          git config --local user.email ${{ secrets.GH_DEPLOY_EMAIL }}
+          git config --local user.name ${{ secrets.GH_DEPLOY_NAME }}
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+        with:
+          fetch-tags: true
+          progress: false
+          token: ${{ secrets.GH_DEPLOY_TOKEN }}
+          fetch-depth: 3
+          ref: ${{ github.event.inputs.source-branch }}
+      - uses: ./.github/actions/setup
+        with:
+          install: true
+          repo-token: ${{ secrets.GH_DEPLOY_TOKEN }}
+      - name: Publish New LTS Release
+        # We always increment from the branch state
+        run: bun release publish ${{ github.event.inputs.channel }}
+        env:
+          FORCE_COLOR: 2
+          CI: true
+          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: tarballs
+          path: tmp/tarballs/**/*.tgz

.github/workflows/release/publish-stable.yml

@@ -0,0 +1,100 @@
+name: Publish Stable Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      source-branch:
+        description: 'If starting a new cycle, or reversioning, the source branch to update the release branch from'
+        required: false
+        default: 'beta'
+        type: choice
+        options:
+        - beta      # promotes beta to stable
+        - main      # promotes canary to stable
+        - release   # re-releases a stable version
+      # At cycle start we must always reset the release branch to beta.
+      is-cycle-start:
+        description: 'Whether this is the start of a new release cycle'
+        required: true
+        default: false
+        type: boolean
+      # downversion e.g. 5.4.0-alpha.1 => 5.3.1 happens when we use a canary, beta or later release to hotfix a stable
+      # upversion e.g. 5.3.1 => 5.4.0 happens when we re-release an existing stable as a new minor/major
+      # examples:
+      #   Upversion: 5.3.1 => 5.4.0
+      #     from-version: 5.3.1
+      #     increment: minor
+      #   Downversion: 5.4.0-alpha.1 => 5.3.1
+      #     from-version: 5.3.0
+      #     increment: patch
+      from-version:
+        description: 'When upversioning or downversioning, the version from which to increment to get the version number for the release'
+        type: string
+      increment:
+        description: 'Type of Version Bump To Perform (only used when upversioning or downversioning)'
+        required: true
+        default: 'patch'
+        type: choice
+        options:
+        - patch
+        - minor
+        - major
+
+env:
+  TURBO_API: http://127.0.0.1:9080
+  TURBO_TOKEN: this-is-not-a-secret
+  TURBO_TEAM: myself
+
+jobs:
+  release:
+    name: Perform Release
+    runs-on: ubuntu-latest
+    environment: deployment
+    steps:
+      - name: Enforce Branch
+        # Note: we always checkout release in actions/checkout, but this enforces
+        # good hygiene.
+        if: github.ref != 'refs/heads/main'
+        run: |
+          echo "Releases may only be performed from the main branch."
+          exit 1
+      - name: Make sure git user is setup
+        run: |
+          git config --local user.email ${{ secrets.GH_DEPLOY_EMAIL }}
+          git config --local user.name ${{ secrets.GH_DEPLOY_NAME }}
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+        with:
+          fetch-tags: true
+          progress: false
+          token: ${{ secrets.GH_DEPLOY_TOKEN }}
+          fetch-depth: 3
+          ref: release
+      ## Ensure we have a copy of the source branch
+      - run: git fetch origin ${{ github.event.inputs.source-branch }} --depth=1
+      - name: Reset the Release Branch
+        if: github.event.inputs.source-branch != 'release' && (github.event.inputs.is-cycle-start == 'true' || github.event.inputs.from-version != null)
+        run: git reset --hard origin/${{ github.event.inputs.source-branch }} && git push origin release -f
+      - uses: ./.github/actions/setup
+        with:
+          install: true
+          repo-token: ${{ secrets.GH_DEPLOY_TOKEN }}
+      - name: Publish New Release
+        # If we are not reversioning
+        # Then we do the default patch increment from the current branch state.
+        # This handles both start-of-cycle and bugfix releases.
+        if: github.event.inputs.from-version == null
+        run: bun release publish release
+        env:
+          FORCE_COLOR: 2
+          CI: true
+          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
+      - name: Publish New Release (Reversion)
+        # If we are reversioning
+        # Then we increment from the branch with the supplied increment
+        # This handles both upversioning and downversioning
+        if: github.event.inputs.from-version != null
+        run: bun release publish release --from=${{ github.event.inputs.from-version }} --increment=${{ github.event.inputs.increment }}
+        env:
+          FORCE_COLOR: 2
+          CI: true
+          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}