ci: add optimized CI/CD workflows

[Kamilbenkirane]

Add comprehensive CI/CD workflows:

CI Workflow:

• Parallel jobs: format-check, lint, type-check, security, test
• Matrix testing: Python 3.12/3.13, multiple OS (Ubuntu, Windows, macOS)
• Coverage reporting with Codecov
• Coverage threshold: 90%

Publish Workflow:

• Version validation (tag vs pyproject.toml)
• CI checks before publishing
• TestPyPI → Production PyPI flow
• GitHub Release creation

Composite Action:

• Reusable Python + uv setup
• Workspace support (--all-packages)
• Dependency groups support (--group dev)

All workflows follow GitHub Actions best practices and align with Makefile patterns.

[claude]

PR Review: CI/CD Workflows

Overall, this is a well-structured and comprehensive CI/CD implementation that follows GitHub Actions best practices.

---

Strengths

Code Quality & Best Practices

• Excellent separation of concerns: Parallel jobs for format-check, lint, type-check, security, and tests
• Proper use of composite actions: The setup-python-uv action promotes DRY principles and consistency
• Good alignment with Makefile: Commands match the existing Makefile patterns exactly
• Matrix testing strategy: Smart cross-platform testing (Ubuntu, Windows, macOS) and Python version coverage (3.12, 3.13)
• Workflow reusability: workflow_call trigger allows the publish workflow to reuse the CI workflow

Security

• Minimal permissions: Uses principle of least privilege (contents: read for CI)
• OIDC token authentication: Uses id-token: write for trusted publishing to PyPI (no API tokens needed)
• Version validation: Excellent version mismatch detection between git tag and pyproject.toml
• Environment protection: Uses GitHub environments for TestPyPI and PyPI deployments
• Artifact isolation: Proper artifact upload/download pattern prevents tampering

---

Issues & Recommendations

1. Critical: Dependency sync inconsistency

File: .github/actions/setup-python-uv/action.yml:23

Your Makefile uses --all-extras (line 18), but the composite action uses --group dev. Since your pyproject.toml only defines dependency-groups.dev (no extras), the current approach works, but this should be clarified for consistency.

2. Bug: Changelog generation edge cases

File: .github/workflows/publish.yml:114-119

If git log fails, the fallback is No changes, which is misleading. The logic could also fail on the first release. Consider adding better error handling and empty changelog detection.

3. Performance: Codecov upload configuration

File: .github/workflows/ci.yml:89-94

fail_ci_if_error: false silently ignores Codecov failures, which could mask coverage reporting issues. Consider using fail_ci_if_error: true with continue-on-error: true on the step to get notifications without blocking CI.

4. Enhancement: Add workflow concurrency control

Files: .github/workflows/ci.yml and .github/workflows/publish.yml

Add concurrency groups to prevent multiple CI runs for rapid pushes. This prevents wasted CI minutes for outdated commits while ensuring publish workflows always complete.

5. Minor: Python version pinning

File: .github/workflows/publish.yml:29

Uses python3 directly instead of a specific version. Use actions/setup-python@v5 with explicit version for consistency.

6. Testing: Makefile alignment

File: .github/workflows/ci.yml:33,43,55

CI uses ruff format --check while Makefile uses ruff format. Add a format-check target to Makefile for exact parity.

7. Security: TestPyPI verification

File: .github/workflows/publish.yml:75

Consider adding verification that installs from TestPyPI and checks the version before proceeding to production PyPI.

---

Test Coverage

Concern: The PR adds workflows but no tests for the workflows themselves.

Recommendations:

• Consider using act (https://github.com/nektos/act) to test workflows locally
• Add documentation about how these workflows were tested
• Document expected behavior for edge cases (first release, failed CI, etc.)

---

Security Assessment

Overall: Secure implementation

Strengths:

• Uses OIDC for PyPI publishing (excellent)
• Minimal permissions throughout
• No hardcoded secrets or tokens
• Environment-based deployment controls
• Artifact integrity maintained through job dependencies

Minor concern: The fetch-depth: 1 in multiple places might cause issues with changelog generation. Consider using fetch-depth: 0 in the github-release job.

---

Performance Considerations

Strengths:

1. Parallel job execution: Excellent use of parallel jobs
2. Matrix optimization: Smart use of include to avoid redundant cross-platform testing
3. Caching: enable-cache: true in uv setup is good
4. Artifact size: Uploading only dist/ is optimal

Suggestion: Consider using actions/cache for mypy cache across runs for faster type checking.

---

Documentation Gaps

Missing documentation about:

1. Required GitHub secrets/environments (CODECOV_TOKEN, testpypi, pypi environments)
2. OIDC trusted publisher configuration instructions
3. Workflow badge suggestions for README

---

Summary

Rating: 8.5/10

This is a high-quality PR that demonstrates strong understanding of CI/CD best practices.

Priority levels:

1. Approve after addressing: Issue Add Claude Code GitHub Workflow #1 (sync flags inconsistency)
2. Strongly recommended: Issues Add Claude Code GitHub Workflow #2, chore: setup repository infrastructure #3, chore: setup repository infrastructure #4
3. Nice to have: Issues docs: add .env.example file for credential configuration #5, feat: add artifacts and mime_types core modules #6, feat: add artifacts and mime_types core modules #7

The workflows are production-ready with minor improvements. Great work on the comprehensive coverage and security-conscious design!