aios-core
Version:
Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework
765 lines (583 loc) • 20.9 kB
Markdown
id: ci-cd-configuration
name: Configure CI/CD Pipeline
agent: github-devops
category: devops
complexity: high
tools:
- github-cli # Manage workflows and repository settings
- coderabbit-free # Automated code review (FREE tier)
checklists:
- github-devops-checklist.md
# Configure CI/CD Pipeline
## Purpose
To set up a complete, production-ready CI/CD pipeline for a repository, including linting, testing, building, code review (CodeRabbit Free), and deployment automation.
## Supported CI Providers
- **GitHub Actions** (primary, recommended)
- **GitLab CI/CD**
- **CircleCI**
- **Jenkins** (basic support)
## Input
### Required Parameters
- **repository_path**: `string`
- **Description**: Local path or GitHub URL of the repository
- **Example**: `/path/to/project` or `https://github.com/user/repo`
- **Validation**: Must be valid Git repository
- **ci_provider**: `string`
- **Description**: CI/CD provider to configure
- **Options**: `"github-actions"`, `"gitlab-ci"`, `"circleci"`, `"jenkins"`
- **Default**: `"github-actions"`
- **project_type**: `string`
- **Description**: Type of project (determines pipeline stages)
- **Options**: `"nodejs"`, `"python"`, `"fullstack"`, `"monorepo"`
- **Required**: true
### Optional Parameters
- **testing_framework**: `string`
- **Description**: Primary testing framework
- **Examples**: `"jest"`, `"pytest"`, `"vitest"`, `"mocha"`
- **Auto-detect**: true (scans package.json or requirements.txt)
- **deployment_target**: `string`
- **Description**: Where to deploy
- **Options**: `"vercel"`, `"netlify"`, `"aws"`, `"none"`
- **Default**: `"none"`
- **enable_coderabbit**: `boolean`
- **Description**: Enable CodeRabbit Free for automated code review
- **Default**: `true`
- **Note**: **FREE tier** - No cost, no API keys needed for public repos
- **branch_protection**: `boolean`
- **Description**: Enable branch protection rules
- **Default**: `true`
- **Rules**: Require PR, require status checks, no force push
- **required_checks**: `array<string>`
- **Description**: Status checks that must pass
- **Default**: `["lint", "test", "build"]`
- **secrets**: `object`
- **Description**: Environment secrets (will be stored securely)
- **Example**: `{ VERCEL_TOKEN: "xxx", DATABASE_URL: "postgres://..." }`
## Output
- **workflow_files**: `array<string>`
- **Description**: Created workflow/config files
- **Example**: `[".github/workflows/ci.yml", ".github/workflows/deploy.yml"]`
- **branch_protection_rules**: `object`
- **Description**: Applied branch protection settings
- **Structure**: `{ branch, required_checks, enforce_admins, allow_force_push }`
- **coderabbit_config**: `object` (if enabled)
- **Description**: CodeRabbit configuration
- **Structure**: `{ enabled: true, config_file: ".coderabbit.yaml", integration_status: "active" }`
- **secrets_configured**: `array<string>`
- **Description**: List of secrets successfully stored
- **Note**: Values not included (security)
- **pipeline_url**: `string`
- **Description**: URL to view pipeline runs
- **Example**: `"https://github.com/user/repo/actions"`
- **README_section**: `string`
- **Description**: Markdown section to add to README.md
- **Content**: CI/CD badges, status, setup instructions
## Process
### Phase 1: Repository Analysis & Validation (2 min)
1. **Validate Repository**
- Check if valid Git repository
- Verify remote origin exists
- Check CI provider compatibility
2. **Detect Project Structure**
- Auto-detect project type (if not provided)
- Scan for package.json, requirements.txt, pom.xml, etc.
- Identify testing framework
- Identify build commands
3. **Check Existing CI Configuration**
- Look for existing workflows
- Warn if overwriting: "⚠️ Found existing CI config. Backup created at: {path}"
### Phase 2: CodeRabbit Free Setup (2 min) 🆓
**Note**: CodeRabbit Free is **100% FREE** for public repositories. No API keys, no credit card, no costs.
4. **Install CodeRabbit GitHub App**
- Guide user: "To enable CodeRabbit Free:
1. Visit: https://github.com/apps/coderabbitai
2. Click 'Install' (FREE for public repos)
3. Grant access to repository: {repo_name}
4. Return here when done"
- Wait for user confirmation
- Verify installation via GitHub API
5. **Create CodeRabbit Configuration**
- Generate `.coderabbit.yaml`:
```yaml
# CodeRabbit Free Configuration
# 🆓 FREE for public repositories - No costs, no limits
language: "en-US"
reviews:
profile: "chill" # balanced review depth
request_changes_workflow: false
high_level_summary: true
poem: false
review_status: true
collapse_walkthrough: false
auto_review:
enabled: true
ignore_title_keywords:
- "WIP"
- "DO NOT REVIEW"
chat:
auto_reply: true
# Focus areas (adjust based on project type)
focus:
- security
- performance
- best_practices
- testing
- documentation
# Ignore patterns
ignore:
- "**/*.min.js"
- "**/*.min.css"
- "**/dist/**"
- "**/build/**"
- "**/.next/**"
- "**/node_modules/**"
- "**/.git/**"
```
- Commit and push `.coderabbit.yaml`
- Log: "✅ CodeRabbit Free configured (Focus: security, performance, best practices)"
6. **Add CodeRabbit Commands to README**
- Document available commands:
```markdown
## Code Review (CodeRabbit Free 🆓)
**Automatic Reviews**: CodeRabbit automatically reviews all PRs
**Manual Commands** (comment on PR):
- `@coderabbitai review` - Request full review
- `@coderabbitai summary` - Get PR summary
- `@coderabbitai resolve` - Mark suggestions as resolved
- `@coderabbitai help` - Show available commands
**Local Pre-Commit Check** (optional):
```bash
# Install CodeRabbit CLI (optional, for local checks)
npm install -g @coderabbitai/cli
# Run pre-commit review
coderabbit --prompt-only -t uncommitted
```
[CodeRabbit Docs](https://docs.coderabbit.ai)
```
### Phase 3: GitHub Actions Workflow Creation (5 min)
7. **Create Lint + Test + Build Workflow**
- Generate `.github/workflows/ci.yml`:
```yaml
name: CI Pipeline
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main, develop ]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run linter
run: npm run lint
test:
runs-on: ubuntu-latest
needs: lint
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test -- --coverage
- name: Upload coverage
uses: codecov/codecov-action@v3
with:
files: ./coverage/coverage-final.json
build:
runs-on: ubuntu-latest
needs: test
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build project
run: npm run build
- name: Upload build artifacts
uses: actions/upload-artifact@v3
with:
name: build
path: dist/
```
8. **Create Deployment Workflow** (if deployment_target provided)
- Generate `.github/workflows/deploy.yml`:
```yaml
name: Deploy
on:
push:
branches: [ main ]
workflow_dispatch:
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Deploy to {deployment_target}
uses: {deployment_action}
with:
token: ${{ secrets.DEPLOY_TOKEN }}
```
### Phase 4: Branch Protection Rules (3 min)
9. **Configure Branch Protection** (if enabled)
- Use GitHub API to set rules on `main`:
- Require pull request reviews (1 approval)
- Require status checks to pass:
- `lint`
- `test`
- `build`
- `coderabbitai` (CodeRabbit review)
- Enforce for administrators: false (for emergency fixes)
- Require linear history: true
- Allow force pushes: false
- Allow deletions: false
10. **Store Secrets** (if provided)
- Use GitHub CLI to set secrets:
```bash
gh secret set VERCEL_TOKEN --body="xxx"
gh secret set DATABASE_URL --body="postgres://..."
```
- Verify secrets stored: `gh secret list`
### Phase 5: Documentation & Testing (3 min)
11. **Update README.md**
- Add CI/CD badges:
```markdown
[](https://github.com/user/repo/actions/workflows/ci.yml)
[](https://github.com/apps/coderabbitai)
```
- Add CI/CD section (from output)
12. **Create Test PR**
- Create branch: `ci-cd-test-{timestamp}`
- Make trivial change (e.g., update README)
- Push and create PR
- Verify:
- CI workflow triggers
- All checks run
- CodeRabbit reviews PR
- Branch protection enforced
- Close PR after validation
13. **Generate Setup Report**
- Document what was configured
- List workflow files created
- Show pipeline URL
- Confirm CodeRabbit active
- List next steps
## Checklist
### Pre-conditions
- [ ] Repository is valid Git repository
- **Validation**: `.git` directory exists
- **Error**: "Not a Git repository"
- [ ] CI provider is supported
- **Validation**: `ci_provider in ["github-actions", "gitlab-ci", "circleci", "jenkins"]`
- **Error**: "CI provider '{provider}' not supported"
- [ ] Project has package.json or equivalent
- **Validation**: File exists at root
- **Error**: "Cannot detect project type. Add package.json or specify project_type manually"
### Post-conditions
- [ ] Workflow files created and committed
- **Validation**: Files exist and are tracked by Git
- **Test**: `git ls-files | grep -E "\.github/workflows|\.gitlab-ci\.yml"`
- [ ] CodeRabbit configuration valid (if enabled)
- **Validation**: `.coderabbit.yaml` is valid YAML
- **Test**: `yamllint .coderabbit.yaml`
- [ ] Branch protection active (if enabled)
- **Validation**: GitHub API returns protection rules
- **Test**: `gh api repos/{owner}/{repo}/branches/main/protection`
- [ ] Test PR passes all checks
- **Validation**: All required checks green
- **Manual Check**: true
### Acceptance Criteria
- [ ] CI pipeline runs on every push
- **Type**: acceptance
- **Test**: Push to branch → workflow triggers
- [ ] CodeRabbit reviews all PRs automatically (if enabled)
- **Type**: acceptance
- **Manual Check**: true
- **Test**: Create PR → CodeRabbit comments within 2 min
- [ ] Branch protection prevents direct pushes to main
- **Type**: acceptance
- **Test**: Try `git push origin main` → rejected
## Templates
### README CI/CD Section
```markdown
## CI/CD Pipeline
This repository uses automated CI/CD with {ci_provider}.
### Status
[](https://github.com/{owner}/{repo}/actions/workflows/ci.yml)
{deployment_badge if applicable}
### Pipeline Stages
1. **Lint**: ESLint + Prettier
2. **Test**: {testing_framework} with coverage
3. **Build**: Production build
{4. **Deploy**: Automatic deployment to {deployment_target} (main branch only) if applicable}
### Code Review (CodeRabbit Free 🆓)
Every PR is automatically reviewed by [CodeRabbit](https://github.com/apps/coderabbitai):
- Security vulnerabilities
- Performance issues
- Best practices
- Test coverage
- Documentation
**Commands** (comment on PR):
- `@coderabbitai review` - Request review
- `@coderabbitai summary` - Get summary
- `@coderabbitai resolve` - Mark as resolved
### Branch Protection
- `main` branch requires:
- ✅ 1 PR approval
- ✅ All CI checks passing
- ✅ CodeRabbit review complete
- ❌ No direct pushes
- ❌ No force pushes
### Setup Instructions
1. Clone repository
2. Install dependencies: `npm install`
3. Run tests locally: `npm test`
4. Create feature branch: `git checkout -b feature/my-feature`
5. Make changes and commit
6. Push and create PR
7. Wait for CI + CodeRabbit review
8. Merge after approval
```
## Tools
- **github-cli**:
- **Version**: 2.0.0
- **Used For**: Manage workflows, secrets, branch protection
- **Required**: true (for GitHub Actions)
- **coderabbit-free**:
- **Version**: Latest (GitHub App)
- **Used For**: Automated code review on every PR
- **Cost**: $0 (FREE for public repositories)
- **Setup**: Install GitHub App (one-time, 2 minutes)
- **Features**:
- Automatic PR reviews
- Security scanning
- Performance analysis
- Best practices checks
- Interactive chat
- **Limitations**: None for open-source (FREE tier is full-featured)
## Performance
- **Duration Expected**: 15 minutes (including CodeRabbit setup)
- **Cost Estimated**: $0 (CodeRabbit Free is free, GitHub Actions has 2,000 free minutes/month)
- **Cacheable**: false (configuration is per-repository)
- **Parallelizable**: false (sequential setup required)
## Error Handling
- **Strategy**: retry + fallback
- **Fallback**: If CodeRabbit setup fails, continue without it (can add later)
- **Retry**:
- **Max Attempts**: 3
- **Backoff**: exponential
- **Backoff MS**: 2000
- **Abort Workflow**: false (continue even if optional features fail)
- **Notification**: log + setup report
## Metadata
- **Story**: Epic 10 (Critical Dependency Resolution)
- **Version**: 1.0.0
- **Dependencies**: `github-cli` tool
- **Author**: Brad Frost Clone
- **Created**: 2025-11-13
- **Updated**: 2025-11-13
- **Breaking Changes**: None (new task)
## Execution Modes
**Choose your execution mode:**
### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
- Autonomous decision making with logging
- Minimal user interaction
- **Best for:** Simple, deterministic tasks
### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
- Explicit decision checkpoints
- Educational explanations
- **Best for:** Learning, complex decisions
### 3. Pre-Flight Planning - Comprehensive Upfront Planning
- Task analysis phase (identify all ambiguities)
- Zero ambiguity execution
- **Best for:** Ambiguous requirements, critical work
**Parameter:** `mode` (optional, default: `interactive`)
## Task Definition (AIOS Task Format V1.0)
```yaml
task: ciCdConfiguration()
responsável: Gage (Automator)
responsavel_type: Agente
atomic_layer: Organism
**Entrada:**
- campo: task
tipo: string
origem: User Input
obrigatório: true
validação: Must be registered task
- campo: parameters
tipo: object
origem: User Input
obrigatório: false
validação: Valid task parameters
- campo: mode
tipo: string
origem: User Input
obrigatório: false
validação: yolo|interactive|pre-flight
**Saída:**
- campo: execution_result
tipo: object
destino: Memory
persistido: false
- campo: logs
tipo: array
destino: File (.ai/logs/*)
persistido: true
- campo: state
tipo: object
destino: State management
persistido: true
```
## Pre-Conditions
**Purpose:** Validate prerequisites BEFORE task execution (blocking)
**Checklist:**
```yaml
pre-conditions:
- [ ] Task is registered; required parameters provided; dependencies met
tipo: pre-condition
blocker: true
validação: |
Check task is registered; required parameters provided; dependencies met
error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
```
## Post-Conditions
**Purpose:** Validate execution success AFTER task completes
**Checklist:**
```yaml
post-conditions:
- [ ] Task completed; exit code 0; expected outputs created
tipo: post-condition
blocker: true
validação: |
Verify task completed; exit code 0; expected outputs created
error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
```
## Acceptance Criteria
**Purpose:** Definitive pass/fail criteria for task completion
**Checklist:**
```yaml
acceptance-criteria:
- [ ] Task completed as expected; side effects documented
tipo: acceptance-criterion
blocker: true
validação: |
Assert task completed as expected; side effects documented
error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
```
## Scripts
**Agent-specific code for this task:**
- **Script:** execute-task.js
- **Purpose:** Generic task execution wrapper
- **Language:** JavaScript
- **Location:** .aios-core/scripts/execute-task.js
## Error Handling
**Strategy:** retry
**Common Errors:**
1. **Error:** Task Not Found
- **Cause:** Specified task not registered in system
- **Resolution:** Verify task name and registration
- **Recovery:** List available tasks, suggest similar
2. **Error:** Invalid Parameters
- **Cause:** Task parameters do not match expected schema
- **Resolution:** Validate parameters against task definition
- **Recovery:** Provide parameter template, reject execution
3. **Error:** Execution Timeout
- **Cause:** Task exceeds maximum execution time
- **Resolution:** Optimize task or increase timeout
- **Recovery:** Kill task, cleanup resources, log state
## Performance
**Expected Metrics:**
```yaml
duration_expected: 5-15 min (estimated)
cost_estimated: $0.003-0.010
token_usage: ~3,000-10,000 tokens
```
**Optimization Notes:**
- Break into smaller workflows; implement checkpointing; use async processing where possible
## Usage Examples
### Example 1: Node.js Project with CodeRabbit
```bash
aios activate Otto # github-devops agent
aios ci-cd setup \
--repo="." \
--provider="github-actions" \
--type="nodejs" \
--enable-coderabbit=true \
--deploy="vercel"
```
**Output**: Complete CI/CD with CodeRabbit Free, Vercel deployment
### Example 2: Python Project (GitLab CI)
```bash
aios ci-cd setup \
--repo="/path/to/python-project" \
--provider="gitlab-ci" \
--type="python" \
--testing="pytest"
```
**Output**: GitLab CI pipeline with pytest
### Example 3: Monorepo with Turborepo
```bash
aios ci-cd setup \
--repo="." \
--provider="github-actions" \
--type="monorepo" \
--enable-coderabbit=true \
--branch-protection=true
```
**Output**: Optimized monorepo pipeline with caching
## CodeRabbit Free: Key Benefits 🆓
1. **Zero Cost**: FREE forever for public repos
2. **No Setup Complexity**: Just install GitHub App (2 minutes)
3. **Automatic Reviews**: Every PR reviewed within minutes
4. **Security Focus**: Catches vulnerabilities early
5. **Performance Insights**: Identifies bottlenecks
6. **Best Practices**: Enforces code quality standards
7. **Interactive**: Chat with CodeRabbit about suggestions
**Why CodeRabbit Free?**
- Competitor (Copilot, CodeGuru) costs $10-19/month/user
- CodeRabbit Free: $0 for open-source
- Better security coverage than most paid tools
- Integrated with GitHub (no external tools needed)
**Related Tasks:**
- `release-management` - Automate releases after CI passes
- `pr-automation` - Help users create PRs with proper format
- `setup-repository` - Initialize repository with best practices