From fec7adef2fe1b64899b48e58053d2c131bd6c8a4 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Sat, 10 Oct 2026 14:42:07 -0700 Subject: [PATCH 1/9] ci: add RTD release workflow --- .github/workflows/release-docs.yaml | 90 +++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 .github/workflows/release-docs.yaml diff --git a/.github/workflows/release-docs.yaml b/.github/workflows/release-docs.yaml new file mode 100644 index 00000000..d2e540cd --- /dev/null +++ b/.github/workflows/release-docs.yaml @@ -0,0 +1,90 @@ +name: Documentation release +on: + push: + tags: + # These tags should be protected, remember to enable the rule: + # https://github.com/canonical/starbase/settings/tag_protection + - "[0-9]+.[0-9]+.[0-9]+" + +jobs: + docs-release: + runs-on: [self-hosted] + permissions: + contents: write + env: + RTD_PROJECT: ${{ vars.RTD_PROJECT }} + RTD_TOKEN: ${{ secrets.RTD_TOKEN }} + steps: + - name: Parse version + run: | + IFS='.' read -r MAJOR MINOR PATCH <<< "${{ github.ref_name }}" + echo "MAJOR=$MAJOR" >> "$GITHUB_ENV" + echo "MINOR=$MINOR" >> "$GITHUB_ENV" + echo "PATCH=$PATCH" >> "$GITHUB_ENV" + + if [[ $PATCH == 0 && $MINOR != 0 ]]; then + echo "IS_MINOR=true" >> "$GITHUB_ENV" + fi + + - name: Create hotfix branch + if: env.PATCH == '0' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + BRANCH="hotfix/$MAJOR.$MINOR" + SHA="${{ github.sha }}" + curl -sfX POST -H "Authorization: Token $GH_TOKEN" -H "Content-Type: application/json" \ + -d "{\"ref\":\"refs/heads/$BRANCH\",\"sha\":\"$SHA\"}" \ + "https://api.github.com/repos/${{ github.repository }}/git/refs" 2>/dev/null || \ + curl -sfX PATCH -H "Authorization: Token $GH_TOKEN" -H "Content-Type: application/json" \ + -d "{\"sha\":\"$SHA\",\"force\":true}" \ + "https://api.github.com/repos/${{ github.repository }}/git/refs/heads/$BRANCH" + + - name: Sync RTD versions + if: env.PATCH == '0' + run: | + curl \ + -fX POST \ + -H "Authorization: Token $RTD_TOKEN" \ + "https://app.readthedocs.com/api/v3/projects/$RTD_PROJECT/sync-versions/" + + - name: Manage RTD versions + if: env.PATCH == '0' + run: | + API="https://app.readthedocs.com/api/v3/projects/$RTD_PROJECT/versions" + + # For minor releases, rename and deactivate the outgoing major version + if [[ $IS_MINOR == true ]] && curl -sf -H "Authorization: Token $RTD_TOKEN" "$API/$MAJOR/" >/dev/null; then + PREV_MINOR=$((MINOR - 1)) + curl -fX PATCH \ + -H "Authorization: Token $RTD_TOKEN" -H "Content-Type: application/json" \ + -d "{\"slug\": \"$MAJOR.$PREV_MINOR\", \"active\": false}" \ + "$API/$MAJOR/" + fi + + # Update new version slug to major and activate + curl -fsS --retry 10 --retry-delay 6 --retry-all-errors -X PATCH \ + -H "Authorization: Token $RTD_TOKEN" -H "Content-Type: application/json" \ + -d "{\"slug\": \"$MAJOR\", \"active\": true}" \ + "$API/hotfix-$MAJOR.$MINOR/" + + - name: Update project default version + if: env.PATCH == '0' + run: | + curl -fX PATCH \ + -H "Authorization: Token $RTD_TOKEN" -H "Content-Type: application/json" \ + -d "{\"default_version\": \"$MAJOR\"}" \ + "https://app.readthedocs.com/api/v3/projects/$RTD_PROJECT/" + + - name: Create redirects + run: | + API="https://app.readthedocs.com/api/v3/projects/$RTD_PROJECT/redirects/" + + create_redirect() { + curl -fX POST \ + -H "Authorization: Token $RTD_TOKEN" -H "Content-Type: application/json" \ + -d "{\"from_url\": \"/$1/*\", \"to_url\": \"/$MAJOR/:splat\", \"type\": \"exact\", \"force\": true}" "$API" + } + + [[ $PATCH == 0 ]] && create_redirect "$MAJOR.$MINOR" + create_redirect "$MAJOR.$MINOR.$PATCH" From 64561a71fe0b0cd69bc7eb416da450211073948c Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Sat, 10 Oct 2026 15:03:23 -0700 Subject: [PATCH 2/9] chore: remove variable --- .github/workflows/release-docs.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/workflows/release-docs.yaml b/.github/workflows/release-docs.yaml index d2e540cd..098a7aa2 100644 --- a/.github/workflows/release-docs.yaml +++ b/.github/workflows/release-docs.yaml @@ -78,12 +78,11 @@ jobs: - name: Create redirects run: | - API="https://app.readthedocs.com/api/v3/projects/$RTD_PROJECT/redirects/" - create_redirect() { curl -fX POST \ -H "Authorization: Token $RTD_TOKEN" -H "Content-Type: application/json" \ - -d "{\"from_url\": \"/$1/*\", \"to_url\": \"/$MAJOR/:splat\", \"type\": \"exact\", \"force\": true}" "$API" + -d "{\"from_url\": \"/$1/*\", \"to_url\": \"/$MAJOR/:splat\", \"type\": \"exact\", \"force\": true}" \ + "https://app.readthedocs.com/api/v3/projects/$RTD_PROJECT/redirects/" } [[ $PATCH == 0 ]] && create_redirect "$MAJOR.$MINOR" From 9c32ab2f52a4d73472133bbbf8709ea91b2552d6 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Thu, 15 Oct 2026 14:28:17 -0700 Subject: [PATCH 3/9] fix: don't force branch creation --- .github/workflows/release-docs.yaml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/workflows/release-docs.yaml b/.github/workflows/release-docs.yaml index 098a7aa2..dd3b8eab 100644 --- a/.github/workflows/release-docs.yaml +++ b/.github/workflows/release-docs.yaml @@ -32,13 +32,13 @@ jobs: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | BRANCH="hotfix/$MAJOR.$MINOR" - SHA="${{ github.sha }}" - curl -sfX POST -H "Authorization: Token $GH_TOKEN" -H "Content-Type: application/json" \ - -d "{\"ref\":\"refs/heads/$BRANCH\",\"sha\":\"$SHA\"}" \ - "https://api.github.com/repos/${{ github.repository }}/git/refs" 2>/dev/null || \ - curl -sfX PATCH -H "Authorization: Token $GH_TOKEN" -H "Content-Type: application/json" \ - -d "{\"sha\":\"$SHA\",\"force\":true}" \ - "https://api.github.com/repos/${{ github.repository }}/git/refs/heads/$BRANCH" + API="https://api.github.com/repos/${{ github.repository }}" + + if ! curl -sf -H "Authorization: Token $GH_TOKEN" "$API/git/refs/heads/$BRANCH" >/dev/null; then + curl -fX POST -H "Authorization: Token $GH_TOKEN" -H "Content-Type: application/json" \ + -d "{\"ref\":\"refs/heads/$BRANCH\",\"sha\":\"${{ github.sha }}\"}" \ + "$API/git/refs" + fi - name: Sync RTD versions if: env.PATCH == '0' From 11669a4735d6f2365f0ccd4aebbf183f554b5c2d Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Thu, 15 Oct 2026 14:56:35 -0700 Subject: [PATCH 4/9] chore: fix actionlint warning --- .github/workflows/release-docs.yaml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/.github/workflows/release-docs.yaml b/.github/workflows/release-docs.yaml index dd3b8eab..3b9f2b84 100644 --- a/.github/workflows/release-docs.yaml +++ b/.github/workflows/release-docs.yaml @@ -18,10 +18,12 @@ jobs: - name: Parse version run: | IFS='.' read -r MAJOR MINOR PATCH <<< "${{ github.ref_name }}" - echo "MAJOR=$MAJOR" >> "$GITHUB_ENV" - echo "MINOR=$MINOR" >> "$GITHUB_ENV" - echo "PATCH=$PATCH" >> "$GITHUB_ENV" - + { + echo "MAJOR=$MAJOR" + echo "MINOR=$MINOR" + echo "PATCH=$PATCH" + } >> "$GITHUB_ENV" + if [[ $PATCH == 0 && $MINOR != 0 ]]; then echo "IS_MINOR=true" >> "$GITHUB_ENV" fi From 68fc401571d2c206a5236a650d716126d32e5cde Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Thu, 15 Oct 2026 14:59:10 -0700 Subject: [PATCH 5/9] chore: patch potential template expansion --- .github/workflows/release-docs.yaml | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/.github/workflows/release-docs.yaml b/.github/workflows/release-docs.yaml index 3b9f2b84..b7b3610a 100644 --- a/.github/workflows/release-docs.yaml +++ b/.github/workflows/release-docs.yaml @@ -16,8 +16,10 @@ jobs: RTD_TOKEN: ${{ secrets.RTD_TOKEN }} steps: - name: Parse version + env: + REF_NAME: ${{ github.ref_name }} run: | - IFS='.' read -r MAJOR MINOR PATCH <<< "${{ github.ref_name }}" + IFS='.' read -r MAJOR MINOR PATCH <<< "$REF_NAME" { echo "MAJOR=$MAJOR" echo "MINOR=$MINOR" @@ -32,13 +34,15 @@ jobs: if: env.PATCH == '0' env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REPOSITORY: ${{ github.repository }} + SHA: ${{ github.sha }} run: | BRANCH="hotfix/$MAJOR.$MINOR" - API="https://api.github.com/repos/${{ github.repository }}" + API="https://api.github.com/repos/$REPOSITORY" if ! curl -sf -H "Authorization: Token $GH_TOKEN" "$API/git/refs/heads/$BRANCH" >/dev/null; then curl -fX POST -H "Authorization: Token $GH_TOKEN" -H "Content-Type: application/json" \ - -d "{\"ref\":\"refs/heads/$BRANCH\",\"sha\":\"${{ github.sha }}\"}" \ + -d "{\"ref\":\"refs/heads/$BRANCH\",\"sha\":\"$SHA\"}" \ "$API/git/refs" fi From 68da64c012ed7baf10d4d0a4e9e215a0f8481d88 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Thu, 15 Oct 2026 15:02:11 -0700 Subject: [PATCH 6/9] chore: format workflow --- .github/workflows/release-docs.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/release-docs.yaml b/.github/workflows/release-docs.yaml index b7b3610a..4308aa11 100644 --- a/.github/workflows/release-docs.yaml +++ b/.github/workflows/release-docs.yaml @@ -58,7 +58,7 @@ jobs: if: env.PATCH == '0' run: | API="https://app.readthedocs.com/api/v3/projects/$RTD_PROJECT/versions" - + # For minor releases, rename and deactivate the outgoing major version if [[ $IS_MINOR == true ]] && curl -sf -H "Authorization: Token $RTD_TOKEN" "$API/$MAJOR/" >/dev/null; then PREV_MINOR=$((MINOR - 1)) @@ -67,7 +67,7 @@ jobs: -d "{\"slug\": \"$MAJOR.$PREV_MINOR\", \"active\": false}" \ "$API/$MAJOR/" fi - + # Update new version slug to major and activate curl -fsS --retry 10 --retry-delay 6 --retry-all-errors -X PATCH \ -H "Authorization: Token $RTD_TOKEN" -H "Content-Type: application/json" \ @@ -90,6 +90,6 @@ jobs: -d "{\"from_url\": \"/$1/*\", \"to_url\": \"/$MAJOR/:splat\", \"type\": \"exact\", \"force\": true}" \ "https://app.readthedocs.com/api/v3/projects/$RTD_PROJECT/redirects/" } - + [[ $PATCH == 0 ]] && create_redirect "$MAJOR.$MINOR" create_redirect "$MAJOR.$MINOR.$PATCH" From 74f5ad74c5726bd860e370c142f9264255d2c147 Mon Sep 17 00:00:00 2001 From: JJ Coldiron Date: Wed, 21 Oct 2026 16:24:17 -0700 Subject: [PATCH 7/9] ci: update runs-on with copilot suggestion Signed-off-by: JJ Coldiron --- .github/workflows/release-docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release-docs.yaml b/.github/workflows/release-docs.yaml index 4308aa11..3ec8c3fe 100644 --- a/.github/workflows/release-docs.yaml +++ b/.github/workflows/release-docs.yaml @@ -8,7 +8,7 @@ on: jobs: docs-release: - runs-on: [self-hosted] + runs-on: [self-hosted, medium, linux, amd64] permissions: contents: write env: From 232c24354ec92c6fe2a832223b014e557e1a8541 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Thu, 22 Oct 2026 16:26:26 -0700 Subject: [PATCH 8/9] ci: call starflow workflow --- .github/workflows/release-docs.yaml | 88 ++--------------------------- 1 file changed, 6 insertions(+), 82 deletions(-) diff --git a/.github/workflows/release-docs.yaml b/.github/workflows/release-docs.yaml index 3ec8c3fe..e4988211 100644 --- a/.github/workflows/release-docs.yaml +++ b/.github/workflows/release-docs.yaml @@ -1,4 +1,5 @@ name: Documentation release + on: push: tags: @@ -8,88 +9,11 @@ on: jobs: docs-release: - runs-on: [self-hosted, medium, linux, amd64] permissions: contents: write - env: - RTD_PROJECT: ${{ vars.RTD_PROJECT }} + uses: canonical/starflow/.github/workflows/release-docs.yaml@main + with: + # TODO: set to your Read the Docs project slug. + rtd-project: starbase + secrets: RTD_TOKEN: ${{ secrets.RTD_TOKEN }} - steps: - - name: Parse version - env: - REF_NAME: ${{ github.ref_name }} - run: | - IFS='.' read -r MAJOR MINOR PATCH <<< "$REF_NAME" - { - echo "MAJOR=$MAJOR" - echo "MINOR=$MINOR" - echo "PATCH=$PATCH" - } >> "$GITHUB_ENV" - - if [[ $PATCH == 0 && $MINOR != 0 ]]; then - echo "IS_MINOR=true" >> "$GITHUB_ENV" - fi - - - name: Create hotfix branch - if: env.PATCH == '0' - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - REPOSITORY: ${{ github.repository }} - SHA: ${{ github.sha }} - run: | - BRANCH="hotfix/$MAJOR.$MINOR" - API="https://api.github.com/repos/$REPOSITORY" - - if ! curl -sf -H "Authorization: Token $GH_TOKEN" "$API/git/refs/heads/$BRANCH" >/dev/null; then - curl -fX POST -H "Authorization: Token $GH_TOKEN" -H "Content-Type: application/json" \ - -d "{\"ref\":\"refs/heads/$BRANCH\",\"sha\":\"$SHA\"}" \ - "$API/git/refs" - fi - - - name: Sync RTD versions - if: env.PATCH == '0' - run: | - curl \ - -fX POST \ - -H "Authorization: Token $RTD_TOKEN" \ - "https://app.readthedocs.com/api/v3/projects/$RTD_PROJECT/sync-versions/" - - - name: Manage RTD versions - if: env.PATCH == '0' - run: | - API="https://app.readthedocs.com/api/v3/projects/$RTD_PROJECT/versions" - - # For minor releases, rename and deactivate the outgoing major version - if [[ $IS_MINOR == true ]] && curl -sf -H "Authorization: Token $RTD_TOKEN" "$API/$MAJOR/" >/dev/null; then - PREV_MINOR=$((MINOR - 1)) - curl -fX PATCH \ - -H "Authorization: Token $RTD_TOKEN" -H "Content-Type: application/json" \ - -d "{\"slug\": \"$MAJOR.$PREV_MINOR\", \"active\": false}" \ - "$API/$MAJOR/" - fi - - # Update new version slug to major and activate - curl -fsS --retry 10 --retry-delay 6 --retry-all-errors -X PATCH \ - -H "Authorization: Token $RTD_TOKEN" -H "Content-Type: application/json" \ - -d "{\"slug\": \"$MAJOR\", \"active\": true}" \ - "$API/hotfix-$MAJOR.$MINOR/" - - - name: Update project default version - if: env.PATCH == '0' - run: | - curl -fX PATCH \ - -H "Authorization: Token $RTD_TOKEN" -H "Content-Type: application/json" \ - -d "{\"default_version\": \"$MAJOR\"}" \ - "https://app.readthedocs.com/api/v3/projects/$RTD_PROJECT/" - - - name: Create redirects - run: | - create_redirect() { - curl -fX POST \ - -H "Authorization: Token $RTD_TOKEN" -H "Content-Type: application/json" \ - -d "{\"from_url\": \"/$1/*\", \"to_url\": \"/$MAJOR/:splat\", \"type\": \"exact\", \"force\": true}" \ - "https://app.readthedocs.com/api/v3/projects/$RTD_PROJECT/redirects/" - } - - [[ $PATCH == 0 ]] && create_redirect "$MAJOR.$MINOR" - create_redirect "$MAJOR.$MINOR.$PATCH" From 679eb2b53f8049a6dcd3529504848a2a3ba9b477 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Thu, 22 Oct 2026 16:30:49 -0700 Subject: [PATCH 9/9] chore: normalize whitespace --- .github/workflows/release-docs.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/release-docs.yaml b/.github/workflows/release-docs.yaml index e4988211..3c773409 100644 --- a/.github/workflows/release-docs.yaml +++ b/.github/workflows/release-docs.yaml @@ -1,5 +1,4 @@ name: Documentation release - on: push: tags: