feat(workflows): add Python linting CI workflow with Ruff (#951)

WilliamBerryiii · Bill Berry · web-flow · commit f89f0eb63e06 · 2026-03-13T11:52:45.000-07:00
## Description Add a reusable GitHub Actions workflow for Python linting with Ruff and integrate it into the `pr-validation.yml` hub workflow. ### What changed - **New `python-lint.yml` reusable workflow** (113 lines) — 9-step pipeline performing Ruff check and format verification with JSON artifact upload, changed-file-only detection, and configurable soft-fail mode. - **Hub integration in `pr-validation.yml`** — added `python-lint` job (lines 53-62) targeting `.github/skills/experimental/powerpoint` with `soft-fail: false` and `changed-files-only: true`. ### How it works 1. Caller passes `working-directory`, `soft-fail`, and `changed-files-only` inputs via `workflow_call`. 2. Workflow checks out code, installs uv and Python 3.11, syncs dependencies from the target directory. 3. When `changed-files-only` is true, detects modified `.py` files via `git diff` against the base branch — skips linting when none are found. 4. Runs `ruff check` producing both human-readable output and a JSON artifact (`ruff-results.json`), then runs `ruff format --check`. 5. Uploads JSON results as a workflow artifact and gates the job on lint/format outcomes (respecting `soft-fail`). All third-party actions are SHA-pinned (`checkout v4.2.2`, `setup-uv v5.4.1`, `setup-python v6.2.0`, `upload-artifact v4.4.3`). Permissions follow least-privilege with `contents: read` at both workflow and job levels. ## Related Issue(s) Closes #889 ## Type of Change Select all that apply: **Code & Documentation:** * [ ] Bug fix (non-breaking change fixing an issue) * [x] New feature (non-breaking change adding functionality) * [ ] Breaking change (fix or feature causing existing functionality to change) * [ ] Documentation update **Infrastructure & Configuration:** * [x] GitHub Actions workflow * [ ] Linting configuration (markdown, PowerShell, etc.) * [ ] Security configuration * [ ] DevContainer configuration * [ ] Dependency update **AI Artifacts:** * [ ] Reviewed contribution with `prompt-builder` agent and addressed all feedback * [ ] Copilot instructions (`.github/instructions/*.instructions.md`) * [ ] Copilot prompt (`.github/prompts/*.prompt.md`) * [ ] Copilot agent (`.github/agents/*.agent.md`) * [ ] Copilot skill (`.github/skills/*/SKILL.md`) > Note for AI Artifact Contributors: > > * Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review `.github/agents/` before creating new ones. > * Skills: Must include both bash and PowerShell scripts. See [Skills](../docs/contributing/skills.md). > * Model Versions: Only contributions targeting the **latest Anthropic and OpenAI models** will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected. > * See [Agents Not Accepted](../docs/contributing/custom-agents.md#agents-not-accepted) and [Model Version Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements). **Other:** * [ ] Script/automation (`.ps1`, `.sh`, `.py`) * [ ] Other (please describe): ## Testing **Automated validation results (all passed):** | Command | Result | |---|---| | `npm run lint:md` | Pass — 145 files, 0 errors | | `npm run spell-check` | Pass — 234 files, 0 issues | | `npm run lint:frontmatter` | Pass — 296 files, 0 errors | | `npm run validate:skills` | Pass — 3 skills, 0 errors | | `npm run lint:md-links` | Pass | | `npm run lint:ps` | Pass — all files clean | | `npm run plugin:generate` | Pass — 11 plugins generated, 0 formatting changes | **Diff-based assessment:** - Subagent review completed — confirmed SHA-pinning consistency, least-privilege permissions, hub-and-spoke integration pattern, and stdout-only JSON redirect for artifact integrity. - Target working directory `.github/skills/experimental/powerpoint` does not yet exist on `main`; expected pending PR #868 for the PowerPoint skill. **Manual testing:** - Manual testing was not performed. Workflow validation requires GitHub Actions execution on push. ## Checklist ### Required Checks * [ ] Documentation is updated (N/A — no documentation changes required for workflow addition) * [x] Files follow existing naming conventions * [ ] Changes are backwards compatible (N/A — new workflow with no impact on existing functionality) * [ ] Tests added for new functionality (N/A — no test infrastructure for GitHub Actions workflows) ### AI Artifact Contributions  ### Required Automated Checks The following validation commands must pass before merging: * [x] Markdown linting: `npm run lint:md` * [x] Spell checking: `npm run spell-check` * [x] Frontmatter validation: `npm run lint:frontmatter` * [x] Skill structure validation: `npm run validate:skills` * [x] Link validation: `npm run lint:md-links` * [x] PowerShell analysis: `npm run lint:ps` * [x] Plugin freshness: `npm run plugin:generate` ## Security Considerations * [x] This PR does not contain any sensitive or NDA information * [x] Any new dependencies have been reviewed for security issues * [x] Security-related scripts follow the principle of least privilege **Security analysis:** - No customer data or secrets in changes. - Runtime dependencies limited to `uv` and `ruff` (well-established Python dev tools). All GitHub Actions are SHA-pinned to known release tags. - Workflow permissions restricted to `contents: read`. Checkout uses `persist-credentials: false`. - No elevated privileges required. ## Additional Notes - The `python-lint` job targets `.github/skills/experimental/powerpoint` which depends on the PowerPoint skill from PR #868. The lint job will skip gracefully when no Python files are found in the target directory. - Two commits in this PR: initial implementation (`80156d0`) and a follow-up fix (`7393ab8`) addressing review findings — consuming the `changed-files-only` input and correcting stderr redirect behavior for JSON artifact integrity. --------- Co-authored-by: Bill Berry <wbery@microsoft.com>
diff --git a/.github/workflows/label-sync.yml b/.github/workflows/label-sync.yml
@@ -25,7 +25,7 @@ jobs:
       issues: write
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.2.2
         with:
           persist-credentials: false
 
diff --git a/.github/workflows/pr-validation.yml b/.github/workflows/pr-validation.yml
@@ -50,6 +50,56 @@ jobs:
       soft-fail: false
       changed-files-only: true
 
+  discover-python-projects:
+    name: Discover Python Projects
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      directories: ${{ steps.find.outputs.directories }}
+      has-projects: ${{ steps.find.outputs.has-projects }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.2.2
+        with:
+          persist-credentials: false
+
+      - name: Find Python projects
+        id: find
+        shell: pwsh
+        run: |
+          $projectList = @(Get-ChildItem -Recurse -Filter pyproject.toml |
+            Where-Object { $_.FullName -notmatch 'node_modules' } |
+            ForEach-Object { Resolve-Path -Relative $_.DirectoryName } |
+            ForEach-Object { $_ -replace '^\.[\\/]', '' } |
+            Sort-Object)
+          $jsonItems = $projectList | ForEach-Object { $_ | ConvertTo-Json -Compress }
+          $dirs = '[' + (($jsonItems) -join ',') + ']'
+          "directories=$dirs" >> $env:GITHUB_OUTPUT
+          if ($projectList.Count -eq 0) {
+            "has-projects=false" >> $env:GITHUB_OUTPUT
+            Write-Output 'No Python projects found'
+          } else {
+            "has-projects=true" >> $env:GITHUB_OUTPUT
+            Write-Output "Found Python projects: $dirs"
+          }
+
+  python-lint:
+    name: "Python Lint (${{ matrix.directory }})"
+    needs: discover-python-projects
+    if: needs.discover-python-projects.outputs.has-projects == 'true'
+    strategy:
+      fail-fast: false
+      matrix:
+        directory: ${{ fromJson(needs.discover-python-projects.outputs.directories) }}
+    uses: ./.github/workflows/python-lint.yml
+    permissions:
+      contents: read
+    with:
+      soft-fail: false
+      changed-files-only: true
+      working-directory: ${{ matrix.directory }}
+
   copyright-headers:
     name: Copyright Headers
     uses: ./.github/workflows/copyright-headers.yml
@@ -78,71 +128,22 @@ jobs:
       changed-files-only: false
       code-coverage: true
 
-  # Discover Python skills with pyproject.toml
-  discover-python-skills:
-    name: Discover Python Skills
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    outputs:
-      matrix: ${{ steps.discover.outputs.matrix }}
-      has-skills: ${{ steps.discover.outputs.has-skills }}
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.2.2
-        with:
-          persist-credentials: false
-          fetch-depth: 0
-
-      - name: Discover Python skill directories
-        id: discover
-        shell: bash
-        run: |
-          # Find all pyproject.toml files under .github/skills/
-          SKILLS=$(find .github/skills -name "pyproject.toml" -exec dirname {} \; 2>/dev/null | sort -u)
-          
-          if [ -z "$SKILLS" ]; then
-            echo "No Python skills found"
-            echo "matrix={\"include\":[]}" >> "$GITHUB_OUTPUT"
-            echo "has-skills=false" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-          
-          # Build JSON matrix
-          MATRIX='{"include":['
-          FIRST=true
-          while IFS= read -r skill_dir; do
-            # Get skill name from directory path
-            SKILL_NAME=$(basename "$skill_dir")
-            if [ "$FIRST" = true ]; then
-              FIRST=false
-            else
-              MATRIX+=','
-            fi
-            MATRIX+="{\"name\":\"$SKILL_NAME\",\"working-directory\":\"$skill_dir\"}"
-          done <<< "$SKILLS"
-          MATRIX+=']}'
-          
-          echo "matrix=$(echo "$MATRIX" | jq -c .)" >> "$GITHUB_OUTPUT"
-          echo "has-skills=true" >> "$GITHUB_OUTPUT"
-          echo "Discovered Python skills:"
-          echo "$MATRIX" | jq .
-
   pytest:
-    name: Python Tests (${{ matrix.name }})
-    needs: discover-python-skills
-    if: needs.discover-python-skills.outputs.has-skills == 'true'
+    name: "Python Tests (${{ matrix.directory }})"
+    needs: discover-python-projects
+    if: needs.discover-python-projects.outputs.has-projects == 'true'
     uses: ./.github/workflows/pytest-tests.yml
     permissions:
       contents: read
       id-token: write
     with:
-      working-directory: ${{ matrix.working-directory }}
+      working-directory: ${{ matrix.directory }}
       soft-fail: false
       changed-files-only: true
     strategy:
       fail-fast: false
-      matrix: ${{ fromJson(needs.discover-python-skills.outputs.matrix) }}
+      matrix:
+        directory: ${{ fromJson(needs.discover-python-projects.outputs.directories) }}
 
   docusaurus-tests:
     name: Docusaurus Tests
diff --git a/.github/workflows/pytest-tests.yml b/.github/workflows/pytest-tests.yml
@@ -59,9 +59,9 @@ jobs:
 
       - name: Install uv
         if: "!inputs.changed-files-only || steps.check-python.outputs.has_changes == 'true'"
-        uses: astral-sh/setup-uv@6ee6290f1cbc4156c0bdd66691b2c144ef8df19a # v7.4.0
+        uses: astral-sh/setup-uv@e06108dd0aef18192324c70427afc47652e63a82 # v7.5.0
         with:
-          version: "latest"
+          version: "0.10.9"
 
       - name: Set up Python
         if: "!inputs.changed-files-only || steps.check-python.outputs.has_changes == 'true'"
diff --git a/.github/workflows/python-lint.yml b/.github/workflows/python-lint.yml
@@ -0,0 +1,118 @@
+name: Python Lint
+
+on:
+  workflow_call:
+    inputs:
+      soft-fail:
+        description: 'When true, linting warnings do not fail the build'
+        required: false
+        type: boolean
+        default: false
+      changed-files-only:
+        description: 'When true, lint only changed Python files'
+        required: false
+        type: boolean
+        default: true
+      working-directory:
+        description: 'Directory containing pyproject.toml with ruff config'
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  python-lint:
+    name: Ruff Lint and Format Check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    defaults:
+      run:
+        shell: pwsh
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.2.2
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Derive artifact name
+        id: meta
+        run: |
+          $name = '${{ inputs.working-directory }}' -replace '/', '-' -replace '^\.', '' -replace '^-', ''
+          "artifact-name=python-lint-$name" >> $env:GITHUB_OUTPUT
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@e06108dd0aef18192324c70427afc47652e63a82 # v7.5.0
+        with:
+          version: "0.10.9"
+
+      - name: Setup Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --locked
+        working-directory: ${{ inputs.working-directory }}
+
+      - name: Detect changed Python files
+        if: inputs.changed-files-only
+        run: |
+          $baseRef = if ($env:GITHUB_BASE_REF) { $env:GITHUB_BASE_REF } else { 'main' }
+          $workingDir = '${{ inputs.working-directory }}'
+          $changed = git diff --name-only --diff-filter=ACMR "origin/$baseRef...HEAD" -- $workingDir | Where-Object { $_ -match '\.pyi?$' }
+          if ($changed) {
+            "HAS_CHANGES=true" >> $env:GITHUB_ENV
+            $fileCount = @($changed).Count
+            Write-Output "Detected $fileCount changed Python file(s)"
+          } else {
+            Write-Output "No Python file changes detected under $workingDir"
+          }
+
+      - name: Run ruff check
+        id: ruff-check
+        if: "!inputs.changed-files-only || env.HAS_CHANGES == 'true'"
+        run: |
+          New-Item -ItemType Directory -Path "$env:GITHUB_WORKSPACE/logs" -Force | Out-Null
+          # JSON output -> file only; stderr flows to CI log to preserve valid JSON
+          uv run ruff check . --output-format json > "$env:GITHUB_WORKSPACE/logs/python-lint-results.json"
+          if ($LASTEXITCODE -ne 0) { "RUFF_CHECK_FAILED=true" >> $env:GITHUB_ENV }
+          uv run ruff check .
+          if ($LASTEXITCODE -ne 0) { "RUFF_CHECK_FAILED=true" >> $env:GITHUB_ENV }
+          $global:LASTEXITCODE = 0
+        working-directory: ${{ inputs.working-directory }}
+        continue-on-error: ${{ inputs.soft-fail }}
+
+      - name: Run ruff format check
+        id: ruff-format
+        if: "!inputs.changed-files-only || env.HAS_CHANGES == 'true'"
+        run: |
+          # Stderr flows to CI log; no file redirect so output stays readable
+          uv run ruff format --check .
+          if ($LASTEXITCODE -ne 0) { "RUFF_FORMAT_FAILED=true" >> $env:GITHUB_ENV }
+          $global:LASTEXITCODE = 0
+        working-directory: ${{ inputs.working-directory }}
+        continue-on-error: ${{ inputs.soft-fail }}
+
+      - name: Upload lint results
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v4.4.3
+        if: always() && (!inputs.changed-files-only || env.HAS_CHANGES == 'true')
+        with:
+          name: ${{ steps.meta.outputs.artifact-name }}
+          path: logs/python-lint-results.json
+          retention-days: 30
+          if-no-files-found: ignore
+
+      - name: Check results
+        if: "!inputs.soft-fail && (!inputs.changed-files-only || env.HAS_CHANGES == 'true')"
+        run: |
+          if ($env:RUFF_CHECK_FAILED -eq 'true' -or $env:RUFF_FORMAT_FAILED -eq 'true') {
+            Write-Output '::error::Python linting failed'
+            if ($env:RUFF_CHECK_FAILED -eq 'true') { Write-Output '  - ruff check failed' }
+            if ($env:RUFF_FORMAT_FAILED -eq 'true') { Write-Output '  - ruff format check failed' }
+            exit 1
+          }
+          Write-Output 'All Python lint checks passed'
diff --git a/.github/workflows/release-stable.yml b/.github/workflows/release-stable.yml
@@ -81,6 +81,73 @@ jobs:
     with:
       soft-fail: false
 
+  discover-python-projects:
+    name: Discover Python Projects
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      directories: ${{ steps.find.outputs.directories }}
+      has-projects: ${{ steps.find.outputs.has-projects }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.2.2
+        with:
+          persist-credentials: false
+
+      - name: Find Python projects
+        id: find
+        shell: pwsh
+        run: |
+          $projectList = @(Get-ChildItem -Recurse -Filter pyproject.toml |
+            Where-Object { $_.FullName -notmatch 'node_modules' } |
+            ForEach-Object { Resolve-Path -Relative $_.DirectoryName } |
+            ForEach-Object { $_ -replace '^\.[\\/]', '' } |
+            Sort-Object)
+          $jsonItems = $projectList | ForEach-Object { $_ | ConvertTo-Json -Compress }
+          $dirs = '[' + (($jsonItems) -join ',') + ']'
+          "directories=$dirs" >> $env:GITHUB_OUTPUT
+          if ($projectList.Count -eq 0) {
+            "has-projects=false" >> $env:GITHUB_OUTPUT
+            Write-Output 'No Python projects found'
+          } else {
+            "has-projects=true" >> $env:GITHUB_OUTPUT
+            Write-Output "Found Python projects: $dirs"
+          }
+
+  python-lint:
+    name: "Python Lint (${{ matrix.directory }})"
+    needs: discover-python-projects
+    if: needs.discover-python-projects.outputs.has-projects == 'true'
+    strategy:
+      fail-fast: false
+      matrix:
+        directory: ${{ fromJson(needs.discover-python-projects.outputs.directories) }}
+    uses: ./.github/workflows/python-lint.yml
+    permissions:
+      contents: read
+    with:
+      soft-fail: false
+      changed-files-only: false
+      working-directory: ${{ matrix.directory }}
+
+  pytest:
+    name: "Python Tests (${{ matrix.directory }})"
+    needs: discover-python-projects
+    if: needs.discover-python-projects.outputs.has-projects == 'true'
+    uses: ./.github/workflows/pytest-tests.yml
+    permissions:
+      contents: read
+      id-token: write
+    with:
+      working-directory: ${{ matrix.directory }}
+      soft-fail: false
+      changed-files-only: false
+    strategy:
+      fail-fast: false
+      matrix:
+        directory: ${{ fromJson(needs.discover-python-projects.outputs.directories) }}
+
   release-please:
     name: Release Please
     needs:
@@ -91,6 +158,8 @@ jobs:
       - gitleaks-scan
       - pester-tests
       - docusaurus-tests
+      - python-lint
+      - pytest
     runs-on: ubuntu-latest
     outputs:
       release_created: ${{ steps.release.outputs.release_created }}
diff --git a/package-lock.json b/package-lock.json
