audit-api-spec.yaml

name: Audit API Spec

on:
  pull_request:
    branches:
      - master
      - rel/**
  merge_group:
    types: [checks_requested]

env:
  STATIC_ANALYSIS_BOT_APP_ID: 1819979
jobs:
  generate-head-api-spec:
    name: Generate head API spec
    runs-on: ubuntu-latest
    steps:
      - name: Checkout PR
        uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 22

      - name: Cache npm dependencies
        id: node-modules-cache
        uses: actions/cache@v5
        with:
          path: |
            node_modules
            modules/*/node_modules
          key: ${{ runner.os }}-node18-${{ hashFiles('yarn.lock') }}-${{ hashFiles('tsconfig.packages.json') }}-${{ hashFiles('**/package.json') }}

      - name: Install Dependencies
        if: steps.node-modules-cache.outputs.cache-hit != 'true'
        run: yarn install --with-frozen-lockfile --ignore-scripts

      - name: Build packages
        env:
          DISABLE_V8_COMPILE_CACHE: '1'
        run: yarn run postinstall

      - name: Generate API spec
        run: |
          ./node_modules/.bin/openapi-generator \
            --codec-file modules/express/openapi-generator.rc.js \
            modules/express/src/typedRoutes/api/index.ts \
            > generated.json

      - name: Remove unknown tags from generated spec
        run: |
          jq '(.paths[] | .[]? | select(. != null)) |= del(."x-unknown-tags")' generated.json > openapi.json

      - name: Convert merged spec to YAML
        run: yq -P < openapi.json > openapi-head.yaml

      - name: Upload API spec to artifact
        uses: actions/upload-artifact@v7
        with:
          name: openapi-head.yaml
          path: openapi-head.yaml

  generate-merge-base-api-spec:
    name: Generate merge base API spec
    runs-on: ubuntu-latest
    steps:
      - name: Checkout PR
        uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          fetch-depth: 0

      - name: Find and checkout merge base
        run: |
          git fetch origin ${{ github.event.pull_request.base.ref || 'master' }}
          MERGE_BASE=$(git merge-base HEAD origin/${{ github.event.pull_request.base.ref || 'master' }})
          echo "Merge base commit: $MERGE_BASE"
          git checkout $MERGE_BASE

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 22

      - name: Cache npm dependencies
        id: node-modules-cache
        uses: actions/cache@v5
        with:
          path: |
            node_modules
            modules/*/node_modules
          key: ${{ runner.os }}-node18-${{ hashFiles('yarn.lock') }}-${{ hashFiles('tsconfig.packages.json') }}-${{ hashFiles('**/package.json') }}

      - name: Install Dependencies
        if: steps.node-modules-cache.outputs.cache-hit != 'true'
        run: yarn install --with-frozen-lockfile --ignore-scripts

      - name: Build packages
        env:
          DISABLE_V8_COMPILE_CACHE: '1'
        run: yarn run postinstall

      - name: Generate API spec
        run: |
          ./node_modules/.bin/openapi-generator \
            --codec-file modules/express/openapi-generator.rc.js \
            modules/express/src/typedRoutes/api/index.ts \
            > generated.json

      - name: Remove unknown tags from generated spec
        run: |
          jq '(.paths[] | .[]? | select(. != null)) |= del(."x-unknown-tags")' generated.json > openapi.json

      - name: Convert merged spec to YAML
        run: yq -P < openapi.json > openapi-merge-base.yaml

      - name: Upload API spec to artifact
        uses: actions/upload-artifact@v7
        with:
          name: openapi-merge-base.yaml
          path: openapi-merge-base.yaml

  check-specs-identical:
    name: Check specs identical
    runs-on: ubuntu-latest
    needs: [generate-head-api-spec, generate-merge-base-api-spec]
    outputs:
      specs-identical: ${{ steps.check-specs-identical.outputs.identical }}
    steps:
      - name: Download head API spec artifact
        uses: actions/download-artifact@v8
        with:
          name: openapi-head.yaml

      - name: Download merge base API spec artifact
        uses: actions/download-artifact@v8
        with:
          name: openapi-merge-base.yaml

      - name: Check specs identical
        id: check-specs-identical
        run: |
          if diff -q openapi-head.yaml openapi-merge-base.yaml > /dev/null 2>&1; then
            echo "identical=true" >> $GITHUB_OUTPUT
            echo "✅ Specs are identical - no changes detected, skipping subsequent checks"
          else
            echo "identical=false" >> $GITHUB_OUTPUT
            echo "📝 Specs differ - proceeding with audit checks"
          fi

  generate-vacuum-reports:
    name: Generate vacuum reports for API spec
    runs-on: ubuntu-latest
    needs: [check-specs-identical]
    if: needs.check-specs-identical.outputs.specs-identical != 'true'
    steps:
      - name: Checkout PR head for ruleset
        uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

      - name: Download head API spec artifact
        uses: actions/download-artifact@v8
        with:
          name: openapi-head.yaml

      - name: Download and install vacuum v0.18.1
        run: |
          curl -L \
            --output vacuum.tar.gz \
            --silent \
            --show-error \
            --fail \
            https://github.com/daveshanley/vacuum/releases/download/v0.18.1/vacuum_0.18.1_linux_x86_64.tar.gz
          tar -xzf vacuum.tar.gz
          chmod u+x vacuum
          sudo mv vacuum /usr/local/bin/
          vacuum version

      - name: Audit head API spec with Vacuum
        run: |
          vacuum report \
            --no-style \
            --stdout \
            --ruleset modules/express/ruleset.yaml \
            openapi-head.yaml > vacuum-report.json

          jq '.resultSet.results // []' vacuum-report.json > vacuum-results.json

          ERROR_COUNT=$(jq '[.[] | select(.ruleSeverity == "error")] | length' vacuum-results.json)
          WARNING_COUNT=$(jq '[.[] | select(.ruleSeverity == "warn")] | length' vacuum-results.json)

          echo "Found $ERROR_COUNT error(s) and $WARNING_COUNT warning(s)"

          if [ "$ERROR_COUNT" -gt 0 ]; then
            echo "API specification audit failed with $ERROR_COUNT error(s)"
            echo ""
            echo "Errors:"
            jq -r '.[] | select(.ruleSeverity == "error") | "  - [\(.ruleId)] \(.message) at \(.path)"' vacuum-results.json
            exit 1
          else
            echo "API specification audit passed!"
          fi

  check-breaking-changes:
    name: Check breaking changes
    needs: [check-specs-identical]
    if: needs.check-specs-identical.outputs.specs-identical != 'true'
    runs-on: ubuntu-latest
    steps:
      - name: Download head API spec artifact
        uses: actions/download-artifact@v8
        with:
          name: openapi-head.yaml

      - name: Download merge base API spec artifact
        uses: actions/download-artifact@v8
        with:
          name: openapi-merge-base.yaml

      - name: Create static-analysis config file
        run: |
          cat <<EOF > .static-analysis.yaml
          ---
          api_version: static-analysis.bitgo/v1alpha1

          rules:
          - path: rules/openapi/breaking-changes
            severity: error
            options:
              before_spec_path: openapi-merge-base.yaml
              after_spec_path: openapi-head.yaml
          EOF
      - name: Generate GitHub App Token
        id: generate-github-app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ env.STATIC_ANALYSIS_BOT_APP_ID }}
          private-key: ${{ secrets.STATIC_ANALYSIS_BOT_PRIVATE_KEY }}
          owner: bitgo
          repositories: |
            static-analysis

      - name: Install BitGo/static-analysis/static-analysis@v1
        uses: BitGo/install-github-release-binary@v2
        with:
          targets: BitGo/static-analysis/static-analysis@v1
          token: ${{ steps.generate-github-app-token.outputs.token }}

      - name: Check breaking changes
        run: |
          if ! static-analysis; then
            echo "
          ## ⚠️ Breaking Changes Detected

          The OpenAPI spec changes in this PR contain breaking changes that could affect API consumers.

          What to do next:
          1. Review the breaking changes in the workflow run.
          2. If these breaking changes are intentional and necessary, contact the DevEx team in #notify-dev-ex on Slack for a manual override.
          3. If not intentional, please revise your changes to maintain backward compatibility.
          "
            exit 1
          fi

  manual-linter-override:
    name: Linter Override
    needs: [check-breaking-changes]
    if: always() && needs.check-breaking-changes.result == 'failure'
    environment: breaking-changes-override
    runs-on: ubuntu-latest
    steps:
      - name: Override Breaking Changes Check
        run: |
          echo "⚠️  Manual override requested for breaking changes check"
          echo "Breaking changes check failed but was manually approved to proceed"
          echo "This override was approved by the reviewer"

  api-spec-check:
    name: API Spec Check
    needs:
      [
        generate-head-api-spec,
        generate-merge-base-api-spec,
        check-specs-identical,
        generate-vacuum-reports,
        check-breaking-changes,
        manual-linter-override,
      ]
    runs-on: ubuntu-latest
    if: always()
    steps:
      - name: Check generate-head-api-spec
        env:
          GENERATE_HEAD_API_SPEC_RESULT: ${{ needs.generate-head-api-spec.result }}
        run: |
          if [ "$GENERATE_HEAD_API_SPEC_RESULT" != "success" ]; then
            echo "❌ generate-head-api-spec: ${{ needs.generate-head-api-spec.result }}"
            exit 1
          fi
      - name: Check generate-merge-base-api-spec
        env:
          GENERATE_MERGE_BASE_API_SPEC_RESULT: ${{ needs.generate-merge-base-api-spec.result }}
        run: |
          if [ "$GENERATE_MERGE_BASE_API_SPEC_RESULT" != "success" ]; then
            echo "❌ generate-merge-base-api-spec: ${{ needs.generate-merge-base-api-spec.result }}"
            exit 1
          fi
      - name: Check generate-vacuum-reports
        env:
          GENERATE_VACUUM_REPORTS_RESULT: ${{ needs.generate-vacuum-reports.result }}
          SPECS_IDENTICAL: ${{ needs.check-specs-identical.outputs.specs-identical }}
        run: |
          if [ "$GENERATE_VACUUM_REPORTS_RESULT" = "skipped" ] && [ "$SPECS_IDENTICAL" = "true" ]; then
            echo "⏭️  generate-vacuum-reports: skipped (specs are identical)"
          elif [ "$GENERATE_VACUUM_REPORTS_RESULT" != "success" ]; then
            echo "❌ generate-vacuum-reports: ${{ needs.generate-vacuum-reports.result }}"
            exit 1
          fi
      - name: Check check-breaking-changes
        env:
          CHECK_BREAKING_CHANGES_RESULT: ${{ needs.check-breaking-changes.result }}
          MANUAL_LINTER_OVERRIDE_RESULT: ${{ needs.manual-linter-override.result }}
          SPECS_IDENTICAL: ${{ needs.check-specs-identical.outputs.specs-identical }}
        run: |
          if [ "$CHECK_BREAKING_CHANGES_RESULT" = "skipped" ] && [ "$SPECS_IDENTICAL" = "true" ]; then
            echo "⏭️  check-breaking-changes: skipped (specs are identical)"
          elif [ "$CHECK_BREAKING_CHANGES_RESULT" != "success" ] && [ "$MANUAL_LINTER_OVERRIDE_RESULT" = "success" ]; then
            echo "⚠️ Manual linter override requested for breaking changes check"
            echo "Breaking changes check failed but was manually approved to proceed"
          elif [ "$CHECK_BREAKING_CHANGES_RESULT" != "success" ]; then
            echo "❌ check-breaking-changes: ${{ needs.check-breaking-changes.result }}"
            exit 1
          fi
      - name: Verify API Spec Check Passed
        run: echo "✅ All API specification checks passed successfully!"