Comment on PR only when api-spec drifts or changes

Adapts itk-dev/devops_itksites's two-job api-spec workflow to this
repo's v2 spec layout, with one behaviour change: stay quiet when the
spec is unchanged. itksites' "no changes detected" comment lands on
every PR that touches src/, which is most of them; suppressing that
branch removes the noise while keeping the signal — the workflow now
only posts on (a) committed spec out of date with the source,
(b) non-breaking spec changes (changelog), or (c) breaking spec
changes (changelog + failure). --edit-last keeps the PR to one
in-place comment across pushes.

Pinned oasdiff-action to v0.0.44 instead of @main; path filters
restrict the run to PRs that could plausibly affect the spec; the
breaking-changes job depends on the export job so a drifting spec
isn't compared against the base.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: turegjorup

.github/workflows/apispec.yaml

@@ -1,32 +1,44 @@
 ### ### Api Spec
 ###
 ### Re-exports the OpenAPI spec (`public/api-spec-v2.{yaml,json}`) from the
-### API Platform configuration and fails if the result differs from the
-### committed copy.
+### API Platform configuration. Posts a PR comment **only** when something
+### needs attention — spec drift, non-breaking changes, or breaking changes —
+### and stays quiet otherwise. The comment is edited in place across runs
+### so a PR carries at most one comment from this workflow.
 ###
 ### #### Assumptions
 ###
 ### 1. A docker compose service named `phpfpm` can be run and `bin/console`
 ###    can be run inside the `phpfpm` service.
 ### 2. The committed `public/api-spec-v2.{yaml,json}` are kept in sync with
-###    the API Platform config.
+###    the API Platform configuration via `composer update-api-spec`.
 
-on: pull_request
+on:
+  pull_request:
+    paths:
+      - "src/**/*.php"
+      - "config/**"
+      - "composer.json"
+      - "composer.lock"
+      - "public/api-spec-v2.yaml"
+      - "public/api-spec-v2.json"
+      - "docker-compose.yml"
 
 name: Api Spec
 
 env:
   COMPOSE_USER: runner
 
 jobs:
-  apispec:
+  api-spec-export:
+    name: Ensure API specification is up to date
     runs-on: ubuntu-latest
-    name: API Specification validation
+    permissions:
+      contents: read
+      pull-requests: write
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 2
 
       - name: Cache vendor
         uses: actions/cache@v5
@@ -41,14 +53,108 @@ jobs:
       - name: Install Dependencies
         run: docker compose run --rm phpfpm composer install
 
-      - name: Export specifications (yaml)
-        run: docker compose run --rm phpfpm bin/console api:openapi:export --yaml --output=public/api-spec-v2.yaml --no-interaction
+      - name: Export specifications
+        run: |
+          docker compose run --rm phpfpm bin/console api:openapi:export --yaml --output=public/api-spec-v2.yaml --no-interaction
+          docker compose run --rm phpfpm bin/console api:openapi:export --output=public/api-spec-v2.json --no-interaction
+
+      - name: Check for uncommitted changes
+        id: git-diff-spec
+        continue-on-error: true
+        run: git diff --diff-filter=ACMRT --exit-code public/api-spec-v2.yaml public/api-spec-v2.json
+
+      - name: Comment PR if spec is outdated
+        if: steps.git-diff-spec.outcome == 'failure'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh pr comment ${{ github.event.pull_request.number }} \
+            --body "$(cat <<'EOF'
+          ## API specification not up to date
+
+          The committed API specification files do not match the exported output.
+
+          Please run the following command, then commit and push the changes:
+
+          ```shell
+          docker compose exec phpfpm composer update-api-spec
+          ```
+          EOF
+          )" \
+            --create-if-none --edit-last
+
+      - name: Fail if spec is outdated
+        if: steps.git-diff-spec.outcome == 'failure'
+        run: exit 1
+
+  api-spec-breaking-changes:
+    name: Detect breaking changes in API specification
+    runs-on: ubuntu-latest
+    needs: [api-spec-export]
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Fetch base branch for comparison
+        run: git fetch --depth=1 origin ${{ github.base_ref }}
+
+      - name: Detect breaking changes
+        id: breaking
+        continue-on-error: true
+        uses: oasdiff/oasdiff-action/breaking@v0.0.44
+        with:
+          base: "origin/${{ github.base_ref }}:public/api-spec-v2.yaml"
+          revision: "public/api-spec-v2.yaml"
+          fail-on: ERR
+
+      - name: Generate changelog
+        id: changelog
+        continue-on-error: true
+        uses: oasdiff/oasdiff-action/changelog@v0.0.44
+        with:
+          base: "origin/${{ github.base_ref }}:public/api-spec-v2.yaml"
+          revision: "public/api-spec-v2.yaml"
+          format: markdown
+          output-to-file: changelog.md
+
+      # Stay quiet when nothing changed — neither breaking nor non-breaking.
+      # Comments only fire on the two branches below.
 
-      - name: Check for changes in specifications (yaml)
-        run: git diff --diff-filter=ACMRT --exit-code public/api-spec-v2.yaml
+      - name: Comment PR - non-breaking changes
+        if: steps.breaking.outcome == 'success' && hashFiles('changelog.md') != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          {
+            echo "## API Specification - Non-breaking changes"
+            echo ""
+            cat changelog.md
+          } > comment.md
+          gh pr comment ${{ github.event.pull_request.number }} \
+            --body-file comment.md \
+            --create-if-none --edit-last
 
-      - name: Export specifications (json)
-        run: docker compose run --rm phpfpm bin/console api:openapi:export --output=public/api-spec-v2.json --no-interaction
+      - name: Comment PR - breaking changes
+        if: steps.breaking.outcome == 'failure'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          {
+            echo "## API Specification - Breaking changes detected"
+            echo ""
+            if [ -s changelog.md ]; then
+              cat changelog.md
+            else
+              echo "The breaking changes action detected incompatible changes. Review the action logs for details."
+            fi
+          } > comment.md
+          gh pr comment ${{ github.event.pull_request.number }} \
+            --body-file comment.md \
+            --create-if-none --edit-last
 
-      - name: Check for changes in specifications (json)
-        run: git diff --diff-filter=ACMRT --exit-code public/api-spec-v2.json
+      - name: Fail if breaking changes detected
+        if: steps.breaking.outcome == 'failure'
+        run: exit 1