DuoOps

Toolset for Explainable and Sustainable CI on GitLab.

DuoOps is a developer-focused CLI and Web Portal designed to make GitLab CI/CD pipelines more transparent, debuggable, and environmentally sustainable. It leverages AI agents to explain failures and provides tools to measure and visualize the carbon footprint of your CI jobs.

🌟 Key Features

• 🤖 AI-Powered Troubleshooting: Ask questions about your pipelines in plain English. The AI agent (powered by GitLab Duo or Google Vertex AI) analyzes logs, identifies root causes, and suggests fixes.
• 🔍 Deep Pipeline Inspection: View pipeline status, job details, and logs directly from your terminal.
• 🌱 Carbon Measurement: Calculate the carbon emissions of your CI jobs based on CPU/RAM usage timeseries. Track your environmental impact over time.
• 📊 Web Portal: A local React-based dashboard to visualize pipeline metrics and chat with the AI assistant in a rich interface.
• 🧠 Intelligent Summarization: Automatically summarizes long job logs using sub-agents to provide concise failure analysis without token limit issues.

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0
• GitLab Account: A Personal Access Token with api scope.
• (Optional) Google Cloud SDK: Required only for BigQuery metrics.
  • Install the gcloud CLI.
  • Authenticate: gcloud auth application-default login

Installation

# Clone the repository
git clone https://github.com/youneslaaroussi/duoops.git
cd duoops

# Install dependencies
pnpm install

# Build the project
pnpm build

# Link the CLI globally
npm link

Configuration

Run the interactive initialization command to set up your credentials:

duoops init

This will prompt you for:

• GitLab URL (default: https://gitlab.com)
• GitLab Personal Access Token
• (Optional) BigQuery settings for sustainability tracking

Alternatively, you can configure DuoOps using environment variables:

| Variable | Description | | :--- | :--- | | GITLAB_TOKEN | Your GitLab Personal Access Token | | GITLAB_URL | GitLab instance URL (default: https://gitlab.com) | | DUOOPS_AI_PROVIDER | AI Provider: gitlab (default) or vertex | | GCP_PROJECT_ID | Google Cloud Project ID (required for Vertex AI) | | GCP_LOCATION | Google Cloud Location (default: us-central1) |

📖 Usage

1. Inspect Pipelines

List recent pipelines for a project:

duoops pipelines list <project-id-or-path>
# Example: duoops pipelines list my-group/my-project

2. Analyze Jobs & Logs

Get details and logs for a specific job:

duoops job show <project-id> <job-id>
# Example: duoops job show 12345 987654

3. Ask the AI Agent

Troubleshoot failures or ask general CI questions:

duoops ask "Why did the last pipeline fail?"
duoops ask "How do I optimize my .gitlab-ci.yml for faster builds?"

4. Measure Carbon Footprint

Calculate emissions for a job using CPU/RAM usage data (JSON timeseries):

duoops measure calculate \
  --provider gcp \
  --machine e2-standard-4 \
  --region us-central1 \
  --cpu-timeseries ./data/cpu.json \
  --ram-used-timeseries ./data/ram.json \
  --out-md report.md

This will output a report to the console and save a Markdown summary to report.md.

Persist from CI: To save results to BigQuery when the measure component runs in GitLab CI, set these CI/CD variables (masked where appropriate):

| Variable | Description | | :--- | :--- | | DUOOPS_BQ_DATASET | BigQuery dataset name | | DUOOPS_BQ_TABLE | BigQuery table name | | GCP_PROJECT_ID | Google Cloud project ID |

The same GCP service account used for the measure component (e.g. GCP_SA_KEY_BASE64) is used for BigQuery; the component sets GOOGLE_APPLICATION_CREDENTIALS so the BigQuery client can authenticate. Ensure the table exists (e.g. run duoops init locally with BigQuery enabled to create it).

Act on recent data

Run duoops act [project-id] [--limit N] to fetch recent CI carbon metrics from BigQuery and get the agent's recommendations (e.g. set a budget, optimize jobs, suggest .gitlab-ci changes). Project ID can be omitted if set via duoops init.

5. Launch the Web Portal

Start the local dashboard to visualize metrics and chat:

duoops portal

Open your browser to http://localhost:3000.

🛠️ Development

Project Structure

• bin/: CLI entry point.
• src/commands/: Oclif command implementations.
• src/lib/: Core logic (AI agents, GitLab client, Measurement tools).
• portal/: React frontend application.

Running Tests

pnpm test

Building for Production

pnpm build

This compiles the TypeScript CLI and builds the React frontend, copying assets to the dist/ directory.

📄 License

MIT