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.

Why CI/CD Hub?

Who It's For

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

Java

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:

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

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

Elastic License 2.0. See LICENSE.