python.yaml

# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
---
name: Python
on:
  push:
    branches: [main]
  pull_request:
    branches: ["*"]
  merge_group:
    types: [checks_requested]
permissions:
  contents: read
concurrency:
  group: "python-${{ github.event.pull_request.number || github.sha }}"
  cancel-in-progress: true
jobs:
  paths-filter:
    runs-on: depot-ubuntu-24.04-arm-small
    # No job may sit at GitHub's 360-minute default: a hung step should
    # fail fast and free the runner. The slowest job here runs well under
    # five minutes, so this is a backstop, not a budget.
    timeout-minutes: 20
    outputs:
      changed: ${{ steps.filter.outputs.changed }}
    steps:
      - uses: actions/checkout@v7
      - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v3
        id: filter
        with:
          filters: |
            changed:
              - '.github/workflows/python.yaml'
              - 'Magefile.go'
              - 'go.mod'
              - 'go.sum'
              - 'proto-clients/spicedb-python-proto/**'
              - 'spicedb-python/**'

  lint:
    needs: paths-filter
    if: needs.paths-filter.outputs.changed == 'true'
    runs-on: depot-ubuntu-24.04-arm-4
    # No job may sit at GitHub's 360-minute default: a hung step should
    # fail fast and free the runner. The slowest job here runs well under
    # five minutes, so this is a backstop, not a budget.
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v7
      # Held at v5 deliberately. setup-go v6+ defaults GOTOOLCHAIN=local, so Go
      # stops fetching the toolchain go.mod asks for and every job that needs a
      # newer one dies with "go.mod requires go >= 1.25.7 (running go 1.24.13;
      # GOTOOLCHAIN=local)". Moving to v6/v7 needs explicit toolchain handling,
      # which is its own change rather than a dependency bump.
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
      - name: Install mage
        timeout-minutes: 5
        run: go install github.com/magefile/mage@latest
      - name: Install ruff
        run: uv tool install ruff
      - name: Sync deps
        working-directory: spicedb-python
        run: uv sync --extra dev
      - name: Lint
        run: mage -d spicedb-python lint

  unit:
    needs: paths-filter
    if: needs.paths-filter.outputs.changed == 'true'
    runs-on: depot-ubuntu-24.04-arm-4
    # No job may sit at GitHub's 360-minute default: a hung step should
    # fail fast and free the runner. The slowest job here runs well under
    # five minutes, so this is a backstop, not a budget.
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
      - name: Install mage
        timeout-minutes: 5
        run: go install github.com/magefile/mage@latest
      - name: Sync proto client dev deps
        working-directory: proto-clients/spicedb-python-proto
        run: uv sync --extra dev
      - name: Sync idiomatic client dev deps
        working-directory: spicedb-python
        run: uv sync --extra dev
      - name: Proto client tests
        run: mage -d proto-clients/spicedb-python-proto test
      - name: Idiomatic client tests
        run: mage -d spicedb-python test

  integration:
    needs: paths-filter
    if: needs.paths-filter.outputs.changed == 'true'
    runs-on: depot-ubuntu-24.04-arm-4
    # No job may sit at GitHub's 360-minute default: a hung step should
    # fail fast and free the runner. The slowest job here runs well under
    # five minutes, so this is a backstop, not a budget.
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
      - name: Install mage
        timeout-minutes: 5
        run: go install github.com/magefile/mage@latest
      - name: Sync deps
        working-directory: spicedb-python
        run: uv sync --extra dev
      - name: Integration test
        run: mage -d spicedb-python integrationTest

  apicompat:
    needs: paths-filter
    if: needs.paths-filter.outputs.changed == 'true' && github.event_name == 'pull_request'
    # Reads the PR's labels to honour breaking-change-acknowledged; the
    # workflow-level grant is contents:read, which cannot see them.
    permissions:
      contents: read
      pull-requests: read
    runs-on: depot-ubuntu-24.04-arm-small
    # No job may sit at GitHub's 360-minute default: a hung step should
    # fail fast and free the runner. The slowest job here runs well under
    # five minutes, so this is a backstop, not a budget.
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
      - name: Install mage
        timeout-minutes: 5
        run: go install github.com/magefile/mage@latest
      - name: Install griffe
        run: uv tool install griffe
      # A deliberate break is acknowledged by labelling the PR
      # `breaking-change-acknowledged`, which skips this step. The label is
      # deliberately per-PR and visible on the PR itself: an intentional break
      # should be a decision someone took and left a record of, not a silent
      # config toggle. Removing the label re-runs the check.
      #
      # The skip is total, not selective -- mage returns 1 both for findings
      # and for its own failures, so this cannot suppress only the former. A
      # labelled PR therefore also loses the signal that the check itself
      # broke, which is the cost of keeping the mechanism this simple.
      # Read the label from the API rather than from github.event. The
      # pull_request payload is a snapshot taken when the event fired, so a
      # label added afterwards is invisible to it -- and re-running the job
      # replays that same stored payload, so a re-run does not see it either.
      # Adding `labeled` to the workflow's trigger types would fix that by
      # re-running all of CI on every label change of any kind, which is a lot
      # of compute for the rare deliberate break. This reads live state, so
      # labelling and re-running the job is enough.
      - name: Check for the acknowledgement label
        id: ack
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail
          if gh api "repos/${{ github.repository }}/issues/${{ github.event.pull_request.number }}/labels" \
               --jq '.[].name' | grep -qx 'breaking-change-acknowledged'; then
            echo "acknowledged=true" >> "$GITHUB_OUTPUT"
          else
            echo "acknowledged=false" >> "$GITHUB_OUTPUT"
          fi
      - name: API compatibility check
        if: steps.ack.outputs.acknowledged != 'true'
        run: mage -d spicedb-python apiCompat origin/${{ github.base_ref }}
      - name: API compatibility check skipped
        if: steps.ack.outputs.acknowledged == 'true'
        run: |
          echo "::notice::API compatibility check skipped: this PR is labelled breaking-change-acknowledged."