test.yml

name: Test
on:
  pull_request:
    branches:
      - main
      - master
  push:
    branches:
      - main
      - master

# Least privilege. Nothing in this workflow writes to the repository; the
# Permit API calls authenticate with their own secret, not GITHUB_TOKEN.
permissions:
  contents: read

env:
  PROJECT_ID: 7f55831d77c642739bc17733ab0af138 #github actions project id (under 'Permit.io Tests' workspace)
  ENV_NAME: python-sdk-ci

jobs:
  pytest:
    runs-on: ubuntu-24.04
    strategy:
      fail-fast: false
      matrix:
        pydantic-version: ['pydantic<2.0.0', 'pydantic>=2.0.0']
        # `include` only attaches extra keys to the two existing entries; it
        # adds no new jobs and leaves the job names below untouched. Each
        # lane installs the matching dependency group from pyproject.toml, so
        # both pydantic resolutions come from uv.lock.
        include:
          - pydantic-version: 'pydantic<2.0.0'
            dependency-group: pydantic-v1
            pydantic-major: '1'
          - pydantic-version: 'pydantic>=2.0.0'
            dependency-group: pydantic-v2
            pydantic-major: '2'
    # NOTE: this name and the matrix shape are load-bearing. Branch protection
    # on main requires the contexts "pytest (Pydantic pydantic<2.0.0)" and
    # "pytest (Pydantic pydantic>=2.0.0)" by exact string. Renaming the job or
    # changing the matrix silently makes those contexts unsatisfiable, which
    # blocks every PR from merging until branch protection is updated to match.
    name: pytest (Pydantic ${{ matrix.pydantic-version }})
    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Install uv
        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
        with:
          # The uv pinned in the dev group, as locked in uv.lock.
          version-file: "uv.lock"
          # Sets UV_PYTHON, so every uv command below runs on exactly this
          # interpreter (downloaded by uv if the runner does not have it).
          python-version: "3.11.8"
          enable-cache: true
          # The two lanes share uv.lock but install different pydantic
          # majors, so they need separate cache entries.
          cache-suffix: ${{ matrix.dependency-group }}

      # Values reach the shell through env: rather than ${{ }} interpolation
      # into the script body. zizmor flags the interpolated form as
      # template-injection; env-passing is the canonical fix.
      - name: Creation env ${{ env.ENV_NAME }}-${{ github.run_id }}-${{ matrix.pydantic-version }}
        id: create_env
        env:
          PROJECT_ID: ${{ env.PROJECT_ID }}
          ENV_NAME: ${{ env.ENV_NAME }}
          RUN_ID: ${{ github.run_id }}
          PYDANTIC_SUFFIX: ${{ matrix.pydantic-version == 'pydantic<2.0.0' && 'v1' || 'v2' }}
          PROJECT_API_KEY: ${{ secrets.PROJECT_API_KEY }}
        run: |
          set -euo pipefail
          ENV_KEY="${ENV_NAME}-${RUN_ID}-${PYDANTIC_SUFFIX}"
          echo "ENV_KEY=$ENV_KEY" >> "$GITHUB_ENV"

          response=$(curl -sS -X POST \
            "https://api.permit.io/v2/projects/${PROJECT_ID}/envs" \
            -H "Authorization: Bearer ${PROJECT_API_KEY}" \
            -H 'Content-Type: application/json' \
            -d "{\"key\": \"${ENV_KEY}\", \"name\": \"${ENV_KEY}\"}")

          ENV_ID=$(echo "$response" | jq -r '.id')
          if [ -z "$ENV_ID" ] || [ "$ENV_ID" = "null" ]; then
            echo "::error title=Env creation failed::Could not create the scratch environment."
            exit 1
          fi
          echo "ENV_ID=$ENV_ID" >> "$GITHUB_ENV"
          echo "New env created with key: $ENV_KEY"

      - name: Fetch API_KEY of ${{ env.ENV_KEY }}
        env:
          PROJECT_ID: ${{ env.PROJECT_ID }}
          ENV_ID: ${{ env.ENV_ID }}
          PROJECT_API_KEY: ${{ secrets.PROJECT_API_KEY }}
        run: |
          set -euo pipefail
          response=$(curl -sS -X GET \
            "https://api.permit.io/v2/api-key/${PROJECT_ID}/${ENV_ID}" \
            -H "Authorization: Bearer ${PROJECT_API_KEY}")

          ENV_API_KEY=$(echo "$response" | jq -r '.secret')
          if [ -z "$ENV_API_KEY" ] || [ "$ENV_API_KEY" = "null" ]; then
            echo "::error title=API key fetch failed::Could not read the scratch environment's key."
            exit 1
          fi
          # Mask before export so the key can never surface in the job log.
          echo "::add-mask::$ENV_API_KEY"
          echo "ENV_API_KEY=$ENV_API_KEY" >> "$GITHUB_ENV"

      # Started here, NOT as a `services:` container. A service container is
      # created before the first step runs, so the only key available to it is
      # the long-lived PROJECT_API_KEY -- while the tests authenticate with the
      # per-run scratch environment key minted above. The PDP then rejects
      # every decision request with a 403 whose body is plain text, which the
      # SDK surfaces as "cannot connect to the PDP container". That mismatch is
      # why the ReBAC and RBAC decision tests could never pass.
      - name: Start the PDP
        env:
          ENV_API_KEY: ${{ env.ENV_API_KEY }}
        run: |
          set -euo pipefail
          docker run -d --name permit-pdp \
            -p 7766:7000 \
            -e PDP_API_KEY="${ENV_API_KEY}" \
            -e PDP_DEBUG=true \
            permitio/pdp-v2:latest
          echo "PDP container started; it warms up while dependencies install."

      # --locked fails the job if uv.lock is out of date with pyproject.toml
      # instead of silently re-resolving.
      - name: Install dependencies
        env:
          DEPENDENCY_GROUP: ${{ matrix.dependency-group }}
        run: uv sync --locked --group "${DEPENDENCY_GROUP}"

      - name: Show installed packages
        run: uv pip list

      # Proves the lane runs the pydantic major its name claims. Without it a
      # resolution change could quietly run both lanes on the same major.
      - name: Verify pydantic major
        env:
          EXPECTED_MAJOR: ${{ matrix.pydantic-major }}
        run: |
          set -euo pipefail
          uv run --no-sync python - <<'PY'
          import os
          import sys

          import pydantic

          expected = os.environ["EXPECTED_MAJOR"]
          print(f"python {sys.version.split()[0]}, pydantic {pydantic.VERSION}")
          if str(pydantic.VERSION).split(".")[0] != expected:
              sys.exit(f"expected pydantic {expected}.x, got {pydantic.VERSION}")
          PY

      # Waited for here rather than immediately after `docker run`, so the
      # PDP's bootstrap (fetch config, pull the policy bundle, start OPA)
      # overlaps with dependency installation instead of running after it.
      # The PDP reports 503 on /healthy until its horizon component is up;
      # issuing a check before that fails in a way that looks like a policy
      # bug rather than a timing one.
      - name: Wait for the PDP
        run: |
          set -uo pipefail
          for i in $(seq 1 180); do
            if curl -sf http://localhost:7766/healthy > /dev/null 2>&1; then
              echo "PDP healthy after ${i}s"
              exit 0
            fi
            sleep 1
          done
          echo "::error title=PDP did not become healthy::/healthy never returned 200 within 180s"
          docker logs permit-pdp 2>&1 | tail -80
          exit 1


      - name: Test with pytest
        env:
          PDP_URL: http://localhost:7766
          API_TIER: prod
          ORG_PDP_API_KEY: ${{ env.ENV_API_KEY }}
          PROJECT_PDP_API_KEY: ${{ env.ENV_API_KEY }}
          PDP_API_KEY: ${{ env.ENV_API_KEY }}
        run: uv run --no-sync pytest -s --cache-clear tests/

      - name: PDP logs
        if: failure()
        run: docker logs permit-pdp 2>&1 | tail -200 || true

      - name: Stop the PDP
        if: always()
        run: docker rm -f permit-pdp || true

      - name: Delete env ${{ env.ENV_KEY }}
        if: always()
        env:
          PROJECT_ID: ${{ env.PROJECT_ID }}
          ENV_ID: ${{ env.ENV_ID }}
          PROJECT_API_KEY: ${{ secrets.PROJECT_API_KEY }}
        run: |
          set -uo pipefail
          # Best effort: a failed cleanup must not mask a test failure, but it
          # must still be visible rather than silently leaking an environment.
          if [ -z "${ENV_ID:-}" ] || [ "${ENV_ID}" = "null" ]; then
            echo "::warning::No ENV_ID recorded; nothing to delete."
            exit 0
          fi
          if ! curl -sS -f -X DELETE \
            "https://api.permit.io/v2/projects/${PROJECT_ID}/envs/${ENV_ID}" \
            -H "Authorization: Bearer ${PROJECT_API_KEY}"; then
            echo "::warning title=Scratch env leaked::Failed to delete environment ${ENV_ID}. Delete it by hand."
          fi

  # Offline suite on every supported Python. It needs no secrets and no PDP, so
  # it also runs on fork PRs. Kept apart from `pytest` above, whose name and
  # matrix are required status checks.
  compatibility:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        # floor: the lowest version of every runtime dependency pyproject.toml
        # allows on that Python, which for pydantic is a pydantic 1 release.
        # pydantic-v2-floor: the same with pydantic held to 2, i.e. the lowest
        # pydantic 2 a consumer can install on that Python.
        # pydantic-v2: what a fresh install gets.
        # Python 3.14 also runs the newest pydantic 1, because it has its own
        # pydantic requirement and pydantic calls v1's 3.14 support minimal.
        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
        deps: [floor, pydantic-v2-floor, pydantic-v2]
        include:
          - python-version: '3.14'
            deps: pydantic-v1
    name: compatibility (Python ${{ matrix.python-version }}, ${{ matrix.deps }})
    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      # uv resolves to the lowest allowed versions, which pip cannot. setup-uv
      # installs the uv pinned in uv.lock, so a new uv release cannot change
      # which floor a leg tests.
      # activate-environment creates .venv on the leg's Python and puts it on
      # PATH, so `uv pip` installs into it and `python` runs from it. No cache:
      # every leg resolves a different set, and a shared entry would hold
      # whichever leg saved first.
      - name: Install uv
        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
        with:
          version-file: "uv.lock"
          python-version: ${{ matrix.python-version }}
          activate-environment: true
          enable-cache: false

      # These legs resolve from the ranges in pyproject.toml, not from uv.lock,
      # because the ranges are what a consumer's installer sees. Installing the
      # package itself (".") reads its dependencies from the metadata uv_build
      # writes, version markers included. --no-sources and --exclude-newer false
      # resolve as a consumer does: the published metadata ignores
      # [tool.uv.sources], and the publish-age cooldown in [tool.uv] applies
      # only to this repository's uv.lock.
      - name: Install dependencies
        env:
          DEPS: ${{ matrix.deps }}
        run: |
          set -euo pipefail
          resolve=(--no-sources --exclude-newer false)
          case "${DEPS}" in
            floor)
              uv pip compile --quiet "${resolve[@]}" --python "$(command -v python)" \
                --resolution lowest-direct pyproject.toml -o "${RUNNER_TEMP}/floor.txt"
              uv pip install "${resolve[@]}" . --group dev -c "${RUNNER_TEMP}/floor.txt"
              ;;
            pydantic-v2-floor)
              echo "pydantic>=2" > "${RUNNER_TEMP}/pydantic-v2.txt"
              uv pip compile --quiet "${resolve[@]}" --python "$(command -v python)" \
                --resolution lowest-direct pyproject.toml -c "${RUNNER_TEMP}/pydantic-v2.txt" \
                -o "${RUNNER_TEMP}/floor.txt"
              grep '^pydantic==' "${RUNNER_TEMP}/floor.txt"
              uv pip install "${resolve[@]}" . --group dev -c "${RUNNER_TEMP}/floor.txt"
              ;;
            pydantic-v1)
              uv pip install "${resolve[@]}" . --group dev "pydantic[email]<2"
              ;;
            pydantic-v2)
              uv pip install "${resolve[@]}" . --group dev "pydantic[email]>=2"
              ;;
            *)
              echo "::error title=Unknown dependency set::${DEPS}"
              exit 1
              ;;
          esac

      - name: Show installed packages
        run: uv pip list

      # Type checkers read permit's annotations only when py.typed is in the
      # installed package, and see the blocking client as blocking only through
      # _sync_types.pyi. Neither is a .py file, so a packaging change can drop
      # them without any import failing. The artifacts are the same on every
      # leg, so one leg builds and checks them: the wheel, and the sdist, since
      # a wheel built from the sdist holds only what the sdist does.
      - name: Check the wheel and sdist ship their type information
        if: matrix.python-version == '3.14' && matrix.deps == 'pydantic-v2'
        run: |
          set -euo pipefail
          uv build --no-sources --out-dir "${RUNNER_TEMP}/dist"
          python - "${RUNNER_TEMP}/dist" <<'PY'
          import sys
          import tarfile
          import zipfile
          from pathlib import Path

          dist = Path(sys.argv[1])
          wheels = sorted(dist.glob("*.whl"))
          sdists = sorted(dist.glob("*.tar.gz"))
          if len(wheels) != 1 or len(sdists) != 1:
              found = [path.name for path in wheels + sdists]
              sys.exit(f"expected one wheel and one sdist in {dist}, found {found}")
          required = ["permit/py.typed", "permit/_sync_types.pyi"]
          contents = {wheels[0]: set(zipfile.ZipFile(wheels[0]).namelist())}
          # Every sdist path starts with its top-level permit-<version>/ directory.
          with tarfile.open(sdists[0]) as sdist:
              contents[sdists[0]] = {name.partition("/")[2] for name in sdist.getnames()}
          for artifact, names in contents.items():
              missing = [path for path in required if path not in names]
              if missing:
                  sys.exit(f"{artifact.name} is missing {missing}")
              print(f"{artifact.name} ships {' and '.join(required)}")
          PY

      # Every test that needs credentials, the Permit API or a PDP is marked
      # e2e (see [tool.pytest] in pyproject.toml), so `-m "not e2e"` selects
      # everything else.
      # The filter fails the run on Python 3.14's deprecation of
      # asyncio.iscoroutinefunction, whether permit or a dependency calls it.
      # It is deliberately narrow: a blanket error::DeprecationWarning would
      # also trip on PermitConnectionError, which still subclasses the
      # deprecated PermitException on purpose.
      - name: Offline tests
        run: |
          python -m pytest -q -m "not e2e" \
            -W "error:'asyncio.iscoroutinefunction' is deprecated:DeprecationWarning"

  # The migration skill's tests (skills/tests): MIGRATION.md, the skill and its
  # scanner, checked against each other and against the SDK. They run apart from
  # the SDK's suite, with skills/tests/pytest.ini. Not a required check.
  migration-skill:
    name: Migration Skill Tests (pydantic ${{ matrix.pydantic }})
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        pydantic: ['1', '2']
    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      # uv also provides the Python 3.9 the scanner runs on below.
      - name: Install uv
        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
        with:
          version-file: "uv.lock"
          python-version: '3.12'
          enable-cache: true
          # The two lanes share uv.lock but install different pydantic
          # majors, so they need separate cache entries.
          cache-suffix: pydantic-v${{ matrix.pydantic }}

      # The locked environment the pytest job runs, with the pydantic major this
      # lane names. --locked fails the job if uv.lock is out of date with
      # pyproject.toml instead of silently re-resolving.
      - name: Install dependencies
        env:
          PYDANTIC_MAJOR: ${{ matrix.pydantic }}
        run: uv sync --locked --group "pydantic-v${PYDANTIC_MAJOR}"

      - name: Migration skill tests
        run: uv run --no-sync pytest -q -c skills/tests/pytest.ini skills/tests

      # Customers run the scanner before they move off Python 3.8/3.9, so it
      # must still run there. --no-project keeps the SDK's environment and its
      # requires-python out of it.
      - name: Run the scanner on Python 3.9
        if: matrix.pydantic == '2'
        run: |
          set -euo pipefail
          uv run --no-project --python 3.9 python \
            skills/permit-python-3-migration/scripts/scan.py skills/tests/fixtures/v2_app --json \
            > "${RUNNER_TEMP}/scan.json"
          uv run --no-sync python - "${RUNNER_TEMP}/scan.json" <<'PY'
          import json
          import sys

          report = json.load(open(sys.argv[1]))
          if not report["findings"]:
              sys.exit("the scanner found nothing in the 2.x sample app on Python 3.9")
          print(f"Python 3.9: {len(report['findings'])} findings")
          PY