plugin-api.yml

name: Plugin API

# Fails a change that breaks the plugin surface unless its title
# marks the break with `!`. A workflow of its own, so that a title edit re-runs only this check.
# On main it checks the squash commit against its parent, a record of what reached history.

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: plugin-api-${{ github.event_name == 'pull_request' && github.ref || github.sha }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

env:
  PIP_DISABLE_PIP_VERSION_CHECK: "1"

jobs:
  plugin-api:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      pull-requests: read  # gh api reads the title as it is now, not as the event recorded it
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
        with:
          fetch-depth: 2
          persist-credentials: false
      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: "3.12"
      # The title is read when the job runs, so a re-run sees an edited one. Only this step has the
      # token, and it runs none of the pull request's code; a file carries the title on.
      - name: Title
        env:
          GH_TOKEN: ${{ github.token }}
          PULL_REQUEST: ${{ github.event.pull_request.number }}
        run: |
          if [ -n "$PULL_REQUEST" ]; then
            gh api "repos/$GITHUB_REPOSITORY/pulls/$PULL_REQUEST" --jq .title > "$RUNNER_TEMP/title"
          else
            git log -1 --format=%s > "$RUNNER_TEMP/title"
            touch "$RUNNER_TEMP/on-main"
          fi
      # A pull request's merge ref sits on the current base, so HEAD^1 is the base as the change
      # would land on it.
      - name: Plugin surface against the base
        run: |
          python -m pip install --quiet uv
          title=$(cat "$RUNNER_TEMP/title")
          where=()
          [ -e "$RUNNER_TEMP/on-main" ] && where=(--on-main)
          griffe=$(grep -oE '"griffelib==[^"]+"' pyproject.toml | tr -d '"')
          [ -n "$griffe" ] || { echo "::error::pyproject.toml's dev extra needs an exact griffelib== pin"; exit 1; }
          uv run --no-project --with "$griffe" python .github/scripts/check_plugin_api.py --base HEAD^1 \
            --title="$title" "${where[@]}"