CI-Copilot

A multi-agent framework that generates, modifies, and debugs CI/CD pipelines through conversation.

Quick Start · Docs · Report Bug · Request Feature

---

Demo

CI-Copilot scanning a repo, building a CI plan, and generating a GitHub Actions workflow — all through conversation.

---

Why CI-Copilot?

The problem. Most teams have one or two people who actually know how the CI system works — how to structure jobs, which actions to trust, how to wire up caching, where the gotchas are in Jenkins vs. GitHub Actions. Everyone else copies YAML from another repo and hopes it works. When something breaks, the same senior engineers get pulled in. And if the org decides to move platforms, the whole thing gets rewritten from scratch.

Meanwhile, CI/CD is just the start. Teams also need build and release pipelines, infra automation jobs, scheduled maintenance tasks, deployment workflows — all of which follow the same pattern: someone senior configures it once, and everyone else is afraid to touch it.

What CI-Copilot brings to the table.

CI-Copilot isn't limited to CI/CD pipelines. It can create any kind of job or workflow you'd normally need a senior engineer to set up — whether that's a CI pipeline, a build and release workflow, an infrastructure automation job, or a scheduled maintenance task. You describe what you need, and it handles the rest: detection, planning, rendering, validation, and commit.

Three things make this different:

1. It works like a senior engineer, available to everyone. A junior DevOps engineer using CI-Copilot gets access to the same depth of knowledge — best practices, platform-specific nuances, security patterns, caching strategies — that would normally take years to build up. It levels the playing field.

2. It's not just CI/CD. Need a nightly database backup job in Jenkins? A Terraform plan-and-apply workflow in GitHub Actions? A release pipeline with approval gates? CI-Copilot can build it. The system understands CI platforms deeply, not just one narrow use case.

3. It reduces the need for a dedicated team. When any engineer can generate, modify, and debug workflows through conversation — with governance and approval gates built in — you no longer need a dedicated CI/CD or build & release team to handle every request. The bottleneck disappears.

Under the hood, it's a multi-agent system where each capability (detection, validation, rendering) is a separate agent that can be extended or replaced independently. And nothing gets committed without your explicit approval — governance is baked in, not bolted on.

---

Key Features

Available now:

• Intelligent context detection — scans your repo to identify runtime, package manager, dependencies, Dockerfiles, and existing CI configs across 8 languages
• CI intent inference — builds a structured pipeline spec (CISpec) with stages, capabilities, enforcement levels, and triggers via LLM analysis
• Policy validation — validates the plan against security policies, license compliance, and best practices before rendering
• Production-ready rendering — generates idiomatic GitHub Actions YAML with proper action versions, caching, and dependency graphs
• Self-correcting refinement — validates with actionlint, checks schema compliance, and auto-corrects through a reflection loop
• Automated PR creation — commits the workflow and opens a pull request directly on your repo
• Human-in-the-loop governance — approval gates after plan generation and before the final commit
• Rich interactive UI — A2UI-powered components for CI plan review, pipeline summaries, and approval workflows

Coming soon:

• Multi-platform support — generate pipelines for Jenkins, GitLab CI, CircleCI, Azure Pipelines, and more from the same intent
• Workflow modification — modify and update existing pipelines through conversation, platform-agnostic
• Job debugging — diagnose and fix failing CI jobs from a prompt
• CI knowledge base — deep, built-in expertise across CI platforms for troubleshooting and optimization

---

Architecture

The system is a hierarchy of agents built with LangGraph, communicating via the A2A protocol.

graph TD
    User([You]) -->|"setup CI for my-org/app"| Sup[Supervisor Agent]
    
    Sup -->|delegates| GenSup[Generation Supervisor]
    
    GenSup --> CD[Context Detector]
    GenSup --> PV[Policy Validator]
    GenSup --> RA[Renderer]
    
    CD -->|GitHub MCP| GH[(GitHub API)]
    CD -.->|approval gate| User
    RA -->|commit + PR| GH
    RA -.->|approval gate| User
    
    style Sup fill:#4A90D9,stroke:#2E6BA6,color:#fff
    style GenSup fill:#7B68EE,stroke:#5A4FCF,color:#fff
    style CD fill:#50C878,stroke:#3BA366,color:#fff
    style PV fill:#FFB347,stroke:#E09530,color:#fff
    style RA fill:#FF6B6B,stroke:#E04A4A,color:#fff

Loading

The flow in practice:

1. You ask for a CI pipeline (e.g. "Create GitHub Actions for my-org/payments-api")
2. Context Detector connects to GitHub via MCP, fetches the repo, and analyzes it — language, runtime version, dependencies, test/lint tools, Dockerfiles, existing CI
3. It builds a CI specification and presents a plan for your approval
4. Policy Validator checks the plan against security and compliance rules
5. Renderer converts the spec to GitHub Actions YAML, validates with actionlint, and refines through a reflection loop
6. You review the final output. On approval, it commits to a branch and opens a PR

---

Table of Contents

• Why CI-Copilot?
• Key Features
• Architecture
• Tech Stack
• Getting Started
• Usage
• Agent Details
• Project Structure
• Roadmap
• Contributing
• FAQ
• License
• Contact
• Acknowledgments

---

Tech Stack

Category	Technologies
Agent Framework	LangChain + LangGraph
Language	Python 3.12+
CI Platform	GitHub Actions
LLM Providers	OpenAI · Anthropic · Google Gemini · AWS Bedrock · Azure OpenAI
Protocol	A2A · A2UI
GitHub Integration	GitHub MCP Server
Validation	actionlint · ruamel.yaml
Infrastructure	Docker · uv · Uvicorn · Starlette

---

Getting Started

Prerequisites

• Python 3.12+
• uv package manager
• An OpenAI API key (or key for another supported provider)
• A GitHub Personal Access Token with repo scope
• Docker + Docker Compose (if using the Docker quick start)

Installation

Quick Start with Docker Compose (recommended)

No cloning required. You just need two files: docker-compose.yml and .env.

1. Create a docker-compose.yml — copy the contents from docker-compose.yml in this repo, or use:

services:
  ci-copilot:
    image: talkopsai/ci-copilot:latest
    container_name: ci-copilot
    ports:
      - "10102:10102"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}
      # LLM Configuration — example below uses OpenAI.
      # If using Anthropic, Gemini, or another provider, change the
      # LLM_PROVIDER and LLM_MODEL values accordingly.
      # See .env.example for supported providers and model names.
      - LLM_PROVIDER=openai
      - LLM_MODEL=gpt-4o-mini
      - LLM_HIGHER_PROVIDER=openai
      - LLM_HIGHER_MODEL=gpt-5-mini
      - LLM_DEEPAGENT_PROVIDER=openai
      - LLM_DEEPAGENT_MODEL=o4-mini
      - LOG_LEVEL=INFO
    restart: unless-stopped
    networks:
      - ci-copilot-net

  talkops-ui:
    image: talkopsai/talkops:latest
    container_name: talkops-ui
    environment:
      - TALKOPS_CI_COPILOT_URL=http://localhost:10102
    ports:
      - "8080:80"
    depends_on:
      - ci-copilot
    restart: unless-stopped
    networks:
      - ci-copilot-net

networks:
  ci-copilot-net:
    driver: bridge

2. Create a .env file in the same directory with your API keys:

OPENAI_API_KEY=your_openai_api_key_here
GITHUB_PERSONAL_ACCESS_TOKEN=your_github_pat_here

3. Start everything:

docker compose up -d

# CI-Copilot running at http://localhost:10102
# TalkOps UI running at http://localhost:8080

That's it. Open the TalkOps UI and start talking to CI-Copilot.

From Source

If you want to run CI-Copilot directly (for development or customization):

1. Install uv for dependency management.

2. Clone the repo and create a virtual environment with Python 3.12:

git clone https://github.com/talkops-ai/ci-copilot.git
cd ci-copilot

uv venv --python=3.12
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows

3. Install dependencies from pyproject.toml:

uv pip install -e .

4. Create a .env file and add your environment variables:

cp .env.example .env
# Edit .env — at minimum set OPENAI_API_KEY and GITHUB_PERSONAL_ACCESS_TOKEN

All available configuration options can be found in ci_copilot/config/default.py. You can set any of these via your .env file to customize CI-Copilot's behavior.

5. Start the A2A server:

uv run --active ci-copilot \
  --host localhost \
  --port 10102 \
  --agent-card ci_copilot/card/ci_copilot.json

To interact with CI-Copilot, we recommend using the TalkOps UI client. Pull and run it with Docker:

docker run -d \
  --name talkops-ui \
  -e TALKOPS_CI_COPILOT_URL=http://localhost:10102 \
  -p 8080:80 \
  talkops-ui:latest

Set TALKOPS_CI_COPILOT_URL to wherever your CI-Copilot server is listening. Then open http://localhost:8080 in your browser and start with something like: "Create a CI pipeline for my-org/my-app"

---

Usage

Basic

Create ci/cd pipeline for talkops-ai/ci-copilot

The system handles detection, planning, validation, rendering, and PR creation. You approve the plan and the final output.

With specific requirements

Setup CI for my-org/payments-api with security scanning,
Docker image builds on push to main, and 80% coverage threshold.

Agent Details

Each agent has a defined scope and its own set of tools.

Supervisor Agent

Entry point. Routes requests — CI/CD tasks go to the Generation Supervisor, everything else gets handled directly (greetings, out-of-scope).

Tools: transfer_to_ci_generation, request_human_input

Generation Supervisor

Orchestrates the detect → validate → render flow using a LangGraph state machine (CIPipelineState). Manages handoffs between the sub-agents.

Tools: transfer_context_to_renderer, transfer_to_renderer, complete_workflow

Context Detector

Connects to GitHub via MCP and runs a thorough analysis of the target repo:

Tool	What it does
fetch_repository_information	Repo metadata — default branch, language, visibility
fetch_repository_files	Pulls manifest files, Dockerfiles, CI configs
detect_runtime_and_package_manager	Identifies language + package manager from manifests
extract_project_dependencies	LLM-powered dep extraction with CI usage classification
check_for_existing_ci	Detects existing CI across GitHub Actions, Jenkins, GitLab CI, etc.
infer_ci_capabilities	Generates a full CISpec — stages, capabilities, triggers, service deps

Supports: Node.js, Python, Go, Java, Rust, Ruby, PHP, .NET.

After building the spec, it presents a CI plan for your approval (first HITL gate).

Policy Validator

Checks the plan before rendering.

Tools: validate_security_policies, check_license_compliance, validate_ci_best_practices, calculate_policy_compliance_score

Renderer

Takes the approved spec and turns it into real YAML:

Tool	What it does
intent_to_commands	Maps CI capabilities to concrete shell commands
plan_workflow	Structures jobs, stages, and dependency graphs
render_workflows	Generates the final GitHub Actions YAML
workflow_refiner	Validates with actionlint, applies corrections via reflection loop
generate_workflow_explanation	Produces a human-readable pipeline summary
commit_and_create_pr	Commits to a branch and opens a PR

Shows you the final pipeline for approval before committing (second HITL gate).

---

Project Structure

ci-copilot/
├── ci_copilot/
│   ├── server.py                      # A2A server entry point (Uvicorn + Starlette)
│   ├── card/
│   │   └── ci_copilot.json            # A2A agent card
│   ├── config/
│   │   ├── config.py                  # Config management (env → defaults → overrides)
│   │   └── default.py                 # Default values
│   ├── core/
│   │   ├── ci_copilot_executor.py     # A2A task executor
│   │   ├── agents/
│   │   │   ├── supervisor_agent.py    # Supervisor (router)
│   │   │   ├── base.py               # Base agent class
│   │   │   └── ci_generation/
│   │   │       ├── generation_supervisor.py
│   │   │       └── github_ci/
│   │   │           ├── context_detector_agent.py
│   │   │           ├── policy_validator_agent.py
│   │   │           ├── renderer_agent.py
│   │   │           ├── context_detector_tool/   # Tools + prompts + HITL middleware
│   │   │           ├── renderer_tool/           # Tools + prompts + workflow schemas
│   │   │           └── policy_validator_tool/   # Validation tools
│   │   ├── a2ui/                      # Rich UI components (A2UI builder)
│   │   ├── hitl/                      # Human-in-the-loop infrastructure
│   │   └── state/
│   │       └── ci_pipeline_state.py   # LangGraph state schemas
│   └── utils/                         # Logger, MCP client, LLM init helpers
├── Dockerfile                         # Multi-stage build (Python 3.12 + actionlint)
├── docker-compose.yml                 # Full stack: CI-Copilot + TalkOps UI
├── pyproject.toml                     # Metadata, dependencies, build config
└── uv.lock                           # Locked dependencies

---

Roadmap

Phase 1 — Pipeline Generation (shipped):

• Multi-agent pipeline generation framework
• GitHub Actions support with automated PR creation
• Multi-language context detection (Node.js, Python, Go, Java, Rust, Ruby, PHP, .NET)
• LLM-powered CI spec inference
• Human-in-the-loop approval gates
• Policy validation (security, compliance, best practices)
• Workflow refinement via actionlint + reflection loop
• A2A protocol + A2UI interactive components
• Multi-provider LLM support (OpenAI, Anthropic, Gemini, Bedrock, Azure)
• Docker deployment

Phase 2 — Multi-Platform (in progress):

• Jenkins pipeline generation
• GitLab CI support
• CircleCI / Azure Pipelines / Bitbucket Pipelines
• CI spec persistence (.talkops/intent.yaml) for iterative updates

Phase 3 — Workflow Operations:

• Modify existing workflows from natural language instructions
• Debug failing CI jobs from a prompt
• Platform-agnostic workflow management (read, update, delete across CI systems)
• Built-in governance for critical operations

Phase 4 — CI Intelligence:

• Deep CI platform knowledge base (best practices, common pitfalls, optimization)
• Pipeline monitoring and drift detection
• Self-healing pipelines
• Custom agent plugin system

See open issues for the full list.

---

Contributing

Contributions are welcome. The process is straightforward:

1. Fork the repo
2. Create a branch (git checkout -b feature/your-feature)
3. Make your changes and commit
4. Push and open a PR

If you're considering something bigger, open an issue first so we can align on the approach.

See CONTRIBUTING.md for detailed guidelines.

---

FAQ

Does it support anything besides GitHub Actions?

Not yet. GitHub Actions is the only supported platform right now. GitLab CI and Jenkins are next.

Which LLMs work?

OpenAI, Anthropic, Google Gemini, AWS Bedrock, and Azure OpenAI. Set LLM_PROVIDER and LLM_MODEL in your .env.

Does it work with private repos?

Yes — your GITHUB_PERSONAL_ACCESS_TOKEN needs repo scope.

What if it can't detect my stack?

It asks you. The Context Detector has a human-in-the-loop fallback — if detection confidence is low, it prompts for clarification before proceeding.

Will it commit code without asking?

No. Two approval gates: (1) after plan generation, (2) before commit. Both require your explicit sign-off.

How do I connect a client?

CI-Copilot speaks the A2A protocol. Any A2A client works. The included docker-compose.yml ships with TalkOps UI at localhost:8080.

---

License

Apache 2.0 — see LICENSE.

---

Contact

TalkOps AI — github.com/talkops-ai

Project: github.com/talkops-ai/ci-copilot

Discord: Join the community

---

Acknowledgments

• LangChain + LangGraph — agent orchestration
• Google A2A Protocol — agent-to-agent communication
• A2UI — interactive UI protocol
• GitHub MCP Server — GitHub API via Model Context Protocol
• actionlint — workflow validation
• uv — Python package management