Final polishment

Author: vdusek

.github/workflows/manual_release_docs.yaml

@@ -3,18 +3,12 @@ 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)
+        description: Git ref to checkout.
         required: true
         type: string
 
@@ -37,20 +31,11 @@ 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: ${{ steps.resolve_ref.outputs.ref }}
+          ref: ${{ inputs.ref || github.event.repository.default_branch }}
 
       - name: Set up Node
         uses: actions/setup-node@v6
@@ -79,7 +64,7 @@ jobs:
           add: website/package.json website/yarn.lock
           message: "chore: Automatic docs theme update [skip ci]"
           default_author: github_actions
-          # Required: checkout may leave a detached HEAD when invoked with a SHA ref.
+          # `actions/checkout` detaches HEAD on SHA refs; EndBug needs a branch to push.
           new_branch: ${{ github.event.repository.default_branch }}
 
       - name: Build docs

.github/workflows/manual_release_stable.yaml

@@ -98,7 +98,7 @@ jobs:
           version_number: ${{ needs.release_prepare.outputs.version_number }}
           ref: ${{ needs.changelog_update.outputs.changelog_commitish }}
 
-      # Publishes the package to PyPI using PyPA official GitHub action with OIDC authentication.
+      # Publish the package to PyPI using PyPA official GitHub action with OIDC authentication.
       - name: Publish package to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
 
@@ -109,6 +109,7 @@ jobs:
       contents: write
     uses: ./.github/workflows/manual_version_docs.yaml
     with:
+      # Commit the version docs changes on top of the changelog commit.
       ref: ${{ needs.changelog_update.outputs.changelog_commitish }}
     secrets: inherit
 
@@ -121,7 +122,7 @@ jobs:
       id-token: write
     uses: ./.github/workflows/manual_release_docs.yaml
     with:
-      # Use the version_docs commit to include both changelog and versioned docs.
+      # Commit the docs release changes on top of the version docs commit.
       ref: ${{ needs.version_docs.outputs.version_docs_commitish }}
     secrets: inherit
 

.github/workflows/manual_version_docs.yaml

@@ -3,23 +3,17 @@ 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)
+        description: Git ref to checkout.
         required: true
         type: string
     outputs:
       version_docs_commitish:
-        description: The commit SHA of the versioned docs commit
+        description: The commit SHA of the versioned docs commit.
         value: ${{ jobs.version_docs.outputs.version_docs_commitish }}
 
 concurrency:
@@ -43,20 +37,11 @@ jobs:
       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 }}
+          ref: ${{ inputs.ref || github.event.repository.default_branch }}
 
       - name: Set up Node
         uses: actions/setup-node@v6
@@ -123,7 +108,7 @@ jobs:
           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
-          # Required: checkout may leave a detached HEAD when invoked with a SHA ref.
+          # `actions/checkout` detaches HEAD on SHA refs; EndBug needs a branch to push.
           new_branch: ${{ github.event.repository.default_branch }}
 
       - name: Resolve output commitish