⭐ ci-matrix-starter — Reusable CI Workflows (Python & TypeScript)

A lean, production-ready GitHub Actions starter that ships reusable CI workflows for Python (3.11/3.12) and TypeScript/Node 20. Designed for always-green CI with strict local gates mirroring CI, CodeQL out of the box, optional SBOM generation, and guard-rails for safe merges.

_{Core status}

_{CI & automation}

_{Security & supply-chain}

_{Releases & packaging}

---

Repo layout

.
├── .github/workflows/
│   ├── build.yml                     # aggregator (example)
│   ├── codeql.yml                    # CodeQL analysis
│   ├── supply-chain.yml              # SBOM + weekly gates
│   ├── release-sbom.yml              # release SBOM publish
│   ├── ghcr-publish.yml              # container to GHCR (example)
│   ├── release-drafter.yml           # release notes draft
│   ├── auto-assign.yml               # auto-assign reviewers
│   ├── labeler.yml                   # PR labeler
│   ├── dependabot-automerge.yml      # auto-merge Dependabot
│   ├── ts-ci.yml                     # reusable TypeScript/Node CI
│   ├── py-ci.yml                     # reusable Python CI
│   └── py-ci-badge.yml               # wrapper for README badge
├── docs/
│   └── screens/
│       └── local-sanity.png          # terminal screenshot (example)
├── src/
│   ├── index.ts                      # minimal TS example
│   └── ci_matrix_starter/            # minimal Py package
├── tests/                            # Python tests (example)
├── package.json                      # Node scripts
├── pyproject.toml                    # Python tooling
└── README.md

---

🖥️ Operating System Compatibility ✅

| OS               | Status |
|------------------|:------:|
| Linux            |   ✅   |
| macOS            |   ✅   |
| Windows (WSL2)   |   ✅   |
| FreeBSD          |   ✅   |
| Android (Termux) |   ✅   |
| Containers (CI)  |   ✅   |

---

🚀 Quick Start (consumers)

Use the reusable workflows in your repo

Create .github/workflows/ci.yml:

name: CI
on:
  pull_request:
  push:
    branches: [main]

jobs:
  # Python matrix (3.11/3.12) with strict gates
  py:
    uses: CoderDeltaLAN/ci-matrix-starter/.github/workflows/py-ci.yml@v0.1.7
    with:
      python_versions: '["3.11","3.12"]'
      run_tests: true

  # TypeScript / Node 20
  ts:
    uses: CoderDeltaLAN/ci-matrix-starter/.github/workflows/ts-ci.yml@v0.1.7

The aggregator in this repo (build.yml) shows how to orchestrate multiple reusable jobs.

Local mirror (same gates as CI)

Node / TS

npx prettier --check .
npx eslint . --max-warnings=0
npx tsc --noEmit
npm test --silent

Python

python -m pip install --upgrade pip
pip install poetry
poetry install --no-interaction
poetry run ruff check .
poetry run black --check .
PYTHONPATH=src poetry run pytest -q --cov=src --cov-fail-under=100
poetry run mypy src

---

📦 What the workflows expect

TypeScript

• package.json with test script.
• tsconfig.json (scope sources, e.g., src/**/*.ts).
• eslint.config.mjs (flat) and Prettier 3.
• Node 20.x.

Python

• pyproject.toml with dev tools (ruff, black, pytest, mypy, poetry).
• Tests under tests/; coverage threshold via cov-min. Matrix 3.11/3.12 (customizable with python_versions).

Optional SBOM & signing

• SBOMs (CycloneDX) available. If COSIGN_KEY & COSIGN_PASSWORD are present, images/artifacts can be signed (safe-by-default: skipped when absent).

---

⛳ Required checks (CI gating)

Suggested branch-protection contexts:

• CI / build (aggregator success)
• CodeQL Analyze / codeql

Enable linear history, dismiss stale reviews on new pushes, and auto-merge when green.

---

🧪 Local Developer Workflow (mirrors CI)

# Node
npx prettier --check . && npx eslint . --max-warnings=0 && npx tsc --noEmit && npm test --silent

# Python
python -m pip install --upgrade pip && pip install poetry
poetry install --no-interaction
poetry run ruff check . && poetry run black --check .
PYTHONPATH=src poetry run pytest -q --cov=src --cov-fail-under=100
poetry run mypy src

---

👨‍💻 Local sanity (screenshot)

---

🔧 CI (GitHub Actions)

• Reusable jobs for Python and TypeScript; call them via uses: with a tag (e.g., @v0.1.7).
• Built-in CodeQL example.
• Strict, fast feedback suitable for PR auto-merge when green.

Python snippet

- run: python -m pip install --upgrade pip
- run: pip install poetry
- run: poetry install --no-interaction
- run: poetry run ruff check .
- run: poetry run black --check .
- env:
    PYTHONPATH: src
  run: poetry run pytest -q
- run: poetry run mypy src

TypeScript snippet

- run: npx prettier --check .
- run: npx eslint . --max-warnings=0
- run: npx tsc --noEmit
- run: npm test --silent || echo "no tests"

---

🗺 When to Use This Project

• You need ready-to-use CI for Python + TypeScript with clean defaults.
• You want reusable workflows referenced by tag.
• You value security (CodeQL), SBOMs, and strict gates to keep main always green.

---

🧩 Customization

• Pin a release tag, e.g., @v0.1.7.
• Adjust Python matrix: with.python_versions.
• Toggle tests in the wrapper: with.run_tests (true/false).
• Provide secrets to enable optional cosign signing.
• Extend jobs by adding steps after uses:.

---

🔒 Security

• Code scanning via CodeQL.
• Recommend enabling: required conversations resolved, dismiss stale reviews, signed commits, and squash merges.
• Avoid uploading sensitive artifacts to public PRs.

---

🙌 Contributing

• Small, atomic PRs using Conventional Commits.
• Keep local & CI gates green before review.
• Use auto-merge once checks pass.

---

💚 Donations & Sponsorship

Support open-source: your donations keep projects clean, secure, and evolving for the global community.

---

🔎 SEO Keywords

reusable github actions workflows, python typescript ci starter, node 20 eslint 9 prettier 3, ruff black mypy pytest, cyclonedx sbom cosign signing, codeql security analysis, branch protection auto merge, always green ci, monorepo friendly ci, strict local gates mirror

---

👤 Author

CoderDeltaLAN (Yosvel) GitHub: https://github.com/CoderDeltaLAN

---

📄 License

Released under the MIT License. See LICENSE.