ci: Extract docs versioning and release into reusable workflows

.github/workflows/manual_regenerate_models.yaml

@@ -46,13 +46,15 @@ jobs:
     steps:
       - name: Validate inputs
         if: inputs.docs_pr_number || inputs.docs_workflow_run_id
+        env:
+          DOCS_WORKFLOW_RUN_ID: ${{ inputs.docs_workflow_run_id }}
         run: |
           if [[ -n "$DOCS_PR_NUMBER" ]] && ! [[ "$DOCS_PR_NUMBER" =~ ^[1-9][0-9]*$ ]]; then
             echo "::error::docs_pr_number must be a positive integer, got: $DOCS_PR_NUMBER"
             exit 1
           fi
-          if [[ -n "${{ inputs.docs_workflow_run_id }}" ]] && ! [[ "${{ inputs.docs_workflow_run_id }}" =~ ^[0-9]+$ ]]; then
-            echo "::error::docs_workflow_run_id must be a numeric run ID, got: ${{ inputs.docs_workflow_run_id }}"
+          if [[ -n "$DOCS_WORKFLOW_RUN_ID" ]] && ! [[ "$DOCS_WORKFLOW_RUN_ID" =~ ^[0-9]+$ ]]; then
+            echo "::error::docs_workflow_run_id must be a numeric run ID, got: $DOCS_WORKFLOW_RUN_ID"
             exit 1
           fi
 
@@ -173,5 +175,5 @@ jobs:
         run: |
           gh pr comment "$DOCS_PR_NUMBER" \
             --repo apify/apify-docs \
-            --body "Python client model regeneration failed. [See workflow run](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})." \
+            --body "Python client model regeneration failed. [See workflow run](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID})." \
             || echo "Warning: Failed to post failure comment to apify/apify-docs PR #$DOCS_PR_NUMBER."

.github/workflows/_release_docs.yaml → .github/workflows/manual_release_docs.yaml

@@ -1,24 +1,30 @@
-name: Doc release
+name: Release docs
 
 on:
   # Runs when manually triggered from the GitHub UI.
   workflow_dispatch:
+    inputs:
+      ref:
+        description: Git ref to checkout (branch, tag, or SHA). Defaults to the default branch.
+        required: false
+        type: string
+        default: ""
 
   # Runs when invoked by another workflow.
   workflow_call:
     inputs:
       ref:
+        description: Git ref to checkout (branch, tag, or SHA)
         required: true
         type: string
 
 env:
   NODE_VERSION: 22
   PYTHON_VERSION: 3.14
-  CHECKOUT_REF: ${{ github.event_name == 'workflow_call' && inputs.ref || github.ref }}
 
 jobs:
   release_docs:
-    name: Doc release
+    name: Release docs
     environment:
       name: github-pages
     permissions:
@@ -28,11 +34,20 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+      - name: Determine checkout ref
+        id: resolve_ref
+        env:
+          INPUT_REF: ${{ inputs.ref }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          REF="${INPUT_REF:-$DEFAULT_BRANCH}"
+          echo "ref=$REF" >> "$GITHUB_OUTPUT"
+
       - name: Checkout repository
         uses: actions/checkout@v6
         with:
           token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
-          ref: ${{ env.CHECKOUT_REF }}
+          ref: ${{ steps.resolve_ref.outputs.ref }}
 
       - name: Set up Node
         uses: actions/setup-node@v6

.github/workflows/manual_release_stable.yaml

@@ -105,62 +105,12 @@ jobs:
   version_docs:
     name: Version docs
     needs: [release_prepare, changelog_update, pypi_publish]
-    runs-on: ubuntu-latest
     permissions:
       contents: write
-    env:
-      NODE_VERSION: 22
-      PYTHON_VERSION: 3.14
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v6
-        with:
-          ref: ${{ github.event.repository.default_branch }}
-          token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
-
-      - name: Set up Node
-        uses: actions/setup-node@v6
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-
-      - name: Set up uv package manager
-        uses: astral-sh/setup-uv@v7
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-
-      - name: Install Python dependencies
-        run: uv run poe install-dev
-
-      - name: Install website dependencies
-        run: |
-          cd website
-          yarn install
-
-      - name: Snapshot the current version
-        run: |
-          cd website
-          VERSION="$(python -c "import tomllib, pathlib; print(tomllib.loads(pathlib.Path('../pyproject.toml').read_text())['project']['version'])")"
-          MAJOR_MINOR="$(echo "$VERSION" | cut -d. -f1-2)"
-          export MAJOR_MINOR
-          rm -rf "versioned_docs/version-${MAJOR_MINOR}"
-          rm -rf "versioned_sidebars/version-${MAJOR_MINOR}-sidebars.json"
-          jq 'map(select(. != env.MAJOR_MINOR))' versions.json > tmp.json && mv tmp.json versions.json
-          bash build_api_reference.sh
-          npx docusaurus docs:version "$MAJOR_MINOR"
-          npx docusaurus api:version "$MAJOR_MINOR"
-
-      - name: Commit and push the version snapshot
-        uses: EndBug/add-and-commit@v10
-        with:
-          author_name: Apify Release Bot
-          author_email: noreply@apify.com
-          message: "docs: update versioned docs for ${{ needs.release_prepare.outputs.version_number }}"
+    uses: ./.github/workflows/manual_version_docs.yaml
+    with:
+      ref: ${{ needs.changelog_update.outputs.changelog_commitish }}
+    secrets: inherit
 
   doc_release:
     name: Doc release
@@ -169,8 +119,8 @@ jobs:
       contents: write
       pages: write
       id-token: write
-    uses: ./.github/workflows/_release_docs.yaml
+    uses: ./.github/workflows/manual_release_docs.yaml
     with:
-      # Use the default branch to include both the changelog update and the versioned docs snapshot.
-      ref: ${{ github.event.repository.default_branch }}
+      # Use the version_docs commit to include both changelog and versioned docs.
+      ref: ${{ needs.version_docs.outputs.version_docs_commitish }}
     secrets: inherit

.github/workflows/manual_version_docs.yaml

@@ -0,0 +1,132 @@
+name: Version docs
+
+on:
+  # Runs when manually triggered from the GitHub UI.
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: Git ref to checkout (branch, tag, or SHA). Defaults to the default branch.
+        required: false
+        type: string
+        default: ""
+
+  # Runs when invoked by another workflow.
+  workflow_call:
+    inputs:
+      ref:
+        description: Git ref to checkout (branch, tag, or SHA)
+        required: true
+        type: string
+    outputs:
+      version_docs_commitish:
+        description: The commit SHA of the versioned docs commit
+        value: ${{ jobs.version_docs.outputs.version_docs_commitish }}
+
+concurrency:
+  group: version-docs
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+env:
+  NODE_VERSION: "22"
+  PYTHON_VERSION: "3.14"
+
+jobs:
+  version_docs:
+    name: Version docs
+    runs-on: ubuntu-latest
+    outputs:
+      version_docs_commitish: ${{ steps.resolve_commitish.outputs.commitish }}
+    permissions:
+      contents: write
+
+    steps:
+      - name: Determine checkout ref
+        id: resolve_ref
+        env:
+          INPUT_REF: ${{ inputs.ref }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          REF="${INPUT_REF:-$DEFAULT_BRANCH}"
+          echo "ref=$REF" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
+          ref: ${{ steps.resolve_ref.outputs.ref }}
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Set up uv package manager
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install Python dependencies
+        run: uv run poe install-dev
+
+      - name: Snapshot the current version
+        id: snapshot
+        run: |
+          cd website
+          corepack enable
+          yarn install
+
+          # Extract version from pyproject.toml.
+          FULL_VERSION="$(uv version --short)"
+          MAJOR_MINOR_VERSION="$(echo "$FULL_VERSION" | cut -d. -f1-2)"
+          MAJOR_VERSION="$(echo "$FULL_VERSION" | cut -d. -f1)"
+          echo "version=$FULL_VERSION" >> "$GITHUB_OUTPUT"
+          echo "Version: $FULL_VERSION, Major.Minor: $MAJOR_MINOR_VERSION, Major: $MAJOR_VERSION"
+
+          # Find the existing versions for this major in versions.json (if any).
+          if [[ -f versions.json ]]; then
+            OLD_VERSIONS="$(jq -r --arg major "$MAJOR_VERSION" '.[] | select(startswith($major + "."))' versions.json)"
+          else
+            OLD_VERSIONS=""
+            echo "[]" > versions.json
+          fi
+
+          # Remove all old versions for this major (if found).
+          if [[ -n "$OLD_VERSIONS" ]]; then
+            while IFS= read -r OLD_VERSION; do
+              [[ -z "$OLD_VERSION" ]] && continue
+              echo "Removing old version $OLD_VERSION for major $MAJOR_VERSION"
+              rm -rf "versioned_docs/version-${OLD_VERSION}"
+              rm -f "versioned_sidebars/version-${OLD_VERSION}-sidebars.json"
+            done <<< "$OLD_VERSIONS"
+            jq --arg major "$MAJOR_VERSION" 'map(select(startswith($major + ".") | not))' versions.json > tmp.json && mv tmp.json versions.json
+          else
+            echo "No existing versions found for major $MAJOR_VERSION, nothing to remove"
+          fi
+
+          # Build API reference and create Docusaurus version snapshots.
+          bash build_api_reference.sh
+          uv run npx docusaurus docs:version "$MAJOR_MINOR_VERSION"
+          uv run npx docusaurus api:version "$MAJOR_MINOR_VERSION"
+
+      - name: Commit and push versioned docs
+        id: commit_versioned_docs
+        uses: EndBug/add-and-commit@v10
+        with:
+          add: website/versioned_docs website/versioned_sidebars website/versions.json
+          message: "docs: Version docs for v${{ steps.snapshot.outputs.version }} [skip ci]"
+          default_author: github_actions
+
+      - name: Resolve output commitish
+        id: resolve_commitish
+        env:
+          COMMIT_SHA: ${{ steps.commit_versioned_docs.outputs.commit_long_sha }}
+        run: |
+          echo "commitish=${COMMIT_SHA:-$(git rev-parse HEAD)}" >> "$GITHUB_OUTPUT"

.github/workflows/on_master.yaml

@@ -28,7 +28,7 @@ jobs:
       contents: write
       pages: write
       id-token: write
-    uses: ./.github/workflows/_release_docs.yaml
+    uses: ./.github/workflows/manual_release_docs.yaml
     with:
       # Use the same ref as the one that triggered the workflow.
       ref: ${{ github.ref }}
@@ -112,7 +112,7 @@ jobs:
       contents: write
       pages: write
       id-token: write
-    uses: ./.github/workflows/_release_docs.yaml
+    uses: ./.github/workflows/manual_release_docs.yaml
     with:
       # Use the ref from the changelog update to include the updated changelog.
       ref: ${{ needs.changelog_update.outputs.changelog_commitish }}

.gitignore

@@ -64,6 +64,7 @@ Session.vim
 # Docs
 docs/changelog.md
 website/versioned_docs/*/changelog.md
+website/versioned_docs/*/pyproject.toml
 
 # Website build artifacts, node dependencies
 website/build