This document details the CI workflow defined in .github/workflows/ci.yaml, which implements the continuous integration pipeline for the StackOne AI SDK. The workflow enforces quality gates, runs tests across multiple Python versions, and generates coverage reports. For information about the release automation workflow, see Release Workflow. For details on the custom Nix setup action used throughout this workflow, see Setup Nix Action.
Sources: .github/workflows/ci.yaml1-101
The CI workflow triggers on two events:
| Trigger Type | Configuration | Purpose |
|---|---|---|
push | All branches | Run checks on every commit |
pull_request | Target branch: main | Validate changes before merge |
The workflow implements concurrency control to prevent redundant runs:
This configuration cancels in-progress runs when new commits are pushed to the same branch, conserving CI resources.
The workflow requires specific permissions for GitHub Pages deployment:
contents: read - Read repository contentspages: write - Deploy to GitHub Pagesid-token: write - OIDC token for Pages deploymentSources: .github/workflows/ci.yaml3-16
The workflow consists of four jobs with specific dependencies and conditional execution:
Diagram: CI Workflow Job Dependencies
Jobs run independently except deploy-coverage, which requires coverage to complete successfully. The coverage and deploy-coverage jobs only execute on the main branch.
Sources: .github/workflows/ci.yaml19-101
The gitleaks job scans the repository for accidentally committed secrets using the gitleaks tool:
| Configuration | Value |
|---|---|
| Runner | ubuntu-latest |
| Checkout depth | 0 (full history) |
| Tools installed | gitleaks |
| Skip uv sync | true |
fetch-depth: 0) to scan all commitsgitleaks detect --source . --config .gitleaks.tomlThe job uses .gitleaks.toml for configuration (see Security Configuration) and fails the workflow if secrets are detected.
Sources: .github/workflows/ci.yaml19-34 .github/actions/setup-nix/action.yaml8-11
The ci job is the primary quality enforcement mechanism, running linting, type checking, and tests across multiple Python versions.
Diagram: CI Job Test Matrix Expansion
The matrix creates four parallel job instances:
| Python Version | Runner OS |
|---|---|
| 3.10 | ubuntu-latest |
| 3.11 | ubuntu-latest |
| 3.12 | ubuntu-latest |
| 3.13 | ubuntu-latest |
Sources: .github/workflows/ci.yaml36-40
The job installs a comprehensive toolset via the setup-nix action:
| Tool | Purpose |
|---|---|
uv | Python package manager |
ty | Type checker |
just | Task runner |
bun | JavaScript runtime (for MCP mock server) |
pnpm_10 | Node.js package manager |
typescript-go | TypeScript transpiler |
These tools enable the execution of lint, type check, and test commands.
Sources: .github/workflows/ci.yaml47-50 .github/actions/setup-nix/action.yaml4-7
The job executes three quality gates in sequence:
Diagram: CI Job Execution Sequence
Each step must succeed for the workflow to pass:
just lint) - Enforces code style via ruff (see Code Quality Standards)just ty) - Validates type annotations using ty type checkerjust test) - Executes pytest suite with MCP mock server runningThe job checks out submodules (submodules: true) to include the MCP mock server at vendor/stackone-ai-node.
Sources: .github/workflows/ci.yaml41-59 .github/actions/setup-nix/action.yaml30-50
The coverage job generates comprehensive test coverage reports and is conditionally executed only on the main branch:
| Tool | Purpose |
|---|---|
uv | Python package manager |
just | Task runner |
bun | JavaScript runtime |
pnpm_10 | Node.js package manager |
typescript-go | TypeScript transpiler |
Note: ty is excluded as type checking is already performed in the ci job.
Sources: .github/workflows/ci.yaml61-73
The job produces multiple coverage report formats:
Diagram: Coverage Artifact Generation Pipeline
just coverage, which runs pytest with coverage trackingjaywcjlove/coverage-badges-cli to generate an SVG badge from coverage/coverage.json using the totals.percent_covered JSON pathcoverage/ directory as a GitHub Pages artifactThe generated artifacts include:
coverage/coverage.json - Machine-readable coverage datacoverage/htmlcov/ - HTML coverage reportcoverage/badges.svg - Visual coverage percentage badgeSources: .github/workflows/ci.yaml75-88
The deploy-coverage job publishes coverage reports to GitHub Pages:
| Configuration | Value |
|---|---|
| Dependencies | needs: coverage |
| Conditional | if: github.ref == 'refs/heads/main' |
| Environment | github-pages |
| Runner | ubuntu-latest |
Diagram: Coverage Deployment Flow
The job executes a single step:
actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e (v4.0.5) to publish the artifact uploaded by the coverage jobThe deployment output URL is captured in steps.deployment.outputs.page_url and displayed in the job summary.
Sources: .github/workflows/ci.yaml90-101
All jobs except gitleaks require a complete development environment. The workflow uses a custom composite action at .github/actions/setup-nix to standardize environment provisioning.
The action accepts two inputs:
| Input | Type | Default | Purpose |
|---|---|---|---|
tools | string | "uv ty just" | Space-separated list of nixpkgs packages |
skip-uv-sync | boolean | "false" | Skip Python dependency installation |
| Job | Tools Parameter | skip-uv-sync | Rationale |
|---|---|---|---|
gitleaks | gitleaks | true | No Python dependencies needed |
ci | uv ty just bun pnpm_10 typescript-go | false | Full test environment required |
coverage | uv just bun pnpm_10 typescript-go | false | Test environment without type checker |
The gitleaks job optimizes execution time by skipping Python and Node.js dependency installation entirely.
For detailed information on the setup-nix action implementation, see Setup Nix Action.
Sources: .github/workflows/ci.yaml27-73 .github/actions/setup-nix/action.yaml3-11
The following diagram maps workflow concepts to concrete file paths and command invocations:
Diagram: CI Workflow Code Entity Relationships
| Entity Type | Path/Command | Line Reference |
|---|---|---|
| Workflow definition | .github/workflows/ci.yaml | 1-101 |
| Custom action | .github/actions/setup-nix/action.yaml | 1-51 |
| Gitleaks command | gitleaks detect --source . --config .gitleaks.toml | ci.yaml34 |
| Lint command | just lint | ci.yaml53 |
| Type check command | just ty | ci.yaml56 |
| Test command | just test | ci.yaml59 |
| Coverage command | just coverage | ci.yaml76 |
| UV sync command | uv sync --all-extras --locked | setup-nix/action.yaml42 |
| PNPM install command | pnpm install --frozen-lockfile | setup-nix/action.yaml49 |
Sources: .github/workflows/ci.yaml1-101 .github/actions/setup-nix/action.yaml1-51
Related Documentation:
just lint, just test, etc.), see Task Automation with justRefresh this wiki