Imported from orchestrate-solutions/universal-ci (AGENTS.md). Install upstream with npx skills add orchestrate-solutions/universal-ci. Copyright stays with the author.

CI Agents for Universal CI

Universal CI runs consistently across different CI agents and platforms. The same configuration works everywhere - local development, cloud CI, containers, and more.

Every push is verified twice:

1. Locally via pre-push hook (before code leaves your machine)
2. Remotely via GitHub Actions (after code reaches the repository)

🏠 Local Agent (Development)

Run verification locally before pushing changes:

# macOS / Linux / WSL - Fully automated setup
curl -sL https://raw.githubusercontent.com/orchestrate-solutions/universal-ci/main/install-ci.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/orchestrate-solutions/universal-ci/main/install-ci.ps1 | iex

That's it. The installer handles everything automatically.

Then run your CI locally:

./run-ci.sh

☁️ GitHub Actions Agent

Use Universal CI in GitHub Actions workflows:

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Universal CI
        run: |
          curl -sL https://raw.githubusercontent.com/orchestrate-solutions/universal-ci/main/run-ci.sh -o run-ci.sh
          chmod +x run-ci.sh
          ./run-ci.sh

🐳 Docker Agent

Run in isolated containers for consistent environments:

# Using Docker directly
docker run --rm -v $(pwd):/workspace -w /workspace alpine:latest sh -c "
  apk add --no-cache curl bash git &&
  curl -sL https://raw.githubusercontent.com/orchestrate-solutions/universal-ci/main/run-ci.sh -o run-ci.sh &&
  chmod +x run-ci.sh &&
  ./run-ci.sh
"

# Using Docker Compose (generated by installer with --docker flag)
docker-compose -f docker-compose.ci.yml run ci

🖥️ Self-Hosted Agents

For enterprise environments with self-hosted runners:

# Install on your runner
curl -sL https://raw.githubusercontent.com/orchestrate-solutions/universal-ci/main/install-ci.sh | sh

# Configure for your environment
# Edit universal-ci.config.json as needed

# Run as part of your CI pipeline
./run-ci.sh

🌐 Supported Agent Types

⚙️ Agent Configuration

All agents use the same universal-ci.config.json configuration:

{
  "tasks": [
    {
      "name": "Install Dependencies",
      "working_directory": ".",
      "command": "npm ci",
      "stage": "test"
    },
    {
      "name": "Run Tests",
      "working_directory": ".",
      "command": "npm test",
      "stage": "test"
    }
  ]
}

Zero configuration differences between local and cloud execution.

Version Testing (Matrix Strategy)

Test across multiple versions without duplicating task definitions:

{
  "tasks": [
    {
      "name": "Test Python {version}",
      "working_directory": ".",
      "command": "python{version} -m pytest",
      "stage": "test",
      "versions": ["3.9", "3.10", "3.11", "3.12", "3.13"]
    }
  ]
}

This automatically creates 5 separate test runs (one for each Python version). The {version} placeholder is replaced with each value from the versions array.

Supported version testing:

• Python: python3.9, python3.10, etc.
• Node.js: node16, node18, node20, etc.
• Any tool: Just use {version} in the command

Conditional Task Execution

Run tasks only when conditions are true - perfect for different environments:

{
  "tasks": [
    {
      "name": "Test Locally",
      "working_directory": ".",
      "command": "npm test",
      "if": "env.CI == 'false'"
    },
    {
      "name": "Deploy to Staging",
      "working_directory": ".",
      "command": "npm run deploy:staging",
      "stage": "release",
      "if": "branch(develop)"
    },
    {
      "name": "Deploy to Production",
      "working_directory": ".",
      "command": "npm run deploy:prod",
      "stage": "release",
      "if": "${{ github.ref }} == 'refs/heads/main' && env.PRODUCTION == 'true'"
    }
  ]
}

Available Conditions:

• env.VAR_NAME - Environment variable value
• file(path) - File exists
• os(linux|macos|windows) - Operating system
• branch(name) - Current git branch
• ${{ github.ref }} - GitHub context (in GitHub Actions)
• Boolean logic: && (and), || (or), != (not equal), == (equal)

Interactive Mode (AI-First Automation)

Perfect for AI agents and automated workflows - get tasks as JSON and select which to run:

# AI reads available tasks
./run-ci.sh --list-tasks
# Output: {"tasks":[{"name":"Build","directory":".","command":"npm run build"},{"name":"Test",...}]}

# AI decides which tasks to execute
./run-ci.sh --select-tasks '["Lint","Test","Build"]'

# Approve tasks that require manual confirmation
./run-ci.sh --stage release --approve-task "Deploy to Production"

# Skip expensive tasks conditionally
./run-ci.sh --skip-task "Slow Integration Tests" --skip-task "E2E Tests"

Example: AI Agent Workflow

#!/bin/bash
# Get list of available tasks
TASKS=$(./run-ci.sh --list-tasks)

# AI analyzes tasks and build a selection strategy
# (In real scenario, this would be AI decision logic)
SELECTED='["Lint","Test","Build"]'

# Execute selected tasks
./run-ci.sh --select-tasks "$SELECTED"

# If release stage has approval tasks, request them
if echo "$TASKS" | grep -q 'requires_approval.*true'; then
  ./run-ci.sh --stage release \
    --approve-task "Deploy to Production" \
    --approve-task "Notify Stakeholders"
fi

🎯 Best Practices

• Test Locally First: Always run ./run-ci.sh locally before pushing
• Consistent Environments: Use Docker agents for reproducible builds
• Fast Feedback: Configure agents to fail fast on first error
• Parallel Execution: Split tasks across multiple agents when possible
• Caching: Leverage agent caching for dependencies (npm, pip, etc.)

Universal CI: The same verification, everywhere. 🚀

🤖 Semantic Versioning for Agents

Universal CI now supports automated semantic versioning. Agents can check the status of version bumps using the CLI:

# Get JSON analysis of current changes
./.github/scripts/semantic-version.sh --analyze

# Get suggested bump type
./.github/scripts/semantic-version.sh --bump-type

This outputs standard JSON that agents can parse to understand if their changes will trigger a patch, minor, or major version bump. /Users/jwink/Documents/universal-ci/AGENTS.md