diff --git a/.github/workflows/oasdiff-comment.yml b/.github/workflows/oasdiff-comment.yml
new file mode 100644
index 00000000..55fd96a3
--- /dev/null
+++ b/.github/workflows/oasdiff-comment.yml
@@ -0,0 +1,63 @@
+name: OpenAPI Diff Comment
+
+# Split from oasdiff.yml specifically so this job — the only one that needs a write-capable
+# GITHUB_TOKEN — never checks out, fetches, or executes anything from the PR/fork. It only
+# downloads the plain-text report artifact that oasdiff.yml (running with a read-only token,
+# on `pull_request`) already produced, and posts/updates it as a PR comment. This is GitHub's
+# own documented pattern for safely commenting on fork PRs — see:
+# https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/
+on:
+ workflow_run:
+ workflows: ["OpenAPI Diff (oasdiff)"]
+ types:
+ - completed
+
+permissions:
+ actions: read
+ pull-requests: write
+
+jobs:
+ comment:
+ name: Post oasdiff report comment
+ runs-on: ubuntu-latest
+ if: github.event.workflow_run.conclusion == 'success'
+ steps:
+ - name: Download report artifact
+ uses: actions/download-artifact@v4
+ with:
+ name: oasdiff-report
+ path: /tmp/oasdiff
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+ run-id: ${{ github.event.workflow_run.id }}
+
+ - name: Comment on PR
+ uses: actions/github-script@v7
+ with:
+ script: |
+ const fs = require('fs');
+ const marker = '';
+ const prNumber = parseInt(fs.readFileSync('/tmp/oasdiff/pr_number.txt', 'utf8').trim(), 10);
+ const body = marker + '\n' + fs.readFileSync('/tmp/oasdiff/report.md', 'utf8');
+
+ const { data: comments } = await github.rest.issues.listComments({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: prNumber,
+ });
+ const existing = comments.find(c => c.body && c.body.startsWith(marker));
+
+ if (existing) {
+ await github.rest.issues.updateComment({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ comment_id: existing.id,
+ body,
+ });
+ } else {
+ await github.rest.issues.createComment({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: prNumber,
+ body,
+ });
+ }
diff --git a/.github/workflows/oasdiff.yml b/.github/workflows/oasdiff.yml
new file mode 100644
index 00000000..9fa32afb
--- /dev/null
+++ b/.github/workflows/oasdiff.yml
@@ -0,0 +1,115 @@
+name: OpenAPI Diff (oasdiff)
+
+# Deliberately plain `pull_request` (not `_target`), so this job never gets a write-capable
+# GITHUB_TOKEN and never needs one — it only reads spec JSON and writes a report. GitHub always
+# gives `pull_request` a read-only token for fork PRs regardless of `permissions:` below, which
+# is exactly what we want here: this job has nothing to write. Posting the sticky PR comment is
+# the separate, privileged job in .github/workflows/oasdiff-comment.yml (triggered by
+# `workflow_run` once this one finishes), which never checks out or executes anything from the
+# PR — see that file for why that split exists.
+on:
+ pull_request:
+ paths:
+ - 'api/**'
+ - '.github/workflows/oasdiff.yml'
+
+permissions:
+ contents: read
+
+jobs:
+ oasdiff:
+ name: oasdiff breaking-change report
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Resolve base/head OpenAPI spec files
+ id: specs
+ run: |
+ set -euo pipefail
+ BASE_SHA="${{ github.event.pull_request.base.sha }}"
+ HEAD_SHA="${{ github.event.pull_request.head.sha }}"
+ mkdir -p /tmp/oasdiff
+
+ base_spec=$(git ls-tree -r --name-only "$BASE_SHA" -- api | grep -E '^api/graphiant_api_docs_v[0-9.]+\.json$' | sort -V | tail -1 || true)
+ head_spec=$(git ls-tree -r --name-only "$HEAD_SHA" -- api | grep -E '^api/graphiant_api_docs_v[0-9.]+\.json$' | sort -V | tail -1 || true)
+
+ if [ -z "$base_spec" ] || [ -z "$head_spec" ]; then
+ echo "No versioned OpenAPI spec found on one side of the diff — skipping oasdiff." | tee /tmp/oasdiff/report.md >> "$GITHUB_STEP_SUMMARY"
+ echo "skip=true" >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
+
+ git show "$BASE_SHA:$base_spec" > /tmp/oasdiff/base.json
+ git show "$HEAD_SHA:$head_spec" > /tmp/oasdiff/head.json
+
+ if cmp -s /tmp/oasdiff/base.json /tmp/oasdiff/head.json; then
+ echo "OpenAPI spec content unchanged — skipping oasdiff." | tee /tmp/oasdiff/report.md >> "$GITHUB_STEP_SUMMARY"
+ echo "skip=true" >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
+
+ echo "skip=false" >> "$GITHUB_OUTPUT"
+ echo "base_spec=$base_spec" >> "$GITHUB_OUTPUT"
+ echo "head_spec=$head_spec" >> "$GITHUB_OUTPUT"
+
+ # Emits ::error:: workflow commands, which GitHub renders as inline
+ # annotations on the "Files changed" tab and in the job's Checks output.
+ - name: Annotate breaking changes
+ if: steps.specs.outputs.skip != 'true'
+ run: |
+ docker run --rm --mount type=bind,src=/tmp/oasdiff,dst=/data tufin/oasdiff breaking \
+ --format githubactions /data/base.json /data/head.json \
+ | sed 's#/data/head\.json#${{ steps.specs.outputs.head_spec }}#g'
+
+ - name: Build oasdiff report
+ if: steps.specs.outputs.skip != 'true'
+ run: |
+ {
+ echo "## oasdiff: \`${{ steps.specs.outputs.base_spec }}\` → \`${{ steps.specs.outputs.head_spec }}\`"
+ echo
+ docker run --rm --mount type=bind,src=/tmp/oasdiff,dst=/data tufin/oasdiff breaking \
+ --format text /data/base.json /data/head.json > /tmp/oasdiff/breaking.txt || true
+
+ # Each breaking-change finding is a line starting with "error" (tab-separated); the
+ # summary/no-change lines never start a line that way, so this is more robust than
+ # matching oasdiff's exact wording, which differs between "no changes at all" and
+ # "changes, but none breaking".
+ if ! grep -qE '^error\b' /tmp/oasdiff/breaking.txt; then
+ echo "✅ **No breaking changes** detected by [oasdiff](https://github.com/oasdiff/oasdiff)."
+ else
+ echo "⚠️ **oasdiff reports non-backward-compatible changes** in this spec update — review before releasing:"
+ echo
+ echo '```'
+ cat /tmp/oasdiff/breaking.txt
+ echo '```'
+ fi
+
+ echo
+ echo "Full spec changelog (oasdiff)
"
+ echo
+ docker run --rm --mount type=bind,src=/tmp/oasdiff,dst=/data tufin/oasdiff changelog \
+ --format markdown /data/base.json /data/head.json || true
+ echo
+ echo "