docs.yml

# A GitHub Actions workflow that generates the documentation for pull requests

name: Documentation

on:
  push:

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: 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

      - name: Prepare
        uses: ./.github/actions/prepare

      - name: Build
        run: npm run build

      - name: Generate docs
        run: npm run docs

      - name: Commit docs
        uses: EndBug/add-and-commit@v9
        # We don't want to commit documentation changes to main
        if: ${{ github.ref != 'refs/heads/main' }}
        with:
          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