ci.yml

name: CI
on:
  pull_request:
  push:
    branches:
      - main
  workflow_call:
    inputs:
      attest-package:
        description: "Create GitHub provenance attestation for the package."
        default: "false"
        type: string
    outputs:
      artifact-basename:
        description: "Base name of the uploaded artifacts; use for artifact retrieval."
        value: ${{ jobs.package.outputs.artifact-basename }}

# Cancel active CI runs for a PR before starting another run
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

defaults:
  run:
    shell: bash  # https://github.com/beeware/briefcase/pull/912

env:
  FORCE_COLOR: "1"

permissions:
  contents: read

jobs:
  pre-commit:
    name: Pre-commit checks
    uses: beeware/.github/.github/workflows/pre-commit-run.yml@main
    with:
      pre-commit-source: "--group pre-commit"

  ty:
    name: Type check
    runs-on: ubuntu-24.04
    continue-on-error: true
    steps:
    - name: Checkout
      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
      with:
        persist-credentials: false

    - name: Set up Python
      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
      with:
        python-version: "3.13"

    - name: Install Tox
      run: python -m pip install --group tox-uv

    - name: Type check
      run: tox -e ty

  towncrier:
    name: Check towncrier
    uses: beeware/.github/.github/workflows/towncrier-run.yml@main
    permissions:
      contents: read
      pull-requests: write
    with:
      tox-source: "--group tox-uv"

  package:
    name: Package Briefcase
    permissions:
      id-token: write
      contents: read
      attestations: write
    strategy:
      matrix:
        subdir:
        - ""  # root briefcase package
        - "debugger"
        - "automation"
    uses: beeware/.github/.github/workflows/python-package-create.yml@main
    with:
      build-subdirectory: ${{ matrix.subdir }}
      attest: ${{ inputs.attest-package }}

  docs-lint:
    name: Documentation linting
    needs: [ pre-commit ]
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
          fetch-depth: 1

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: "3.X"
          cache: pip
          cache-dependency-path: |
            pyproject.toml
            .pre-commit-config.yaml

      - name: Install system dependencies
        run: |
          sudo apt-get install aspell aspell-en

      - name: Update pip
        run: python -m pip install -U pip

      - name: Install Tox
        run: python -m pip install --group 'tox-uv'

      - name: Perform lint checks
        run: python -m tox -e docs-lint

  unit-tests:
    name: Unit tests
    needs: [ pre-commit, towncrier, package ]
    runs-on: ${{ matrix.platform }}
    continue-on-error: ${{ matrix.experimental || false }}
    strategy:
      fail-fast: false
      matrix:
        platform: [ "macos-15-intel", "macos-latest", "windows-latest", "ubuntu-24.04" ]
        python-version: [ "3.10", "3.14" ]
        include:
          # Ensure the Python versions between min and max are tested
          - platform: "ubuntu-24.04"
            python-version: "3.11"
          - platform: "ubuntu-24.04"
            python-version: "3.12"
          - platform: "ubuntu-24.04"
            python-version: "3.13"
          # # Allow dev Python to fail without failing entire job
          # - python-version: "3.15"
          #   experimental: true
    steps:
    - name: Checkout
      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
      with:
        persist-credentials: false
        fetch-depth: 0

    - name: Set up Python
      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
      with:
        python-version: ${{ matrix.python-version }}
        allow-prereleases: true

    - name: Get Packages
      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
      with:
        pattern: ${{ format('{0}*', needs.package.outputs.artifact-basename) }}
        merge-multiple: true
        path: dist

    - name: Install Tox
      run: python -m pip install --group tox-uv

    - name: Test Briefcase
      id: test
      run: |
        RUNNER_OS=$(cut -d- -f1 <<< ${{ matrix.platform }})
        RUNNER_VERSION=$(cut -d- -f2 <<< ${{ matrix.platform }})
        COVERAGE_FILE=".coverage.${RUNNER_OS}.${RUNNER_VERSION}.${{ matrix.python-version }}" \
          tox -e py-cov --installpkg dist/briefcase-*.whl

    - name: Store Coverage Data
      if: always() && (steps.test.outcome == 'success' || steps.test.outcome == 'failure')
      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
      with:
        name: coverage-data-${{ matrix.platform }}-${{ matrix.python-version }}
        path: ".coverage.*"
        if-no-files-found: error
        include-hidden-files: true

    - name: Report Platform Coverage
      id: coverage
      if: always() && (steps.test.outcome == 'success' || steps.test.outcome == 'failure')
      # coverage reporting must use the same Python version used to produce coverage
      run: tox -qe coverage$(tr -dc "0-9" <<< "${{ matrix.python-version }}")

    - name: Test Debugger
      run: |
          tox -e py-debugger --installpkg dist/briefcase_debugger-*.whl

  coverage:
    name: Project coverage
    runs-on: ubuntu-24.04
    needs: unit-tests
    if: always() && (needs.unit-tests.result == 'success' || needs.unit-tests.result == 'failure')
    steps:
    - name: Checkout
      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
      with:
        persist-credentials: false
        fetch-depth: 0

    - name: Setup Python
      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
      with:
        # Use minimum version of python for coverage to avoid phantom branches
        # https://github.com/nedbat/coveragepy/issues/1572#issuecomment-1522546425
        python-version: "3.10"

    - name: Install Tox
      run: python -m pip install --group tox-uv

    - name: Retrieve Coverage Data
      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
      with:
        pattern: coverage-data-*
        merge-multiple: true

    - name: Platform Coverage Reports
      id: platform-coverage
      run: |
        tox --parallel-no-spinner -qe \
          coverage-ci-platform-linux,coverage-ci-platform-macos,coverage-ci-platform-windows

    - name: Project Coverage Report
      id: project-coverage
      if: always()
      run: tox -qe coverage-ci-project-html

    - name: Upload Project Coverage HTML Report
      if: always() && steps.project-coverage.outcome == 'failure'
      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
      with:
        name: html-coverage-report-project
        path: htmlcov

  verify-projects:
    name: Verify project
    needs: [ package, unit-tests ]
    uses: beeware/.github/.github/workflows/app-create-verify.yml@main
    with:
      runner-os: ${{ matrix.runner-os }}
      framework: ${{ matrix.framework }}
    strategy:
      fail-fast: false
      matrix:
        framework: [ "toga", "pyside6", "pygame", "console" ]
        runner-os: [ "macos-15-intel", "macos-latest", "ubuntu-24.04", "ubuntu-24.04-arm", "windows-latest", "windows-11-arm"]

  verify-apps:
    name: Build app
    needs: [ package, unit-tests ]
    uses: beeware/.github/.github/workflows/app-build-verify.yml@main
    with:
      # Builds on Linux must use System Python; otherwise, fall back to version all GUI toolkits support
      python-version: ${{ startsWith(matrix.runner-os, 'ubuntu') && 'system' || '3.12' }}
      runner-os: ${{ matrix.runner-os }}
      framework: ${{ matrix.framework }}
    strategy:
      fail-fast: false
      matrix:
        framework: [ "toga", "pyside6", "pygame", "console" ]
        runner-os: [ "macos-15-intel", "macos-15", "ubuntu-24.04", "ubuntu-24.04-arm", "windows-latest", "windows-11-arm" ]
        exclude:
          # Toga apps won't run on Windows ARM64 until toga#2782 is resolved
          - framework: "toga"
            runner-os: "windows-11-arm"
          # Pygame hasn't published Windows ARM64 wheels
          - framework: "pygame"
            runner-os: "windows-11-arm"
          # PySide6 is unstable on Windows ARM64 (see #2969)
          - framework: "pyside6"
            runner-os: "windows-11-arm"