01-basic-ci.yml

name: "01 · Basic CI"

# ──────────────────────────────────────────────────────────────────────────────
# TRIGGERS
# ──────────────────────────────────────────────────────────────────────────────
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:
    inputs:
      environment:
        description: "Target environment"
        required: true
        type: choice
        options: [staging, production]
      skip-tests:
        description: "Skip tests (fast deploy)"
        type: boolean
        default: false

# ──────────────────────────────────────────────────────────────────────────────
# DEFAULTS — cancel in-progress runs when a new push arrives
# ──────────────────────────────────────────────────────────────────────────────
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# Minimal default permissions — grant only what each job needs
permissions:
  contents: read

# ──────────────────────────────────────────────────────────────────────────────
# JOBS
# ──────────────────────────────────────────────────────────────────────────────
jobs:
  # ── 1. Lint ──────────────────────────────────────────────────────────────────
  lint:
    name: Lint
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

      - name: Set up Python
        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b  # v5.3.0
        with:
          python-version: "3.11"

      - name: Cache pip
        uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c6158d  # v4.2.0
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
          restore-keys: ${{ runner.os }}-pip-

      - name: Install linter
        run: pip install ruff

      - name: Lint
        run: ruff check src/

  # ── 2. Test ──────────────────────────────────────────────────────────────────
  test:
    name: Test (Python ${{ matrix.python-version }})
    runs-on: ubuntu-latest
    if: ${{ !inputs.skip-tests }}

    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.10", "3.11", "3.12"]

    steps:
      - name: Checkout
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b  # v5.3.0
        with:
          python-version: ${{ matrix.python-version }}

      - name: Cache pip
        uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c6158d  # v4.2.0
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('requirements.txt') }}

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Run tests
        run: pytest src/ -v --junitxml=test-results-${{ matrix.python-version }}.xml

      - name: Upload test results
        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08  # v4.6.0
        if: always()
        with:
          name: test-results-py${{ matrix.python-version }}
          path: test-results-${{ matrix.python-version }}.xml
          retention-days: 30

      - name: Post test summary
        if: always()
        run: |
          echo "## Test Results — Python ${{ matrix.python-version }}" >> $GITHUB_STEP_SUMMARY
          echo "Run at: $(date -u)" >> $GITHUB_STEP_SUMMARY

  # ── 3. Build ─────────────────────────────────────────────────────────────────
  build:
    name: Build
    needs: [lint, test]
    runs-on: ubuntu-latest

    outputs:
      version: ${{ steps.version.outputs.tag }}

    steps:
      - name: Checkout
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

      - name: Set up Python
        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b  # v5.3.0
        with:
          python-version: "3.11"

      - name: Generate version tag
        id: version
        run: echo "tag=v$(date +%Y%m%d)-${{ github.run_number }}" >> $GITHUB_OUTPUT

      - name: Build package
        run: |
          pip install build
          python -m build

      - name: Upload dist
        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08  # v4.6.0
        with:
          name: dist-${{ steps.version.outputs.tag }}
          path: dist/

  # ── 4. Deploy Staging ─────────────────────────────────────────────────────────
  deploy-staging:
    name: Deploy → Staging
    needs: build
    if: github.ref == 'refs/heads/main' || inputs.environment == 'staging'
    runs-on: ubuntu-latest
    environment: staging

    steps:
      - name: Download dist
        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16  # v4.1.8
        with:
          name: dist-${{ needs.build.outputs.version }}
          path: dist/

      - name: Deploy to staging
        run: |
          echo "Deploying version ${{ needs.build.outputs.version }} to staging..."
          echo "Artifact contents:"
          ls -la dist/
        env:
          DEPLOY_TOKEN: ${{ secrets.STAGING_DEPLOY_TOKEN }}