diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 009d316cc..ee713c6fb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -6,6 +6,8 @@ name: CI
permissions:
contents: read
packages: write
+ # The API Contract job posts its report as a pull-request comment.
+ pull-requests: write
on:
pull_request:
@@ -90,6 +92,122 @@ jobs:
- name: Clippy check
run: cargo clippy --features rar -- -D warnings
+ # Guard the API contract: the committed spec must match the code, and any
+ # change to what clients depend on is surfaced on the run.
+ #
+ # The freshness check is not optional decoration. `web/openapi.json` is a
+ # committed artifact regenerated by a pre-commit hook, so a commit made with
+ # `--no-verify`, or from a clone where `make setup-hooks` was never run,
+ # leaves it stale. oasdiff would then compare two identical stale files, pass,
+ # and let the breaking change through: the gate would be theatre.
+ api-contract:
+ name: API Contract
+ runs-on: ubuntu-latest
+ timeout-minutes: 30
+ env:
+ SCCACHE_GHA_ENABLED: "true"
+ SCCACHE_GHA_VERSION: openapi
+ RUSTC_WRAPPER: sccache
+ steps:
+ - uses: actions/checkout@v4
+ - name: Install mold linker
+ run: sudo apt-get update && sudo apt-get install -y mold
+ - name: Install Rust
+ uses: dtolnay/rust-toolchain@master
+ with:
+ toolchain: 1.95.0
+ - name: Setup sccache
+ uses: mozilla-actions/sccache-action@v0.0.9
+
+ - name: Check the committed spec matches the code
+ run: |
+ cargo run -- openapi --output /tmp/openapi-fresh.json
+ if ! diff -q /tmp/openapi-fresh.json web/openapi.json >/dev/null; then
+ echo "::error::web/openapi.json is stale. Run 'make openapi-all' and commit the result."
+ diff -u web/openapi.json /tmp/openapi-fresh.json | head -60 || true
+ exit 1
+ fi
+ if ! diff -q web/openapi.json docs/api/openapi.json >/dev/null; then
+ echo "::error::docs/api/openapi.json differs from web/openapi.json. Run 'make openapi'."
+ exit 1
+ fi
+ echo "OpenAPI spec is in sync with the backend."
+
+ - name: Fetch the base branch
+ run: git fetch --depth=1 origin ${{ github.base_ref }}
+
+ # Reports rather than fails, and the distinction is deliberate.
+ #
+ # A red job means "fix this before merging". A contract change is not
+ # that: breaking changes are a normal mid-cycle event here, because the
+ # version is decided at tag time rather than per PR. Failing the job would
+ # mark a routine, intentional act as a failure, and a check that is
+ # routinely red is one people learn to skim past, which costs more than it
+ # catches.
+ #
+ # `continue-on-error` keeps the job green while still flagging the step, so
+ # the run page shows the change without claiming anything is broken. The
+ # decision this feeds is made by `make release-prepare`, which compares
+ # against the previous tag at the moment the version is actually chosen.
+ #
+ # The stale-spec check above stays fatal, because that one really is a
+ # mistake: the committed artifact does not match the code.
+ - name: Report API contract changes
+ id: contract
+ continue-on-error: true
+ uses: oasdiff/oasdiff-action/breaking@v0
+ with:
+ base: origin/${{ github.base_ref }}:web/openapi.json
+ revision: HEAD:web/openapi.json
+ fail-on: ERR
+ # The spec is public, but uploading it to a third party should be a
+ # decision rather than a default. `github-token: ''` disables the
+ # action's own comment, which posts a link to that upload rather than
+ # the findings; the report is posted below instead.
+ review: false
+ github-token: ""
+
+ # One comment, edited in place, so the PR always shows the current state
+ # rather than a thread of stale reports. It is rewritten to say the
+ # contract is unchanged once the findings are gone, because a lingering
+ # "3 breaking changes" on a PR that no longer has any is worse than no
+ # comment at all.
+ - name: Comment the contract report
+ if: always() && github.event.pull_request.head.repo.full_name == github.repository
+ env:
+ GH_TOKEN: ${{ github.token }}
+ PR: ${{ github.event.pull_request.number }}
+ REPO: ${{ github.repository }}
+ REPORT: ${{ steps.contract.outputs.breaking }}
+ run: |
+ MARKER=''
+
+ if [ -n "$REPORT" ]; then
+ BODY=$(
+ printf '%s\n### API contract changes\n\n' "$MARKER"
+ printf 'Compared against `%s`. These are changes a client generated from the\n' "${{ github.base_ref }}"
+ printf 'previous document would notice. Not a failure: breaking changes are a\n'
+ printf 'release-time decision, and `make release-prepare` checks the bump against\n'
+ printf 'them when the version is chosen.\n\n'
+ printf 'Report
\n\n```\n'
+ printf '%s\n' "$REPORT" | head -c 55000
+ printf '```\n\n