Add override for breaking changes

Author: russell-stern

.github/workflows/breaking-changes.yml

@@ -6,31 +6,43 @@ permissions:
 on:
   pull_request:
     branches: [main]
-    types: [opened, synchronize, reopened]
+    # Re-run when override labels are added or removed
+    types: [opened, synchronize, reopened, labeled, unlabeled]
 
 jobs:
   proto-breaking:
     runs-on: ubuntu-latest
+    env:
+      SKIP: ${{ contains(github.event.pull_request.labels.*.name, 'breaking-change:proto') || contains(github.event.pull_request.labels.*.name, 'breaking-change:approved') }}
     steps:
+      - name: Skipped — intentional breaking change (label override)
+        if: env.SKIP == 'true'
+        run: |
+          echo "::notice title=Proto breaking check skipped::This PR has label breaking-change:proto or breaking-change:approved. A maintainer acknowledged an intentional proto break. Remove the label to re-enable buf breaking."
+
       - name: Checkout code
+        if: env.SKIP != 'true'
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
           submodules: recursive
           token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Setup Bun
+        if: env.SKIP != 'true'
         uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version: 1.3.12
 
       - name: Install dependencies
+        if: env.SKIP != 'true'
         run: bun install --frozen-lockfile
 
       # cre-sdk's buf.yaml points at ../../submodules/chainlink-protos/cre, which buf rejects when
       # --against uses subdir=packages/cre-sdk (module path escapes the context). Run breaking on
       # the chainlink-protos workspace instead, comparing HEAD to the submodule commit pinned on main.
       - name: Buf breaking (proto)
+        if: env.SKIP != 'true'
         run: |
           set -euo pipefail
           REPO="${{ github.workspace }}"
@@ -49,26 +61,38 @@ jobs:
 
   ts-api-surface:
     runs-on: ubuntu-latest
+    env:
+      SKIP: ${{ contains(github.event.pull_request.labels.*.name, 'breaking-change:typescript-api') || contains(github.event.pull_request.labels.*.name, 'breaking-change:approved') }}
     steps:
+      - name: Skipped — intentional breaking change (label override)
+        if: env.SKIP == 'true'
+        run: |
+          echo "::notice title=TypeScript API check skipped::This PR has label breaking-change:typescript-api or breaking-change:approved. Commit an updated api-baseline.d.ts when appropriate; this label only bypasses CI."
+
       - name: Checkout code
+        if: env.SKIP != 'true'
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           submodules: recursive
           token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Setup Bun
+        if: env.SKIP != 'true'
         uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version: 1.3.12
 
       - name: Install dependencies
+        if: env.SKIP != 'true'
         run: bun install --frozen-lockfile
 
       - name: Compile declaration emit
+        if: env.SKIP != 'true'
         working-directory: packages/cre-sdk
         run: bun run compile:build
 
       - name: Diff TypeScript public API vs baseline
+        if: env.SKIP != 'true'
         working-directory: packages/cre-sdk
         run: |
           cat dist/index.d.ts dist/pb.d.ts \
@@ -83,26 +107,38 @@ jobs:
 
   host-bindings:
     runs-on: ubuntu-latest
+    env:
+      SKIP: ${{ contains(github.event.pull_request.labels.*.name, 'breaking-change:host-bindings') || contains(github.event.pull_request.labels.*.name, 'breaking-change:approved') }}
     steps:
+      - name: Skipped — intentional breaking change (label override)
+        if: env.SKIP == 'true'
+        run: |
+          echo "::notice title=Host bindings check skipped::This PR has label breaking-change:host-bindings or breaking-change:approved. Update snapshots and host-imports-baseline.txt when appropriate; this label only bypasses CI."
+
       - name: Checkout code
+        if: env.SKIP != 'true'
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           submodules: recursive
           token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Setup Bun
+        if: env.SKIP != 'true'
         uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version: 1.3.12
 
       - name: Install dependencies
+        if: env.SKIP != 'true'
         run: bun install --frozen-lockfile
 
       - name: JS host bindings snapshot test
+        if: env.SKIP != 'true'
         working-directory: packages/cre-sdk
         run: bun test src/sdk/wasm/host-bindings-contract.test.ts
 
       - name: Diff Rust host imports vs baseline
+        if: env.SKIP != 'true'
         run: |
           sed -n '/unsafe extern "C"/,/^}/p' \
             packages/cre-sdk-javy-plugin/src/javy_chainlink_sdk/src/lib.rs \

README.md

@@ -268,16 +268,30 @@ bun generate:sdk          # Generate all SDK types and code
 
 ### Breaking Changes
 
-The `breaking-changes` CI job blocks PRs that alter any of the three protected contracts.
-If your change is intentional, update the relevant baseline before pushing:
+The [`breaking-changes`](./.github/workflows/breaking-changes.yml) workflow blocks PRs that alter any of the three protected contracts. If your change is intentional, update the relevant baseline before pushing:
 
 | Contract | What triggers the failure | How to update |
 |---|---|---|
-| Proto fields | Field deleted, renamed, renumbered, or type changed | No baseline file needed — CI runs `buf breaking` on `submodules/chainlink-protos` (`cre` module) against the submodule commit pinned on `main` |
+| Proto fields | Field deleted, renamed, renumbered, or type changed | No baseline file — CI runs `buf breaking` on `submodules/chainlink-protos` (`cre` module) against the submodule commit pinned on `main` |
 | TypeScript public API | An exported type/interface was removed or changed | Run `bun run update-api-baseline` inside `packages/cre-sdk` and commit `api-baseline.d.ts` |
 | JS host binding names | A binding was added, removed, or renamed in `host-bindings.ts` | Run `bun test --update-snapshots` inside `packages/cre-sdk` and commit the updated `__snapshots__` file |
 | Rust host imports | An `extern "C"` import was added or removed in `lib.rs` | Re-run the sed extraction (see `breaking-changes.yml`) and commit `host-imports-baseline.txt` |
 
+#### CI override labels
+
+When a change is **intentionally** breaking and cannot be fixed by updating a baseline (e.g. a coordinated proto break before `main` catches up), a **maintainer** adds the matching label on the PR (this re-runs the workflow):
+
+| Label | Skips |
+|-------|--------|
+| `breaking-change:proto` | `proto-breaking` (`buf breaking`) |
+| `breaking-change:typescript-api` | `ts-api-surface` |
+| `breaking-change:host-bindings` | `host-bindings` |
+| `breaking-change:approved` | All three jobs |
+
+Labels are an audit trail in the PR timeline, not a substitute for review. Prefer updating baselines (`api-baseline.d.ts`, snapshots, `host-imports-baseline.txt`) when the new contract is the new source of truth. For proto breaks, coordinate the `chainlink-protos` submodule bump and document migration notes in the PR.
+
+Restrict who can add these labels in the repo’s **Labels** settings (e.g. maintainers only).
+
 For detailed development setup, see individual package READMEs:
 
 - [CRE SDK Development](./packages/cre-sdk/README.md#building-from-source)