update-api-spec.yml

name: Update API Specification

on:
  schedule:
    # Run weekdays at 02:00 UTC
    - cron: '0 2 * * 1-5'
  workflow_dispatch: # Allow manual triggering

concurrency:
  group: update-api-spec
  cancel-in-progress: false

jobs:
  update-api-spec:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    permissions:
      contents: write
      pull-requests: write

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

    - name: Set up Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'

    - name: Install dependencies
      run: |
        npm install -g swagger2openapi
        npm install -g mintlify

    - name: Configure git
      run: |
        git config user.name "API Spec Updater"
        git config user.email "noreply@checkly.com"

    - name: Ensure labels exist
      env:
        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: |
        gh label create "auto-generated" --color "0e8a16" --description "Automatically generated PR" --force
        gh label create "api-docs" --color "1d76db" --description "API documentation changes" --force

    - name: Fetch latest API specification
      run: ./update-api-spec.sh

    - name: Generate pages for any new endpoints
      run: node .github/scripts/detect-new-endpoints.mjs

    - name: Create or update API spec PR if anything changed
      env:
        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: |
        set -euo pipefail

        # Stage everything that might have changed
        git add api-reference docs.json

        if git diff --cached --quiet; then
          echo "✅ No changes — nothing to do"
          exit 0
        fi

        # Summarise the diff for the commit/PR body
        SPEC_CHANGED=0
        if git diff --cached --name-only | grep -q '^api-reference/openapi\.json$'; then
          SPEC_CHANGED=1
        fi
        NEW_PAGES=$(git diff --cached --name-only --diff-filter=A | grep -c '^api-reference/.*\.mdx$' || true)
        DOCS_JSON_CHANGED=0
        if git diff --cached --name-only | grep -q '^docs\.json$'; then
          DOCS_JSON_CHANGED=1
        fi

        # Title reflects what actually changed
        if [ "$SPEC_CHANGED" = "1" ] && [ "$NEW_PAGES" -gt 0 ]; then
          TITLE="chore(api): update API spec and add $NEW_PAGES new endpoint page(s)"
        elif [ "$SPEC_CHANGED" = "1" ]; then
          TITLE="chore(api): update API specification"
        elif [ "$NEW_PAGES" -gt 0 ]; then
          TITLE="docs(api): add $NEW_PAGES new endpoint page(s)"
        else
          TITLE="chore(api): refresh API reference"
        fi

        BRANCH="auto/update-api-spec"
        git checkout -B "$BRANCH"

        git commit -m "$TITLE" \
                   -m "Automatically fetched from https://api.checklyhq.com/openapi.json" \
                   -m "Updated on $(date -u '+%Y-%m-%d %H:%M:%S UTC')"
        git push --force-with-lease origin "$BRANCH"

        # Build PR body
        BODY_FILE=$(mktemp)
        {
          echo "Auto-generated from the API spec sync workflow."
          echo ""
          echo "- Spec changed: $([ "$SPEC_CHANGED" = "1" ] && echo yes || echo no)"
          echo "- New endpoint pages: $NEW_PAGES"
          echo "- \`docs.json\` updated: $([ "$DOCS_JSON_CHANGED" = "1" ] && echo yes || echo no)"
          echo ""
          echo "This PR reuses the \`$BRANCH\` branch so future runs update this PR instead of opening duplicates."
          echo ""
          echo "---"
          echo "_Run: [${{ github.run_id }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})_"
        } > "$BODY_FILE"

        PR_URL=$(gh pr list \
          --base main \
          --head "$BRANCH" \
          --state open \
          --json url \
          --jq '.[0].url // ""')

        if [ -n "$PR_URL" ]; then
          gh pr edit "$PR_URL" \
            --title "$TITLE" \
            --body-file "$BODY_FILE" \
            --add-label auto-generated \
            --add-label api-docs
          echo "Updated $PR_URL"
        else
          PR_URL=$(gh pr create \
            --title "$TITLE" \
            --body-file "$BODY_FILE" \
            --base main \
            --head "$BRANCH" \
            --label auto-generated \
            --label api-docs)
          echo "Created $PR_URL"
        fi

        # Try to enable auto-merge, but do not create another PR if GitHub
        # requires manual approval before pull_request workflows can run.
        if ! gh pr merge "$PR_URL" --squash --auto --delete-branch; then
          echo "::notice::Could not enable auto-merge for $PR_URL. The stable branch will be updated by the next run instead of opening another PR."
        fi

    - name: Ping Checkly
      if: always()
      run: curl -fsS --retry 3 https://ping.checklyhq.com/ad576f21-3f3e-4a6a-b8e4-67fd0f6ed92d