cidx

README

CIDX — Integrate any project into CI in two commands

CIDX detects your existing project, generates a CI config, and runs the same checks locally and in CI. Two commands, one cidx.toml, containers handle the rest.

Everything runs in Docker or Podman — nothing is installed on your machine. 40+ built-in presets cover common security, code quality, test, and build tools out of the box.

Installation

Install with Go (latest):

go install github.com/cidx-org/cidx/cmd/cidx@latest

Or download a release binary from Releases.

For other methods, see docs/getting-started/installation.md.

Quick Start

Two paths, two commands each.

Run locally:

cidx init        # Detect project, generate cidx.toml
cidx run ci      # Execute the full pipeline in containers

Plug into CI:

cidx init                                              # Detect project, generate cidx.toml
cidx generate github -o .github/workflows/cidx.yml    # Generate CI workflow
# or: cidx generate gitlab -o .gitlab-ci.yml

cidx init detects your project type (Go, Python, Rust, Node.js, Ansible), picks the right presets, and generates a cidx.toml. Same config, same checks, locally and in CI.

Example configs

Go project (auto-generated by cidx init)

[security]
containers = ["trivy", "gitleaks", "gosec"]

[code]
containers = ["golangci-lint", "gofmt", "prettier", "commitizen"]

[test]
containers = ["go-test"]

[build]
containers = ["go-build"]

[pipelines.ci]
phases = ["security", "code", "test", "build"]

[pipelines.pr]
phases = ["security", "code", "test"]

Minimal

[security]
containers = ["trivy", "gitleaks"]

[pipelines.ci]
phases = ["security"]

With overrides

[security]
containers = ["trivy"]

[containers.trivy]
severity = "HIGH,CRITICAL"
exit_code = 1
timeout = "10m"

How It Works

cidx.toml          Built-in Presets       Custom Presets
(what to run)   +  (how to run it)    +  (.cidx/presets.toml)
     │                   │                      │
     └───────────┬───────┘──────────────────────┘
                 │
          Docker / Podman

You declare what to run. CIDX resolves how — images, commands, volumes, environment, timeouts, pull policy.

Core Commands

cidx init                      # Detect project, generate config
cidx run ci                    # Execute a pipeline
cidx run security              # Run a single phase
cidx run trivy                 # Run a single tool
cidx run --dry-run ci          # Preview without executing
cidx run --parallel security   # Parallel execution (local)
cidx generate github           # Generate GitHub Actions workflow
cidx generate gitlab           # Generate GitLab CI config
cidx validate                  # Validate config file
cidx check drift               # Compare cidx.toml vs CI workflow
cidx doctor                    # Validate environment
cidx preset list               # List all 40+ presets by phase
cidx preset info trivy         # Show preset details
cidx status                    # Interactive TUI dashboard

Workflow Helpers

CIDX also ships developer workflow commands, dogfooded daily on this repo. These are secondary to the core integration engine but useful for the full dev cycle.

# PR lifecycle (cidx repo pr)
cidx repo pr create "feat: description"   # Create branch + draft PR
cidx repo cpw -m "commit message"         # Commit, push, watch CI
cidx repo pr watch -q                     # Watch CI checks (quiet)
cidx repo pr merge                        # Squash merge + cleanup
cidx repo branch list --stale             # Find stale branches
cidx repo branch cleanup -x              # Delete merged branches

# Workflow runs (no PR required, e.g. direct push to main)
cidx repo workflow watch                  # Watch latest run on current branch
cidx repo workflow watch --branch main    # Watch latest run on main
cidx repo workflow watch <run-id>         # Watch a specific run by ID

# Releases (cidx release)
cidx release tag prepare                  # Generate version and message
cidx release tag create                   # Create and push tag
cidx release create                       # Full release workflow

# Security (cidx security)
cidx security vuln list                   # List vulnerability exceptions
cidx security registry check              # Verify DHI access

# Maintenance
cidx cleanup                              # Remove stopped containers

Shortcuts: cidx pr, cidx cpw, and cidx workflow work as aliases for cidx repo pr, cidx repo cpw, and cidx repo workflow.

Configuration

Custom presets

Define new tools or override built-in ones:

• User-level: ~/.config/cidx/presets.toml
• Project-level: .cidx/presets.toml

[presets.my-scanner]
image = "myorg/scanner:latest"
command = "scan ."
phase = "security"
timeout = "15m"
pull_policy = "if-not-present"

Container options

[containers.trivy]
severity = "HIGH,CRITICAL"    # Preset option
timeout = "10m"               # Per-container timeout
pull_policy = "always"        # always, if-not-present, never

Version pinning

required_version = "1.3.1"

Built-in images

Presets default to Docker Hardened Images where available — smaller attack surface, SBOM included, provenance metadata.

DHI requires Docker Hub credentials. In CI, set DOCKERHUB_USERNAME and DOCKERHUB_TOKEN.

cidx security registry check    # Verify DHI access
cidx security registry login    # Authenticate

Documentation

• Installation
• Configuration
• CI Integration
• Available Tools
• CLI Reference
• Philosophy
• Development Notes

Example configs

• examples/cidx.toml — minimal starter (run security + code)
• examples/cidx-advanced.toml — small custom config with overrides
• examples/cidx-complete.toml — full catalog: every section, every option, every default rendered explicit with pedagogical comments. Cherry-pick from here.

Contributing

See CONTRIBUTING.md.

License

MIT