Use token to commit docs to re-trigger CLA (#685)

# Motivation

When docs changes are needed and committed onto a branch, this doesn't
retrigger CLA, making the PR stuck until another commit is added.
If we use a personal access token to checkout the code, then the CLA
will be retriggered and the PR doesn't get stuck.

# Changes

1. Use the personal access token in the docs workflow if possible.
2. If the token can't be used but docs changes are required, fail the
job.


# Tests

I deliberately broke the docs on the first commit. The docs were updated
and CLA retriggered.

# Todos

- [ ] Add entry to changelog (if necessary).
Not necessary

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

.github/workflows/docs.yml

@@ -9,9 +9,26 @@ jobs:
   docs:
     runs-on: ubuntu-20.04
 
+    # In order to trigger the CLA after committing docs changes, we need
+    # to use the GIX_CREATE_PR_PAT token. This token is not available for all
+    # users. So on PRs where the token is not available, we don't commit
+    # changes and instead just fail if the docs changes are needed.
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
+      - name: Check if commits can be added
+        id: check_can_add_commit
+        run: |
+          echo "can_add_commit=${{ secrets.GIX_CREATE_PR_PAT != '' && github.event_name == 'pull_request' }}" >> $GITHUB_OUTPUT
+
+      - name: Checkout with token
+        if: steps.check_can_add_commit.outputs.can_add_commit == 'true'
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.ref }}
+          token: ${{ secrets.GIX_CREATE_PR_PAT }}
+      - name: Checkout without token
+        if: steps.check_can_add_commit.outputs.can_add_commit == 'false'
+        uses: actions/checkout@v4
 
       - uses: actions/setup-node@v4
         with:
@@ -38,3 +55,28 @@ jobs:
           add: .
           default_author: github_actions
           message: "🤖 Documentation auto-update"
+
+      - name: Check docs changes
+        id: check_docs
+        run: |
+          if git diff --exit-code; then
+            echo "docs_needed=false" >> $GITHUB_OUTPUT
+          else
+            echo "docs_needed=true" >> $GITHUB_OUTPUT
+          fi
+      - name: Commit docs changes
+        if: steps.check_can_add_commit.outputs.can_add_commit == 'true' && steps.check_docs.outputs.docs_needed == 'true'
+        uses: EndBug/add-and-commit@v9.1.4
+        with:
+          add: .
+          default_author: github_actions
+          message: "Updating docs"
+          # do not pull: if this branch is behind, then we might as well let
+          # the pushing fail
+          pull_strategy: "NO-PULL"
+
+      - name: Fail for docs issues without personal access token
+        if: steps.check_can_add_commit.outputs.can_add_commit == 'false' && steps.check_docs.outputs.formatting_needed == 'true'
+        run: |
+          echo "Docs changes are needed but couldn't be committed because the personal access token isn't available or this isn't a pull request."
+          exit 1