From 99096ae118bda83aeb2ca044c4a736e0c2c0d52f Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Wed, 12 Aug 2026 20:30:34 -0500
Subject: [PATCH] ci: gate breaking spec changes with oasdiff; fix
 sdk_generation trigger

- Add breaking-changes.yml: oasdiff compares the PR spec against the
  base branch and fails on breaking changes (fail-on WARN). PRs labeled
  'breaking-change' still get the report but pass, acknowledging an
  intentional break. Complements validate.yml, which covers static
  lint but not client compatibility.
- Fix sdk_generation.yaml paths filter: './plex-api-spec.yaml' never
  matched (GitHub path globs are repo-root-relative without './'), so
  spec pushes did not trigger SDK generation; masked by the hourly cron.
---
 .github/workflows/breaking-changes.yml | 41 ++++++++++++++++++++++++++
 .github/workflows/sdk_generation.yaml  |  2 +-
 2 files changed, 42 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/breaking-changes.yml

diff --git a/.github/workflows/breaking-changes.yml b/.github/workflows/breaking-changes.yml
new file mode 100644
index 000000000..55a6802df
--- /dev/null
+++ b/.github/workflows/breaking-changes.yml
@@ -0,0 +1,41 @@
+name: Breaking Changes
+
+# Compares the PR's spec against the base branch with oasdiff and fails on
+# changes that would break existing API clients (and the eight generated
+# SDKs). Label the PR 'breaking-change' to acknowledge an intentional
+# break: the report is still produced, but the job passes.
+
+on:
+  pull_request:
+    # No branches filter: stacked PRs (base != main) get the gate too.
+    paths:
+      - "plex-api-spec.yaml"
+      - ".github/workflows/breaking-changes.yml"
+
+permissions:
+  contents: read
+  pull-requests: write # lets oasdiff post its review link as a PR comment
+
+concurrency:
+  group: breaking-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  breaking-changes:
+    name: Breaking-change gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Fetch base branch
+        run: git fetch --depth=1 origin "$GITHUB_BASE_REF"
+
+      - name: Detect breaking changes (oasdiff)
+        uses: oasdiff/oasdiff-action/breaking@033c15c845bef10f148afb0fa781bf1b2a7fe1bf # v0.1.12
+        with:
+          base: "origin/${{ github.base_ref }}:plex-api-spec.yaml"
+          revision: "HEAD:plex-api-spec.yaml"
+          fail-on: ${{ !contains(github.event.pull_request.labels.*.name, 'breaking-change') && 'WARN' || '' }}
+          github-token: ${{ github.token }}
diff --git a/.github/workflows/sdk_generation.yaml b/.github/workflows/sdk_generation.yaml
index 4c1c52074..c9240ac01 100644
--- a/.github/workflows/sdk_generation.yaml
+++ b/.github/workflows/sdk_generation.yaml
@@ -18,7 +18,7 @@ permissions:
       - main
     paths:
       - .github/workflows/sdk_generation.yaml
-      - ./plex-api-spec.yaml
+      - plex-api-spec.yaml
 jobs:
   generate:
     uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15