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 other workflows after committing docs changes, we need
    # to use the PR Automation App. This token is not available for external
    # users. So on PRs that can't access the secret, 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.PR_AUTOMATION_BOT_PUBLIC_PRIVATE_KEY != '' && github.event_name == 'pull_request' }}" >> $GITHUB_OUTPUT

      - name: Create GitHub App Token
        uses: actions/create-github-app-token@v1
        id: app-token
        with:
          app-id: ${{ vars.PR_AUTOMATION_BOT_PUBLIC_APP_ID }}
          private-key: ${{ secrets.PR_AUTOMATION_BOT_PUBLIC_PRIVATE_KEY }}

      - 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: ${{ steps.app-token.outputs.token }}
      - 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:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'

      - name: Install latest npm
        run: npm install -g npm@latest

      - name: Install dependencies
        run: npm ci

      - 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 GitHub App
        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 GitHub App Secret isn't available or this isn't a pull request."
          exit 1