cidx

CIDX — One CI config for local and CI

CIDX is a container-first CI runner. One cidx.toml, same checks locally and in CI.

Everything runs in containers (Docker or Podman). Nothing is installed on your machine, your workspace stays clean, and 40+ built-in presets handle common tools out of the box.

CIDX is dogfooded on this repository: CIDX builds CIDX.

Quick Start

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

# Check your environment
cidx doctor

# Initialize (auto-detects Go/Python/Rust/Node.js/Ansible)
cidx init

# Generate CI workflow
cidx generate github -o .github/workflows/cidx.yml
# or: cidx generate gitlab -o .gitlab-ci.yml

# Preview and run
cidx run --dry-run ci
cidx run ci

That's it. cidx init detects your project type, picks the right presets, and generates a cidx.toml. cidx generate produces the CI platform file. Three commands to a working pipeline.

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.

Commands

Running pipelines

cidx run security              # Run a phase
cidx run trivy                 # Run a single tool
cidx run ci                    # Run a named pipeline
cidx run --parallel security   # Parallel execution (local)
cidx run --quiet ci            # Show logs only on failure
cidx run --dry-run ci          # Preview without executing
cidx run --backend podman ci   # Force Podman backend

PR lifecycle

cidx pr create "feat: description"   # Create branch + draft PR
cidx cpw -m "commit message"        # Commit, push, watch CI
cidx pr watch -q                     # Watch CI checks (quiet)
cidx pr status                       # Show PR info
cidx pr ready                        # Mark ready for review
cidx pr merge                        # Squash merge + cleanup
cidx pr open                         # Open in browser

Diagnostics

cidx doctor                    # Validate environment
cidx check drift               # Compare cidx.toml vs CI workflow
cidx validate                  # Validate config file

Presets

cidx preset list               # List all 40+ presets by phase
cidx preset info trivy         # Show preset details
cidx preset search security    # Search presets
cidx preset check-updates      # Check for newer image versions
cidx preset audit              # CVE + update compliance report
cidx preset scan               # Scan images for vulnerabilities

CI generation

cidx generate github           # Generate GitHub Actions workflow
cidx generate gitlab           # Generate GitLab CI configuration
cidx generate github -o .github/workflows/cidx.yml  # Write to file

Branch management

cidx branch list               # All branches with status
cidx branch list --stale       # Inactive > 30 days
cidx branch cleanup            # Dry-run cleanup
cidx branch cleanup -x         # Delete merged branches

Releases

cidx action tag prepare        # Generate version and message
cidx action tag create         # Create and push tag
cidx action release create     # Bump version, tag, push, release

Maintenance

cidx cleanup                   # Remove stopped cidx containers
cidx status                    # Interactive TUI dashboard

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 registry check    # Verify DHI access
cidx registry login    # Authenticate

Documentation

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

Contributing

See CONTRIBUTING.md.

License

MIT