CI/CD Hub

Centralized CI/CD for Java and Python repos with config-driven toggles, reusable workflows, and a single hub that runs pipelines across many repositories.

Note

Refactor In Progress - We're aligning CLI/registry integration and doc automation. Some commands may be incomplete. See STATUS.md for current state.

---

Why CI/CD Hub?

Problem	Solution
Hours writing YAML per repo	One CLI generates config + workflows in minutes
Copy-paste configs that drift	3-tier merge (defaults → hub → repo) keeps everything in sync
Manually configuring 10+ tools	Schema-validated config with profiles that auto-configure tools
Debugging cryptic CI failures	Triage bundles with prioritized, actionable reports

---

Who It's For

Audience	Use Case
Hub/Org Admins	Centralized standards across many repos
Teams	Consistent CI gates across Python and Java
Maintainers	Minimal YAML, reproducible workflows

Core Concepts

• Hub repo: hosts defaults, templates, workflows, and repo configs.
• Target repo: owns .ci-hub.yml for per-repo overrides.
• Merge order: defaults → hub config → repo config (repo wins).

CLI Flow (Short)

# Guided onboarding (interactive)
python -m cihub setup

# Or generate config + workflow directly
python -m cihub init --repo . --apply

# Run CI locally (uses .ci-hub.yml)
python -m cihub ci

Execution Modes

• Central mode: the hub clones repos and runs pipelines directly from a single workflow.
• Distributed mode: the hub dispatches workflows to each repo via caller templates and reusable workflows.

---

Pre-Push Validation

Run local checks before pushing:

cihub check              # Fast: lint, format, type, test (~30s)
cihub check --audit      # + links, adr, configs (~45s)
cihub check --security   # + bandit, pip-audit, trivy, gitleaks (~2min)
cihub check --full       # + templates, matrix, license, zizmor (~3min)
cihub check --all        # Everything including mutation (~15min)

Other validation commands:

cihub validate --repo .          # Validate .ci-hub.yml against schema
cihub run ruff --repo .          # Run one tool, emit JSON
cihub verify --remote            # Verify workflow contracts (requires gh auth)
cihub docs generate              # Regenerate CLI/config reference docs
cihub docs check                 # Verify docs are up to date

---

Toolchains

Python

Category	Tools
Testing	pytest, Hypothesis
Linting	Ruff, Black, isort
Types	mypy
Security	Bandit, pip-audit, Semgrep, Trivy
Mutation	mutmut
Container	Docker, SBOM

Java

Category	Tools
Testing	jqwik
Coverage	JaCoCo
Quality	Checkstyle, SpotBugs, PMD
Security	OWASP Dependency-Check, Semgrep, Trivy
Mutation	PITest
Container	Docker, SBOM

Shared (Both Languages)

Semgrep, Trivy, CodeQL, SBOM, Docker

Quick Start

Central mode

# Run all repos
gh workflow run hub-run-all.yml -R jguida941/ci-cd-hub

# Run by group
gh workflow run hub-run-all.yml -R jguida941/ci-cd-hub -f run_group=fixtures

Distributed mode

1. Create a PAT with repo + workflow scopes.
2. Set HUB_DISPATCH_TOKEN via CLI:

python -m cihub setup-secrets --all

3. In each target repo:

python -m cihub init --repo . --apply

4. Set dispatch_enabled: true in config/repos/<repo>.yaml.

Prerequisites

• Python 3.10+ (3.12 used in CI)
• GitHub Actions for workflow execution
• GitHub CLI (gh) recommended for dispatching workflows

Debugging & Triage

Analyze CI failures:

cihub triage --latest        # Triage most recent failed run
cihub triage --run <id>      # Triage specific run by ID

Environment flags for debugging:

Flag	Effect
CIHUB_DEBUG=True	Show tracebacks
CIHUB_VERBOSE=True	Show tool logs
CIHUB_DEBUG_CONTEXT=True	Show decision/context blocks
CIHUB_EMIT_TRIAGE=True	Write triage bundle to .cihub/

Triage outputs: .cihub/triage.json, priority.json, triage.md

Installation (local development)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements-dev.txt

Documentation

Doc	Description
Docs Index	Full map of guides, references, and development docs
Getting Started	Primary entry point for new users
CLI Reference	Generated from cihub docs generate
Config Reference	Generated from schema
Tools Reference	Tool registry and options
Troubleshooting	Common issues and fixes
Development Guide	Maintainer workflow
Current Status	Refactor progress

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

Elastic License 2.0. See LICENSE.