code-docs.yml

# =============================================================================
# code-docs.yml — Generated Go Package Docs
#
# Runs on every push to main. Generates Go package docs via gomarkdoc and
# commits them back to docs/code/, plus uploads a retained artifact copy.
# Mirrors the environments library's own code-docs.yml.
#
# Auth:
#   Uses the BlanketOps-Environments GitHub App instead of a personal-account
#   PAT for checkout/push and private-module git config — see ci.yaml's
#   header for the reasoning.
#
#   Unlike environments' code-docs.yml, the generated-docs commit here is NOT
#   GPG-signed — this repo has no GPG_PRIVATE_KEY/GPG_PASSPHRASE secrets
#   configured, and its existing bot-authored commits (release.yml,
#   finalize-release.yml) are likewise unsigned. Add those secrets and a
#   crazy-max/ghaction-import-gpg step if signed docs commits are wanted
#   later.
#
# Secrets required:
#   APP_ID, APP_PRIVATE_KEY — GitHub App credentials
# =============================================================================

name: Code Docs

on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  godoc:
    name: Generate Code Docs
    runs-on: ubuntu-latest
    steps:
      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
          owner: blanketops
          repositories: environments-controller,environments,environments-api,environments-contract

      - name: Checkout
        uses: actions/checkout@v4
        with:
          token: ${{ steps.app-token.outputs.token }}
          fetch-depth: 0

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: false

      - name: Configure Git for private modules
        run: |
          git config --global url."https://x-access-token:${{ steps.app-token.outputs.token }}@github.com/".insteadOf "https://github.com/"
          go env -w GOPRIVATE=github.com/blanketops/*
          go env -w GONOSUMDB=github.com/blanketops/*
          go env -w GOPROXY=direct

      - name: Install gomarkdoc
        run: go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest

      - name: Generate docs
        run: |
          mkdir -p docs/code
          gomarkdoc \
            --output 'docs/code/{{.Dir}}.md' \
            ./internal/... \
            ./pkg/...

      - name: Configure git committer
        run: |
          git config user.name "github-actions"
          git config user.email "actions@github.com"

      - name: Commit and push docs
        run: |
          git add docs/code/ -f
          if ! git diff-index --quiet HEAD; then
            git commit -m "docs: auto-generate code documentation [skip ci]"
            git pull --rebase origin main
            git push origin main
          else
            echo "No documentation changes to commit"
          fi

      - name: Upload docs artifact
        uses: actions/upload-artifact@v4
        with:
          name: godoc-${{ github.sha }}
          path: docs/code/
          retention-days: 30

      - name: Build summary
        run: |
          echo "## 📚 Code Documentation" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "Generated from commit \`${{ github.sha }}\` on branch \`${{ github.ref_name }}\`." >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          for group in internal pkg; do
            files=$(find docs/code -name "*.md" | grep "/${group}" | sort)
            if [ -n "$files" ]; then
              echo "### \`${group}/\`" >> $GITHUB_STEP_SUMMARY
              echo "" >> $GITHUB_STEP_SUMMARY
              for f in $files; do
                pkg=$(basename "$f" .md)
                echo "- \`${pkg}\`" >> $GITHUB_STEP_SUMMARY
              done
              echo "" >> $GITHUB_STEP_SUMMARY
            fi
          done
          echo "> 📦 Download artifact \`godoc-${{ github.sha }}\` from the [Actions run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) to browse all generated docs." >> $GITHUB_STEP_SUMMARY