Opal/ documentation source ↗
Opal / local pipelines

Run GitLab-style pipelines locally.

Opal is a terminal-first, AI-capable local runner for GitLab pipelines. It evaluates .gitlab-ci.yml, keeps local Git-aware behavior where it matters, and gives you fast ways to run, inspect, debug, and analyze jobs without pushing to a remote runner.

Opal terminal interface showing pipeline jobs and logs
Built for

local debugging

Run against the working tree you are actively editing instead of waiting on a remote runner.

Main modes

run · run --no-tui · plan · view

Use interactive runs, plain terminal runs, DAG-only planning, or post-run history browsing depending on the task.

AI-assisted

job analysis in the TUI

Analyze a selected job, preview the exact prompt Opal sends, and keep troubleshooting inside the same terminal workflow.

Install

# Download the build that matches your machine.

Install from crates.io

cargo install opal-cli

# Install with Homebrew on macOS

brew tap cloudflavor/tap
brew install cloudflavor/tap/opal-cli

Open install docs → · Browse Opal releases on GitHub ↗

For a prebuilt binary, choose macOS Apple Silicon, Linux ARM64 or Linux x86_64 from the selected release. Obtain its archive and checksums together upstream, verify before extracting, then place opal in a user-owned directory on your PATH. GitHub access permissions apply.

Demos / original terminal recordings

# The main ways people actually use Opal.

# Opal AI Troubleshooting · Codex

Analyze the selected job with the Codex backend, inspect the rendered prompt, and keep troubleshooting inside the TUI.

press a inside opal run

Open docs →

Download original .cast recording ↓

Original recordings from the Opal documentation, self-hosted here with asciinema-player 3.18.1 (Apache 2.0). Recording sources.

Reference

# Use these docs when you need precision, not just a demo.

# CLI Reference

See the complete command-line surface, flags, environment variables, and common examples.

opal --help
Open docs →

# AI Troubleshooting

Analyze selected jobs with Codex or Ollama, inspect the exact rendered prompt, and keep troubleshooting inside the terminal.

a / A in the TUI
Open docs →

# AI Configuration

Configure the active AI backend, prompt template files, Ollama host/model settings, and Codex CLI command/model overrides.

.opal/config.toml
Open docs →

# Pipeline Model

Understand how Opal evaluates includes, rules, services, caches, artifacts, and local workspaces.

.gitlab-ci.yml
Open docs →
Opal / reference

Open the part you need.

Complete repository documentation: installation, workflows, configuration, and reference.

Opal Documentation →

Opal executes GitLab-style CI pipelines locally so you can iterate without pushing to a remote runner. This documentation gives you the high-level tour of how the system is structured and where to look for specific topics.

Install →

cargo install --path crates/opal

Quick Start →

cargo install --path crates/opal

Pipeline Model →

This document describes how Opal interprets `.gitlab-ci.yml` and schedules jobs locally.

Opal Plan →

`opal plan` lets you explore the pipeline graph without spinning up containers. It uses the same parser and rule evaluation as `opal run`, so the output is a faithful preview of what will execute when you launch a real run.

Opal Configuration →

Opal reads a layered `config.toml` to customize runtime behavior and automatically handle container registry authentication. Two locations are checked (later entries override earlier ones):

AI Configuration →

This page documents how to configure Opal's AI-assisted job troubleshooting backends, prompt files, and saved-analysis behavior.

AI Troubleshooting →

This page tracks Opal's AI-assisted job troubleshooting feature.

GitLab Feature Parity →

This page tracks which `.gitlab-ci.yml` features Opal currently recognizes and how that compares with GitLab's official CI/CD YAML surface.

User Interface →

The Ratatui-based UI is optimized for keyboard navigation. This document complements the in-app shortcut list and explains each pane in detail.

CLI Reference →

This page documents the current Opal command-line surface directly from the implementation.

Opal MCP Agent Playbook →

This document is meant to be handed to a coding agent such as Codex.

Storage And Local State →

This page documents where Opal stores local state, how per-job workspaces are prepared, how cache and artifacts are laid out on disk, and how project-level `.opal` content interacts with global configuration.

Technical Debt →

Architecture and maintenance notes for Opal.

Documentation snapshot from https://github.com/cloudflavor/opal at revision 194af1f1fbef, not a current-release selector.