{"id":50969161,"url":"https://github.com/cloudflavor/opal","last_synced_at":"2026-06-19T00:02:03.221Z","repository":{"id":344930793,"uuid":"821457439","full_name":"cloudflavor/opal","owner":"cloudflavor","description":"Run Gitlab pipelines locally using the Apple Container CLI for MacOS and podman/docker/orbstack/nerdctl for linux","archived":false,"fork":false,"pushed_at":"2026-04-25T11:49:03.000Z","size":2420,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-25T12:07:50.828Z","etag":null,"topics":["apple-container","gitlab","gitlab-pipeline","gitlab-runner","local-development","local-development-environment","macos-containers"],"latest_commit_sha":null,"homepage":"https://opal.cloudflavor.io","language":"Rust","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudflavor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-06-28T15:25:59.000Z","updated_at":"2026-04-25T11:49:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cloudflavor/opal","commit_stats":null,"previous_names":["cloudflavor/opal"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/cloudflavor/opal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflavor%2Fopal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflavor%2Fopal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflavor%2Fopal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflavor%2Fopal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudflavor","download_url":"https://codeload.github.com/cloudflavor/opal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflavor%2Fopal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34511617,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple-container","gitlab","gitlab-pipeline","gitlab-runner","local-development","local-development-environment","macos-containers"],"created_at":"2026-06-19T00:02:01.453Z","updated_at":"2026-06-19T00:02:03.062Z","avatar_url":"https://github.com/cloudflavor.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# opal\n\n[![Docs](https://img.shields.io/badge/docs-opal.cloudflavor.io-0ea5e9)](https://opal.cloudflavor.io)\n\nOpal is a terminal-first, AI-capable 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, docs, and job analysis.\n\n## Demo\n\n### Opal Run\n\n[![asciicast](https://asciinema.org/a/sRnoaxug8FIBIC4b.svg)](https://asciinema.org/a/sRnoaxug8FIBIC4b)\n\n### Opal Plan\n\n[![asciicast](https://asciinema.org/a/sQJqanuJ2Jj6dejt.svg)](https://asciinema.org/a/sQJqanuJ2Jj6dejt)\n\n### Opal Run --no-tui\n\n[![asciicast](https://asciinema.org/a/5Kr6vJBbkKv1wlhF.svg)](https://asciinema.org/a/5Kr6vJBbkKv1wlhF)\n\n### Opal View\n\n[![asciicast](https://asciinema.org/a/GLTgUvewqvfDB7Qz.svg)](https://asciinema.org/a/GLTgUvewqvfDB7Qz)\n\n### Opal AI Troubleshooting · Codex\n\n[![asciicast](https://asciinema.org/a/876637.svg)](https://asciinema.org/a/876637)\n\n### Opal AI Troubleshooting · Ollama\n\n[![asciicast](https://asciinema.org/a/876581.svg)](https://asciinema.org/a/876581)\n\n## Features\n\n- `opal run` executes a practical local-runner subset of GitLab pipelines, including `rules`, `workflow:rules`, `needs`, `dependencies`, artifacts, cache, services, and matrix jobs.\n- `opal plan` prints the evaluated DAG without starting containers.\n- `opal view` opens the history/log browser for previous runs.\n- The TUI can analyze a selected job with AI backends, preview the exact rendered prompt, and keep troubleshooting inside the terminal.\n- 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.\n- 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`.\n- Supported local engines: `docker`, `podman`, Apple `container`, and `orbstack`.\n- `nerdctl` remains available as a Linux-oriented engine option when the underlying `containerd` environment is directly usable.\n- On macOS, Apple `container` is a strong default for Opal because it runs each container in its own lightweight VM instead of routing all containers through one shared Linux VM, which improves per-job isolation while keeping a lightweight local workflow.\n\n## Quick Start\n\n```bash\ncargo install --path crates/opal\nopal run\n```\n\nThis installs the executable as `opal` on your system.\n\nFor a local checkout during development, use:\n\n```bash\ncargo install --path crates/opal\n```\n\nCommon entry points:\n\n```bash\nopal run\nopal run --no-tui\nopal plan\nopal view\nopal completions zsh\nopal mcp\n```\n\nThe MCP server currently exposes planning, background operations with status polling for run, rerun, log-search, and heavy log-inspection requests, run inspection, history listing with status, job, branch, pipeline-file, and date-range filters, failed-job lookup, run-diff, plan-explanation, and engine-status tools for agent workflows. History-oriented MCP views are scoped to the current checkout, so `latest` and resource browsing do not mix runs from unrelated repositories sharing the same `OPAL_HOME`.\n\nWhen `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.\n\nBy default, Opal expects `.gitlab-ci.yml` in the current working directory and prepares each job from a snapshot of that current working tree.\n\nDefault engine selection:\n\n- macOS: `auto` uses Apple `container`\n- Linux: `auto` uses `podman`\n\nYou can override the `auto` default in config with:\n\n```toml\n[engine]\ndefault = \"docker\"\n```\n\nPreview the DAG without execution:\n\n```bash\nopal plan --workdir . --pipeline .gitlab-ci.yml\n```\n\nLimit planning or execution to specific jobs plus their required upstream dependencies:\n\n```bash\nopal plan --workdir . --pipeline .gitlab-ci.yml --job package-linux\nopal run --job rust-checks\n```\n\nThe full user-facing command surface, engine behavior, and runtime usage now live in the docs set rather than in this README.\n\n## Testing\n\nRun the fixture suite with:\n\n```bash\n./scripts/test-pipelines.sh\n```\n\nThe script writes logs under `tests-temp/test-pipeline-logs/`.\n\nUseful overrides:\n\n- `OPAL_BIN`\n- `OPAL_TEST_COMMAND`\n- `OPAL_TEST_ARGS`\n\nExample:\n\n```bash\nOPAL_BIN=target/debug/opal OPAL_TEST_ARGS='--no-tui --engine docker' ./scripts/test-pipelines.sh\n```\n\nFor the current fixture matrix and scenario descriptions, see `pipelines/tests/README.md`.\n\n## AI troubleshooting\n\nOpal can analyze a selected job directly from the TUI.\n\n- `a` starts analysis for the selected job and toggles the analysis view once it exists\n- `A` previews the exact rendered prompt that Opal will send\n- `o` opens the current log or analysis view in your pager\n\nThis also works when you load a past job in `opal view`.\n\nCurrent backends:\n\n- `ollama`\n- `claude`\n- `codex`\n\nSee:\n\n- `docs/ai.md` for usage, current behavior, and provider notes\n- `docs/ai-config.md` for backend selection, prompt files, and AI configuration\n\n## Releasing\n\nBuild release artifacts with:\n\n```bash\nbash ./scripts/build-release-artifacts.sh\n```\n\nContainerized Linux release builds pass `--dns` to the container runtime by default (`CONTAINER_DNS=1.1.1.1`). Override it as needed, for example:\n\n```bash\nCONTAINER_DNS=8.8.8.8 bash ./scripts/build-release-artifacts.sh\n```\n\nContainerized builds use repo-local Rust caches by default:\n\n- `HOST_CARGO_HOME=target/.container-cache/cargo-home`\n- `HOST_RUSTUP_HOME=target/.container-cache/rustup-home`\n\nOverride those paths only if you intentionally want a different cache location.\n\nBuild Linux release artifacts with Docker and write them to a local folder:\n\n```bash\ndocker build \\\n  --target release-artifacts \\\n  --build-arg RELEASE_TARGETS=x86_64-unknown-linux-gnu \\\n  --output type=local,dest=./releases/docker \\\n  .\n```\n\nTo build both Linux release targets in one run, pass:\n\n```bash\n--build-arg RELEASE_TARGETS=x86_64-unknown-linux-gnu,aarch64-unknown-linux-gnu\n```\n\nTo build just the macOS Apple Silicon release tarball locally and print its checksum for manual upload:\n\n```bash\nCI_COMMIT_TAG=v0.1.0-rc6 bash ./scripts/build-macos-release-asset.sh\n```\n\nArtifacts are written under `releases/`.\n\nTag-driven release publishing expectations:\n\n- release tags must match `crates/opal/Cargo.toml`'s package version, allowing an optional leading `v`\n- plain `opal run` does not turn into a tag pipeline just because `HEAD` is tagged; set `CI_COMMIT_TAG` or `GIT_COMMIT_TAG` explicitly when you want local tag-pipeline behavior\n- Linux release artifacts are split into separate `arm64` and `amd64` release jobs so each target runs in its own matching container image platform\n- macOS Apple Silicon release artifacts run in `release-artifacts:macos-aarch64` on runners tagged `macos-arm64`\n- `CARGO_REGISTRY_TOKEN` enables automatic crates.io publishing from the tag pipeline\n- `GITHUB_TOKEN` plus `GITHUB_REPOSITORY=owner/repo` enables automatic GitHub release publishing with the built tarballs and release notes\n- if `release/notes/\u003ctag\u003e.md` or `release/notes/\u003cversion\u003e.md` exists, that file becomes the GitHub release body; otherwise the release job composes notes from the generated per-platform archive summaries\n\nTo run the tag pipeline locally:\n\n```bash\nCI_COMMIT_TAG=v0.1.0-rc3 opal run --no-tui\n```\n\nPackage validation commands:\n\n```bash\ncargo package --list\ncargo publish --dry-run\n```\n\nRelease-candidate preparation notes live in `release/rc-checklist.md`.\n\n## Documentation\n\nRead the hosted docs at:\n\n- `https://opal.cloudflavor.io`\n\nKey references in the repo docs set:\n\n- `docs/quickstart.md`\n- `docs/cli.md`\n- `docs/ui.md`\n- `docs/ai.md`\n- `docs/plan.md`\n- `docs/pipeline.md`\n- `docs/gitlab-parity.md`\n\nRelease-candidate preparation notes live outside the embedded docs set in `release/rc-checklist.md`.\n\nUse `docs/gitlab-parity.md` for the exact supported surface and known divergences from GitLab Runner/GitLab CI.\nFor exact runtime usage details, especially host env forwarding and repository secrets, see `docs/pipeline.md`.\n\nThe `docs/` directory is embedded into the Opal binary at build time and can be opened from the TUI with `?`.\n\n## License\n\nLicensed under the Apache License, Version 2.0. See `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflavor%2Fopal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudflavor%2Fopal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflavor%2Fopal/lists"}