opal-cli 0.1.0-rc1

Terminal-first GitLab pipeline runner with TUI, history browser, and embedded docs.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

# opal

[![Docs](https://img.shields.io/badge/docs-opal.cloudflavor.io-0ea5e9)](https://opal.cloudflavor.io)

Opal is a terminal-first GitLab pipeline runner for local debugging. It parses `.gitlab-ci.yml`, evaluates a practical local-runner subset of GitLab filters/rules, executes jobs in local containers, and provides a keyboard-driven UI for run history, logs, artifacts, and docs.

## Demo

### Opal Run

[![asciicast](https://asciinema.org/a/LxDIEb87AyDtDM5c.svg)](https://asciinema.org/a/LxDIEb87AyDtDM5c)

### Opal Plan

[![asciicast](https://asciinema.org/a/6rP1p3H4vtA7Orr8.svg)](https://asciinema.org/a/6rP1p3H4vtA7Orr8)

### Opal Run --no-tui

[![asciicast](https://asciinema.org/a/2Q2mFyHkwXMoI9e0.svg)](https://asciinema.org/a/2Q2mFyHkwXMoI9e0)

### Opal View

[![asciicast](https://asciinema.org/a/3eTpVFphkhQKDZB9.svg)](https://asciinema.org/a/3eTpVFphkhQKDZB9)

## Features

- `opal run` executes a practical local-runner subset of GitLab pipelines, including `rules`, `workflow:rules`, `needs`, `dependencies`, artifacts, cache, services, and matrix jobs.
- `opal plan` prints the evaluated DAG without starting containers.
- `opal view` opens the history/log browser for previous runs.
- The TUI includes embedded markdown docs, help overlays, pager integration, and history/resource browsing. Press `?` inside the TUI to open the built-in documentation viewer.
- GitLab-style predefined job metadata is injected into job environments, including `CI_JOB_NAME`, `CI_JOB_NAME_SLUG`, `CI_JOB_STAGE`, `CI_PROJECT_DIR`, and `CI_PIPELINE_ID`.
- Supported local engines: `docker`, `podman`, Apple `container`, and `orbstack`.
- `nerdctl` remains available as a Linux-oriented engine option when the underlying `containerd` environment is directly usable.

## Quick Start

```bash
cargo install opal-cli
opal run
```

This installs the executable as `opal` on your system.

For a local checkout during development, use:

```bash
cargo install --path .
```

Common entry points:

```bash
opal run
opal run --no-tui
opal plan
opal view
```

When `opal plan` runs in an interactive terminal, it now opens in your pager by default. Use `--no-pager` to print directly or `--json` for machine-readable output.

By default, Opal expects `.gitlab-ci.yml` in the current working directory and prepares each job from a snapshot of that current working tree.

Default engine selection:

- macOS: `auto` uses Apple `container`
- Linux: `auto` uses `podman`

You can override the `auto` default in config with:

```toml
[engine]
default = "docker"
```

Preview the DAG without execution:

```bash
opal plan --workdir . --pipeline .gitlab-ci.yml
```

Limit planning or execution to specific jobs plus their required upstream dependencies:

```bash
opal plan --workdir . --pipeline .gitlab-ci.yml --job package-linux
opal run --workdir . --pipeline .gitlab-ci.yml --job lint
```

The full user-facing command surface, engine behavior, and runtime usage now live in the docs set rather than in this README.

## Testing

Run the fixture suite with:

```bash
./scripts/test-pipelines.sh
```

The script writes logs under `tests-temp/test-pipeline-logs/`.

Useful overrides:

- `OPAL_BIN`
- `OPAL_TEST_COMMAND`
- `OPAL_TEST_ARGS`

Example:

```bash
OPAL_BIN=target/debug/opal OPAL_TEST_ARGS='--no-tui --engine docker' ./scripts/test-pipelines.sh
```

For the current fixture matrix and scenario descriptions, see `pipelines/tests/README.md`.

## Releasing

Build release artifacts with:

```bash
./scripts/build-release-artifacts.sh
```

Artifacts are written under `releases/`.

Package validation commands:

```bash
cargo package --list
cargo publish --dry-run
```

Release-candidate preparation notes live in `release/rc-checklist.md`.

## Documentation

Read the hosted docs at:

- `https://opal.cloudflavor.io`

Key references in the repo docs set:

- `docs/quickstart.md`
- `docs/cli.md`
- `docs/ui.md`
- `docs/plan.md`
- `docs/pipeline.md`
- `docs/gitlab-parity.md`

Release-candidate preparation notes live outside the embedded docs set in `release/rc-checklist.md`.

Use `docs/gitlab-parity.md` for the exact supported surface and known divergences from GitLab Runner/GitLab CI.
For exact runtime usage details, especially host env forwarding and repository secrets, see `docs/pipeline.md`.

The `docs/` directory is embedded into the Opal binary at build time and can be opened from the TUI with `?`.

## License

Licensed under the Apache License, Version 2.0. See `LICENSE`.