api-diff.yml

name: API diff

# Diffs every published API against its last release on PRs into `release`.
# A backport fails on any break, since it must keep the published API. The cut
# (a PR from `main`) only reports, for the migration audit, unless the cycle's
# `phase` in version.json is `additive`: an additive cut publishes patches, so
# a break fails it. Nightly calls this on `main` and runs only in that phase,
# so a break that lands early surfaces within a day rather than at the cut.
permissions:
  contents: read

on:
  workflow_call:

concurrency:
  group: api-diff-${{ github.ref }}
  cancel-in-progress: true

jobs:
  diff:
    name: Public API
    runs-on: ubuntu-24.04-arm
    # Nightly's run on `main` writes the Rust cache, which needs this environment's keys.
    environment: ${{ github.ref == 'refs/heads/main' && 'cache-write' || '' }}
    # cargo-semver-checks documents every published crate twice, baseline and current.
    timeout-minutes: 120
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Pick the mode
        id: mode
        run: |
          # `release` has no version.json until the first shared cut lands there.
          phase=null
          if [[ -f version.json ]]; then phase=$(jq -r .phase version.json); fi
          if [[ "$EVENT" != pull_request* ]]; then
            # Nightly on `main`: only the additive phase forbids a break there.
            [[ "$phase" == additive ]] && echo "args=--deny" >>"$GITHUB_OUTPUT" || echo "skip=1" >>"$GITHUB_OUTPUT"
          elif [[ "$HEAD_REF" == main && "$HEAD_REPO" == "$GITHUB_REPOSITORY" && "$phase" != additive ]]; then
            # Only this repository's own `main` is the cut; a fork's `main` is a backport.
            echo "args=" >>"$GITHUB_OUTPUT"
          else
            echo "args=--deny" >>"$GITHUB_OUTPUT"
          fi
        env:
          EVENT: ${{ github.event_name }}
          HEAD_REF: ${{ github.head_ref }}
          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
      - if: ${{ !steps.mode.outputs.skip }}
        uses: ./.github/actions/nix
      - if: ${{ !steps.mode.outputs.skip }}
        uses: ./.github/actions/rust-cache
        with:
          access-key-id: ${{ secrets.MBX_R2_ACCESS_KEY_ID }}
          secret-access-key: ${{ secrets.MBX_R2_SECRET_ACCESS_KEY }}
      # The JS baseline is rendered from `release`'s source.
      - name: Fetch release
        if: ${{ !steps.mode.outputs.skip }}
        run: git fetch --no-tags --depth=1 origin +refs/heads/release:refs/remotes/origin/release
      - name: Diff against the last release
        id: diff
        if: ${{ !steps.mode.outputs.skip }}
        # The report-only mode passes no argument.
        run: nix develop --command just api-diff ${ARGS:+"$ARGS"}
        env:
          ARGS: ${{ steps.mode.outputs.args }}
          # Lists and downloads the moq-c and moq-ffi release assets.
          GH_TOKEN: ${{ github.token }}
      - name: Keep the report
        if: ${{ !cancelled() && steps.diff.outcome != 'skipped' }}
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
        with:
          name: api-diff
          path: target/api-diff/
          retention-days: 30
          if-no-files-found: error