ci: Fix docs release failing on detached HEAD (#1851)

## Summary

`actions/checkout` detaches HEAD when checking out a SHA, which blocks
`EndBug/add-and-commit` from pushing the versioned docs commit. Pass
`new_branch` so the action pushes to the default branch, and tighten the
trigger contract so `ref` is only required for `workflow_call` (for
`workflow_dispatch` the default branch is always used).

Mirrors apify/apify-client-python#741 and the equivalent fix in
apify-sdk-python.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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

.github/workflows/manual_release_stable.yaml

@@ -97,7 +97,7 @@ jobs:
           is_prerelease: ""
           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
 
@@ -111,6 +111,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
 
@@ -123,6 +124,6 @@ jobs:
       id-token: write
     uses: ./.github/workflows/manual_release_docs.yaml
     with:
-      # Use the version_docs commit to include both changelog and versioned docs.
+      # Use the commit with the version docs changes as the source for the release docs.
       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,6 +108,8 @@ 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
+          # `actions/checkout` detaches HEAD on SHA refs; EndBug needs a branch to push.
+          new_branch: ${{ github.event.repository.default_branch }}
 
       - name: Resolve output commitish
         id: resolve_commitish