api-diff.yml

---
name: API Diff

on:
  pull_request:
    types:
      - opened
      - synchronize
      - reopened
      - labeled
      - unlabeled
  workflow_dispatch:
    inputs:
      baseline_version:
        description: >-
          Override the baseline version to compare against.
          Defaults to <api.diff.baseline.version> in pom.xml.
        required: false
        default: ""

permissions:
  contents: read

jobs:
  api-diff:
    runs-on: ubuntu-24.04
    env:
      # Empty unless overridden via workflow_dispatch; the api-diff task then
      # falls back to <api.diff.baseline.version> in pom.xml.
      API_DIFF_BASELINE_VERSION: ${{ inputs.baseline_version }}
      BREAKING_API_CHANGE_ACCEPTED: >-
        ${{ contains(github.event.pull_request.labels.*.name, 'breaking-api-change-accepted') }}

    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          persist-credentials: false
      - uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4.0.1
        with:
          version: v2026.5.18
          sha256: cfac593469d028d7ae5fe36e37bd7c59118b5238e92d8a876209578464f24a84
      - name: Cache local Maven repository
        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
        with:
          path: ~/.m2/repository
          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
      - name: Run japicmp API diff
        run: mise run api-diff
      - name: Check docs/apidiffs is up to date
        run: |
          if ! git diff --exit-code -- docs/apidiffs; then
            echo "::error::Published API surface changed but docs/apidiffs is stale."
            echo "Run 'mise run api-diff' locally and commit the updated docs/apidiffs."
            exit 1
          fi
      - name: Fail on incompatible published API changes
        run: |
          python3 - <<'PY'
          import os
          from pathlib import Path
          import sys
          import xml.etree.ElementTree as ET

          failures = []
          for report in sorted(Path(".").glob("**/target/japicmp/api-diff.xml")):
              parts = report.parts
              module = "/".join(parts[: parts.index("target")])
              tree = ET.parse(report)
              for change in tree.findall(".//compatibilityChange"):
                  binary = change.get("binaryCompatible") == "false"
                  source = change.get("sourceCompatible") == "false"
                  if binary or source:
                      failures.append((module, change.get("type", "unknown")))

          if not failures:
              print("No incompatible published API changes detected.")
              sys.exit(0)

          print("Incompatible published API changes detected:")
          for module, change_type in failures[:100]:
              print(f"- {module}: {change_type}")
          if len(failures) > 100:
              print(f"... and {len(failures) - 100} more")
          if os.environ.get("BREAKING_API_CHANGE_ACCEPTED") == "true":
              print("Accepted by PR label `breaking-api-change-accepted`.")
              sys.exit(0)
          print("Run `mise run api-diff` locally for full japicmp output.")
          print("Reports are written to `**/target/japicmp/*`.")
          sys.exit(1)
          PY