update-docs.yml

name: Update docs
on:
  push:
    paths:
      - "**/*.tf"
      - "**/*.md"
      - ".github/workflows/update-docs.yml"

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  docs:
    name: Auto update terraform docs
    runs-on: ubuntu-latest
    permissions:
      contents: write # for terraform-docs/gh-actions to commit documentation updates
      pull-requests: write # for peter-evans/create-pull-request to create PRs with doc updates
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
        with:
          egress-policy: audit

      - name: Checkout with GITHUB Action token
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          persist-credentials: true

      - name: Generate TF docs
        if: github.repository_owner == 'github-aws-runners'
        uses: terraform-docs/gh-actions@6de6da0cefcc6b4b7a5cbea4d79d97060733093c # v1.4.1
        with:
          find-dir: .
          git-push: false

      # commit via the GitHub API so commits are signed by GitHub and show as verified
      - name: Commit and push docs changes (branches only)
        if: github.ref != 'refs/heads/main' && github.repository_owner == 'github-aws-runners'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          COMMIT_MESSAGE: "docs: auto update terraform docs"
        run: |
          set -o pipefail
          # diff against HEAD because terraform-docs stages the files it updates
          if git diff --quiet HEAD; then
            echo "No documentation changes to commit."
            exit 0
          fi
          echo "Committing documentation changes:"
          git diff --name-only HEAD
          # pass file contents through a temp file to avoid the kernel's argument size limit
          additions=$(mktemp)
          git diff --name-only HEAD | while IFS= read -r file; do
            jq -n --arg path "$file" --rawfile contents <(base64 -w0 "$file") '{path: $path, contents: $contents}'
          done | jq -s '.' > "$additions"
          jq -n \
            --arg repository "$GITHUB_REPOSITORY" \
            --arg branch "$GITHUB_REF_NAME" \
            --arg expectedHeadOid "$(git rev-parse HEAD)" \
            --arg message "$COMMIT_MESSAGE" \
            --slurpfile additions "$additions" \
            '{
              query: "mutation ($input: CreateCommitOnBranchInput!) { createCommitOnBranch(input: $input) { commit { oid } } }",
              variables: {
                input: {
                  branch: { repositoryNameWithOwner: $repository, branchName: $branch },
                  expectedHeadOid: $expectedHeadOid,
                  message: { headline: $message },
                  fileChanges: { additions: $additions[0] }
                }
              }
            }' | gh api graphql --input -

      - name: Generate TF docs (forks)
        if: github.repository_owner != 'github-aws-runners'
        uses: terraform-docs/gh-actions@6de6da0cefcc6b4b7a5cbea4d79d97060733093c # v1.4.1
        with:
          find-dir: .
          git-commit-message: "docs: auto update terraform docs"
          git-push: ${{ github.ref != 'refs/heads/main' || github.repository_owner != 'github-aws-runners' }}

      # change docs via PR in case of locked main branch
      - name: Create Pull Request (main branch only)
        if: github.ref == 'refs/heads/main' && github.repository_owner == 'github-aws-runners'
        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          sign-commits: true
          commit-message: "docs: auto update terraform docs"
          title: "docs: Update Terraform docs"
          branch: update-docs
          branch-suffix: random
          base: ${{ github.event.pull_request.base.ref }}
          delete-branch: true

  deploy-pages:
    name: Deploy documentation to GitHub Pages
    needs: [docs]
    runs-on: ubuntu-latest
    permissions:
      contents: write # for actions/checkout and mkdocs gh-deploy to push to gh-pages branch
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
        with:
          egress-policy: audit

      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          # mkdocs gh-deploy invokes `git push` internally via ghp-import, which relies on
          # the credentials persisted by actions/checkout to authenticate against gh-pages.
          persist-credentials: true
      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
      - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install --require-hashes -r .github/workflows/mkdocs/requirements.txt
      - name: Build and deploy docs (main branch)
        if: github.ref == 'refs/heads/main'
        run: mkdocs gh-deploy --force -c -b gh-pages
      - name: Build docs only (other branches)
        if: github.ref != 'refs/heads/main'
        run: mkdocs build