cidx

CIDX - CI with Declarative eXecution

CIDX is two tools in one:

1. CI/CD Abstraction Layer - Write once, run everywhere (Local, GitHub Actions, GitLab CI, Jenkins)
2. Git Workflow Facilitator - Human-friendly commands that wrap git complexity

The Problem

CI/CD Pain:

• You write the same tool configurations 3-4 times (Local, CI, pre-commit)
• Each CI platform has different syntax
• Configuration drift between local and CI

Git Pain:

• Git commands are designed by kernel devs, for kernel devs
• checkout does 3 different things, reset has 5 modes
• Common workflows require 4-5 commands

The Solution

                    CIDX
                     │
        ┌────────────┴────────────┐
        │                         │
   CI/CD Layer              Git Workflow
        │                         │
   cidx.toml                 cidx action
   cidx run                  cidx branch
   cidx check                cidx demo

Part 1: CI/CD Abstraction Layer

Convention over Configuration - Just name the container, CIDX knows the rest.

Quick Start

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

# Initialize
cidx init

# Run
cidx run security   # Run all security containers
cidx run trivy      # Run specific container
cidx run ci         # Run full CI pipeline

Configuration

One file, all environments:

# cidx.toml

# Enable security containers (CIDX knows Docker images, volumes, commands)
[security]
containers = ["trivy", "gitleaks", "semgrep"]

# Enable code quality containers
[code]
containers = ["megalinter"]

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

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

How It Works

CI/CD Runner (GitLab/GitHub/Jenkins/Local)
                    │
                  CIDX
                    │
            ┌───────┴───────┐
            │               │
       cidx.toml     Built-in Presets
            │               │
            └───────┬───────┘
                    │
              Docker Containers

• 15+ built-in presets - Trivy, Gitleaks, Semgrep, MegaLinter, etc.
• Auto-detection - Knows images, volumes, commands for each tool
• 5-line configs - Most projects need less than 10 lines

Workflow Validation

Ensure your local config matches CI:

cidx check workflow  # Validates cidx.toml ↔ GitHub Actions

Part 2: Git Workflow Facilitator

Human-friendly git - Common workflows in single commands.

Why?

Action Commands

# PR Workflow
cidx action pr create "feat: new feature"  # Create branch + draft PR
cidx action pr ready                        # Mark PR ready for review
cidx action pr merge                        # Merge + cleanup

# Development
cidx action cpw -m "message"               # Commit, Push, Watch CI
cidx action release create                 # Bump version + create release

Branch Management

# List branches with status
cidx branch list              # All branches with PR/merge status
cidx branch list --stale      # Branches inactive > 30 days
cidx branch list --merged     # Already merged branches
cidx branch list --orphan     # PR closed without merge

# Cleanup
cidx branch cleanup           # Dry-run: show what would be deleted
cidx branch cleanup -x        # Actually delete merged branches
cidx branch cleanup --stale   # Include stale branches

# PR Status
cidx branch pr                # Show PR status for current branch
cidx branch pr -w             # Watch CI checks until complete
cidx branch pr -o             # Open PR in browser

Status Dashboard

Interactive TUI showing project context at a glance:

cidx status                   # Launch interactive dashboard
cidx status --no-tui          # Simple text output (auto in CI)

Features:

• GitHub account and authentication status
• Current branch with ahead/behind commits
• Local changes (staged, modified, untracked)
• PR info with CI check status
• Watch mode: press w to auto-refresh every 5s

Keyboard shortcuts:

• w - Toggle watch mode (polls CI checks)
• r - Refresh status
• q - Quit

Environment detection: Automatically uses simple text output in CI environments (GitHub Actions, GitLab CI, Jenkins, etc.) to avoid blocking pipelines.

Demo

cidx demo spinner             # See the snake spinner animation
cidx demo spinner -d 10       # Run for 10 seconds

Development Workflow

CIDX uses trunk-based development with manual releases:

# 1. Create feature branch with draft PR
cidx action pr create "feat: add new feature"

# 2. Work and commit
cidx action cpw -m "feat: implement feature"

# 3. Mark ready and merge
cidx action pr ready
cidx action pr merge

# 4. After 3-5 PRs, create release
cidx action release create

Documentation

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE