2026
v3.18.0 (2026-08-26)
Features
lunar policy ok-releasenow prints the Hub-rendered verdict block verbatim when the Lunar configuration setscustomization.ok_release_template, in place of the built-in summary line and the failing and bypassed check lists; when no template is configured, or the Hub cannot render one, the command prints its built-in output as before. Only the printed block changes — the verdict, the exit code, the polling progress messages, andlunar policy ok-prare unaffected. See Customizing theok-releaseverdict output.
Improvements
lunar policy ok-releaseandlunar policy ok-prno longer print the command's usage and flag list when they fail after their arguments have been parsed — an invalid component ID, an expired timeout, or an authentication failure — so the error and its remedy stay at the end of a CI log instead of being scrolled off by help text.lunar policy ok-releaseandlunar policy ok-prnow fail on the first response saying Lunar Hub has no component by that name, instead of polling every interval until--timeout— ten minutes by default — for the same verdict. Nothing in the run being gated creates a component, so waiting could not change the answer; the error names the invalid component ID and points at the Lunar catalog the name has to come from. An unknown component stays fatal under every--fail-openmode, and a component that exists but has not finished evaluating still polls to--timeoutas before.
Bug fixes
The CI Tracer now selects a component whose declared repository identity differs in letter case from the identity the CI environment reports: host, owner, and repository name are compared case-insensitively when matching components to the repository the job runs in, when resolving the names listed in
LUNAR_COMPONENT, and when falling back to a single component named after the repository. Previously a component authored asgithub.com/Acme/Apiin a checkout the Git platform reports asacme/apimatched nothing, so the job ran collectors for no component and collected nothing, without an error. A monorepo component's subdirectory path is still matched case-sensitively, because it is a file path, and branch matching is unchanged. See Case-insensitive repository identity matching.
v2.12.0 (2026-08-11)
Improvements
lunar policy ok-releaseandlunar policy ok-prnow print a loud warning when running in CI without a detectable workflow run ID — for example whenGITHUB_RUN_IDis absent and--workflow-idwas not passed — explaining how to pass--workflow-id; previously the gate silently blocked until its timeout.
v2.11.0 (2026-08-07)
Features
lunar setup bootstrapnow accepts--gitlab-grouptogether with--gitlab-tokento deposit a GitLab group access token — run once per top-level group — and--github-ownerto deposit per-organization GitHub App keys for multi-organization installs. At least one Git platform credential is now required:--github-app-pem, the GitLab pair, or both. Existing single-organization GitHub invocations are unchanged.
v2.10.0 (2026-08-04)
Features
lunar policy ok-releaseandlunar policy ok-praccept a new--fail-openflag to exit successfully instead of blocking when no verdict can be obtained: a bare--fail-opencovers an unreachable Hub, and--fail-open=timeoutor--fail-open=bothextend it to gate timeouts (the value must be attached with=). Authentication failures and an unknown component name stay fatal under every mode — a typo in a component name cannot silently pass — and a gate whose checks genuinely fail still blocks.lunar policy bypass-releaseandlunar policy bypass-prrecord a time-bound override of a component's release or PR/MR merge gate,lunar policy bypass-lslists a component's bypasses — including expired and revoked ones — andlunar policy bypass-rmrevokes one early.--reasonis recorded with the bypass,--forsets its duration, and--sha,--pr, and--policynarrow its scope; in CI, when neither--shanor--pris given, the bypass is scoped to the commit taken fromGITHUB_SHAorCI_COMMIT_SHA. See Break-glass gate bypasses.The new
lunar queuecommands inspect and clear the Hub's queue of script runs:lunar queue statusshows how many runs are queued by script type, andlunar queue clear <collectors|policies|catalogers|all>deletes queued runs — useful for recovering from a misconfiguration that filled the queue with work that can only fail and retry. Without--yes,queue clearprints what it would remove without deleting anything, and runs that are already executing are never deleted.
Improvements
The CI Tracer now fetches the component catalog from the Hub only when a CI job names a component, caches it per repository, and asks only for changes since its last fetch, removing redundant Hub round-trips on every run. The new
LUNAR_CATALOG_FULL_REFRESH_PERIODvariable (default15m) bounds how long a missed change can leave the cached catalog stale;0disables the periodic full refresh.
v2.8.0 (2026-07-29)
Bug fixes
Fetching scripts from a public repository under an owner with no configured SCM credentials no longer emits a warning per reference: the designed anonymous-access fallback is logged at debug level, so a
lunar collector devrun over a configuration referencing dozens of public plugin scripts no longer prints a wall of warnings that reads like a failure. A private repository under an unconfigured owner still fails loudly, with the error naming the missing credentials. See Public repositories without a GitHub App.lunar collector devandlunar cataloger devnow run code collectors from the component's subdirectory for monorepo components — the same working directory the Hub uses — instead of the repository root, so a collector no longer behaves differently in local development than in production. With--componentthe subdirectory must exist at the checked-out ref, and with--component-dirpointing inside a monorepo the component name (andLUNAR_COMPONENT_ID) now includes the subdirectory exactly as the Hub names it.An interrupted
lunar collector dev,lunar policy dev, orlunar cataloger devrun no longer poisons every later run withfailed to install draft config: ... configuration already exists. The throwaway draft configuration such a run leaves behind is now replaced on the next run instead of blocking it, so no manual deletion under~/.lunar/drafts/(orlunar clear-cache) is needed to recover.lunar policy ok-releaseandlunar policy ok-prno longer fail on a transient connection error partway through their poll. When the Hub becomes briefly unreachable after the poll has already reached it — for example during a load-balancer blip under load — the command now printstemporarily unable to reach remote server; retrying...and keeps polling until--timeoutinstead of aborting the gate. A server that is unreachable from the very first call, or any non-transient error, still fails immediately.
v2.7.0 (2026-07-21)
Improvements
lunar collector dev,lunar policy dev,lunar cataloger dev, andlunar hub pull --dry-runnow work with GitLab-hosted components and plugins: set the newLUNAR_GITLAB_TOKENenvironment variable (or let a configured Hub supply the credentials), and the CLI routes clone authentication, default-branch resolution, and wildcard component expansion to the matching SCM for each host, including GitLab's nested namespaces. With--component-dir, the component name is now derived from the checkout's actual remote host instead of the configured GitHub host.
Bug fixes
Fetching the component catalog from the Hub no longer fails with a gRPC
ResourceExhaustederror on very large catalogs: the maximum gRPC message size between the CLI, the CI Tracer, and the Hub is raised from 4 MB to 16 MiB, so the CI Tracer's periodic catalog refresh keeps working on installations with tens of thousands of components.
v2.6.2 (2026-07-17)
Features
The new
lunar setup bootstrapcommand performs the secret-deposit step of a Lunar Dedicated install: it generates the workload encryption key and the webhook secret, and deposits them together with the GitHub App private key (--github-app-pem) into the dedicated account's secret drop in AWS Secrets Manager, encrypted with the install's CMK. It requires--tenantand--regionfrom the coordinates packet, and can deposit cross-account by assuming the write-only deposit role with--deposit-role-arnand--external-id(which must be given together), so the secrets never pass through Earthly's systems. Re-runs are safe: the generated encryption key and webhook secret are write-once and never overwritten, while the GitHub App key is updated on every run, so rotating it is just a re-run. The generated webhook secret is printed exactly once — on the run that deposits it — to be set in the GitHub App's "Webhook secret" field.
Bug fixes
lunarand the CI Tracer now place their state, cache, and config directories under a writable temp-based path when running as a non-root user whose home directory is unset or resolves to the filesystem root, instead of failing withmkdir /.lunar: permission denied; a usable home directory still resolves to~/.lunar/as before.
v2.6.1 (2026-07-16)
Breaking changes
The
lunar grafana deploy-dashboardscommand is removed. Lunar's Grafana dashboards, datasources, and panel plugins are now installed by theghcr.io/earthly/lunar-dashboardsdeploy image — the Helm chart runs it automatically on install and upgrade, and the same image can be run directly with Docker or Podman against a Grafana you operate yourself — so no local CLI step or container runtime is involved in dashboard deployment anymore.
Improvements
lunar sql connection-stringaccepts a new--grafanaflag that prints the connection string for the read-only Grafana datasource role instead of the SQL API one.
Bug fixes
The CI Tracer now detects scheduled runs —
GITHUB_EVENT_NAME=scheduleon GitHub Actions,BUILDKITE_SOURCE=scheduleon Buildkite — and records their collections as periodic re-collections rather than CI collections pinned to the checked-out commit, so a scheduled pipeline no longer replaces the component's latest data with its own partial results. See Scheduled CI runs no longer overwrite component data.
v2.6.0 (2026-07-09)
Features
lunar-config.ymlcan now be validated before merge:lunar hub pull --dry-run <repo>runs the Hub's own load-and-validate pipeline — includinguses:plugin resolution and component repository checks — without applying anything, exiting non-zero on validation errors; it needs GitHub access but no Hub connection, so it can run as a CI check on pull requests. A companionlunar config schemacommand prints a JSON Schema for editor autocomplete.
Bug fixes
Fixed a CI/CD Tracer deadlock while configuring signal-heavy traced processes that could hang a build indefinitely and hold its runner until the CI timeout. The deadlock surfaced most often when the Hub was unreachable.
v2.5.0 (2026-07-08)
Features
New
lunar grafana deploy-dashboardscommand installs Lunar's Grafana dashboards, datasources, and panel plugins into a Grafana instance you operate (self-hosted or Grafana Cloud). The Grafana endpoint and credentials are supplied by the Hub, the dashboard version is matched to the running Hub automatically, and a Docker or Podman runtime is required locally.
Improvements
The Hub gRPC and HTTP ports now default to 443 when not configured, and
lunar ci-tracer runforwards the resolved Hub connection settings to the tracer process. A CI runner configured with onlyLUNAR_HUB_HOSTpreviously failed the Hub-configured check and could silently run without instrumentation.lunar collector devandlunar policy devnow work when the Lunar config is split acrosslunar-config.d/files, and fully local runs (--component-dirtogether with--script) no longer require GitHub or Hub credentials. Credential errors in the remaining modes now explain what to configure.
Bug fixes
The CI/CD Tracer now classifies Node.js-based GitHub Actions launched through a shebang entrypoint as steps; such actions were previously attributed as commands of the preceding step.
Fixed
sudofailing inside traced builds withThe "no new privileges" flag is set: the CI/CD Tracer no longer setsno_new_privson traced processes that holdCAP_SYS_ADMIN. Runningsudoor other setuid binaries under tracing requires a self-hosted runner running as root withCAP_SYS_ADMIN; on runners without the capability the previous behavior is unchanged.
v2.4.0 (2026-06-23)
Security
Updated high-severity Go dependencies (
golang.org/x/crypto,golang.org/x/net,golang.org/x/sys,github.com/jackc/pgx/v5) to patched versions in thelunarCLI and CI/CD Tracer build.
v2.3.2 (2026-06-19)
Bug fixes
Fixed collectors failing with
Hub connection details not providedwhen a collector image carrying CLI v2.2.0 or later runs against a Hub older than 2.3.1:lunar collectinside a collector now falls back to the legacy stdout output those Hubs expect. Out-of-bandlunar collect --componentinvocations still submit to the Hub directly.
v2.3.1 (2026-06-19)
Migrations and upgrade notes
The CI/CD Tracer's GitHub Action now lives at
earthly/lunar-ci-tracer(renamed fromearthly/lunar-ci-action) — update workflow references to the new name. The separatelunar-ci-agent-distbinary distribution is retired: install the tracer through thelunarCLI withlunar ci-tracer runorlunar ci-tracer install.
Bug fixes
Pull-request checks now post on GitHub Enterprise Server: the CI/CD Tracer records the repository's GitHub host with each CI collection, so the Hub posts the resulting checks against the right GitHub instance. See GitHub Enterprise Server and multi-organization support.
v2.3.0 (2026-06-19)
Features
New
lunar ci-tracer installcommand downloads and caches the CI/CD Tracer through the Hub without running it, for warming the cache at build time — for example when baking a runner image.The CI/CD Tracer now supports Buildkite. Start it from a Buildkite agent
commandhook to trace builds and run CI collectors; runs are collected even though Buildkite exposes no job or step boundaries, and settingLUNAR_COMPONENT_INFER=trueenables changed-path attribution for monorepo builds. See Buildkite support.The CI/CD Tracer resolves the GitHub host from the run environment (
GITHUB_SERVER_URLon GitHub Actions, or the git remote on Buildkite), so runs on GitHub Enterprise Server repositories are attributed to the right component with no extra configuration;LUNAR_GITHUB_HOSTremains available as an override. See GitHub Enterprise Server and multi-organization support.
v2.2.0 (2026-06-17)
Features
Unified CLI and CI/CD Tracer releases
The lunar CLI and the CI/CD Tracer (previously called the CI agent) now release together under a single version. There is no separate lunar-ci-agent binary to install: the CLI fetches, verifies, and caches the tracer through your Hub on first use, and later runs reuse the cache.
Start the tracer with the new lunar ci-tracer run command. It resolves the tracer version pinned into the CLI at build time (override with --version), downloads the binary through the Hub on a cache miss, verifies its digest, and caches it under ~/.lunar/bin (override with LUNAR_BIN_DIR). All other arguments are forwarded to the tracer unchanged.
Version numbering continues above both earlier release lines — the CLI was at v2.0.0 and the CI agent at v2.1.3 — which is why there is no v2.1.0.
New
--component <github.com/owner/repo>and--sha <commit>flags letlunar collectrun outside a traced CI job — for example in a CD pipeline — to attach additional component JSON to an existing component at a specific commit. The flags fall back toLUNAR_COMPONENT_IDandGITHUB_SHAwhen unset, and an optional--prassociates the write with a pull request. See Out-of-band collection.
Improvements
When
LUNAR_COMPONENT_INFER=trueis set, changed-path component inference on GitHub Actions now covers push events as well as pull requests, so a monorepo build on the default branch is attributed to the components whose files actually changed. See Monorepo support: path-scoped components.lunarcommands and the CI/CD Tracer automatically retry Hub requests interrupted by a brief Hub outage, such as a rolling restart during an upgrade, instead of failing the operation.The CI/CD Tracer resolves component default branches only for the repository it is tracing, instead of for every component at startup. This reduces GitHub API usage on busy runners and fixes Lunar config sync failures caused by exhausting the GitHub App rate limit.
Bug fixes
The CI/CD Tracer now bounds the Hub and GitHub API calls made from its tracing loop with timeouts, and job cancellation interrupts them. A stalled call could previously freeze the traced build or leave an orphaned tracer occupying a self-hosted runner after the job was cancelled.
Fixed a CI/CD Tracer deadlock triggered when a traced process exited while the tracer was still configuring it. The wedged tracer could leave a self-hosted runner reporting online while no longer running jobs.
The CI/CD Tracer no longer logs a warning for every fault signal seen in traced processes — managed runtimes such as the JVM, Go, and Node.js raise and handle these signals as part of normal operation. A crash is now reported only when a fault signal actually terminates the traced process.
v2.0.0 (2026-05-17)
Features
The new
lunar licencecommand group extracts Hub bootstrap artifacts from a licence JWT locally, before any Hub is running in the cluster:lunar licence verifyvalidates the licence against the trust list embedded in the binary and prints a summary;lunar licence pull-secretgenerates a KubernetesimagePullSecretmanifest for pulling Lunar images fromghcr.io(with--namespace/-n,--name, and--out/-o); andlunar licence registry-tokenprints the GHCR pull token for use withdocker login. All subcommands accept--licence-file, or theLUNAR_LICENCE_FILEenvironment variable.
Improvements
The CI/CD Tracer continues running when Hub-backed startup setup fails — fetching runtime logging configuration or completing the initial sync — instead of aborting the CI job; set
LUNAR_STRICT_MODE=trueto keep the previous fail-closed startup behavior.
Bug fixes
lunar collector dev --componentchecks out the branch configured for the component in the Hub catalog instead of always using the repository's default branch, and validates that the component exists in the catalog.The CI/CD Tracer retries its update checks while Lunar Hub has no current configuration published, instead of proceeding and later surfacing confusing "manifest not found" errors during observation.
v1.1.2 (2026-05-07)
Breaking changes
The CI/CD Tracer no longer accepts a GitHub personal access token for runtime authentication: the
LUNAR_GITHUB_TOKENruntime path is removed, and the tracer always uses GitHub App installation tokens vended by Lunar Hub, which was already the default path. RemoveLUNAR_GITHUB_TOKENfrom tracer environments; a Hub connection is now required for GitHub API access.
Features
The new
lunar diagnose bundlecommand captures a self-contained troubleshooting snapshot of a deployed Lunar stack — descriptions and logs for every Lunar pod plus database statistics — packaged as a singletar.gzfor sharing with support.
Improvements
CLI commands that take a component name —
lunar collector dev,lunar policy dev,lunar component get-json,lunar policy ok-release, andlunar policy ok-pr— fall back to theLUNAR_COMPONENT_IDenvironment variable when no flag or argument is given.lunar hub pullno longer runs global catalogers automatically on every configuration sync; pass the new--rerun-catalogers/-tflag to opt in, mirroring the existing--rerun-code-collectors/-lflag. Per-component catalogers are unaffected and keep firing on their own hooks.The new
LUNAR_INSTALL_FILE_MAX_DISK_SIZEsetting (for example200mor5gb) caps the disk space used by locally cached Lunar configuration versions, pruning the oldest unused versions first; the default0leaves size-based pruning disabled.The CI/CD Tracer now handles attaching to a CI job that is already running — for example when launched as a step inside a GitHub Actions job — initializing from the current step instead of dropping all events, and it reports readiness only after its initial configuration sync with Lunar Hub succeeds.
Bug fixes
The CI/CD Tracer starts and idles when Lunar Hub has no configuration installed yet, instead of exiting with a startup sync failure and leaving the CI runner untraced.
The CI/CD Tracer correctly traces GitHub code scanning runs that use the
dynamicevent type, including step resolution for CodeQL default-setup workflows whose definitions are not committed to the repository.The CI/CD Tracer no longer fails to initialize on GitHub-hosted runners: step scripts under the hosted runners'
work/_temp/path are now recognized, where previously only the self-hosted_work/_temp/layout was detected.CI/CD Tracer startup update checks are now properly cancelled when their timeout fires (configurable via
LUNAR_UPDATE_CHECK_TIMEOUT, default 5m), and attaching to an already-running process no longer logs misleading error and warning messages for expected mid-job attach conditions.
v1.1.1 (2026-03-26)
Improvements
lunar policy ok-releaseandlunar policy ok-prprint which policy checks are blocking and their status, instead of only reporting that the component is unable to release or merge.lunar policy ok-releaseandlunar policy ok-prpoll until policy results are complete instead of returning a one-shot answer that could report failure before workflows and collectors had finished; polling is configurable with--poll-interval(default 10s) and--timeout(default 10m), and the commands print what they are still waiting on.A new
--ready-fileoption makes the CI/CD Tracer create a file once tracing is active when attaching to a running process with--pid, so wrapper scripts can wait for tracing to start instead of polling/proc.lunarand the CI/CD Tracer now default their state, cache, and config directories to user-level paths under~/.lunar/when running as a non-root user, instead of system paths such as/var/lib/lunar; explicit overrides likeLUNAR_STATE_DIRstill take precedence.
v1.1.0 (2026-03-19)
Improvements
lunar collecthas a new--array-appendflag that wraps the collected value in a single-element array; arrays at the same path are concatenated during the Component JSON merge, so repeated collector invocations can accumulate list values.lunar collector devandlunar policy devcan now run directly inside a plugin directory (one containinglunar-collector.ymlorlunar-policy.yml) without requiring a repository with a fulllunar-config.ymlsetup.Collectors running on CI command hooks (
ci-before-command,ci-after-command) now inherit the full environment of the traced CI process instead of a minimal sandbox, so variables such asPATHandJAVA_HOMEset during CI steps are visible to collector scripts.
Bug fixes
The CI/CD Tracer terminates and reaps any remaining traced child processes when the root traced process exits, instead of leaving them ptrace-stopped.
The CI/CD Tracer resolves steps from reusable workflow references, fixing "job not found in workflow definition" step-resolution failures in GitHub Actions jobs that call another workflow via
uses:.The CI/CD Tracer detects shebang scripts during process tracing, so a tool like
npmis reported as the command binary instead of its interpreter (node) inbinary.namehook matching andLUNAR_CI_COMMAND_BIN.The CI/CD Tracer no longer fails to parse GitHub Actions workflow definitions that set a step's
envto a runtime expression such as${{ fromJSON(inputs.envs) }}.
v1.0.11 (2026-02-22)
Security
Git access tokens no longer appear in debug logs: git commands authenticate through the process environment instead of embedding the token in clone and remote URLs.
Features
The new
--component-dirflag pointslunar collector devat a local directory as the target repository, instead of cloning the component's repo.The new
--configoption onlunar collector devandlunar policy devloads the Lunar config from a remote Git repository, accepting bothgithub.com/org/repoandgithub://org/repo@branchforms.Collector command hooks support advanced matching of traced commands: exact or pattern-based binary matching (
name_pattern,dir_pattern), positional and flag-based argument matchers (including both--flag=valueand--flag valueforms), and environment variable matchers.The new
--no-huboption makes the Hub connection optional, solunar collector devandlunar policy devcan run without a configured Hub.Plugin scripts can be addressed with dot notation in dev commands —
myplugin.mycollectorselects one collector or policy, and passing just the plugin name runs all of the plugin's collectors or policies in a single invocation.The new
lunar secretcommands manage the secrets that collectors, policies, and catalogers use, storing values on the Hub at runtime instead of requiring them in the Hub's environment configuration.The new
lunar versioncommand prints the CLI version and the source commit it was built from.
Improvements
lunar collector devresolves the component name and exposes it to the collector script's environment.Plugins referenced from directories outside the config repository — including symlinked paths — now install correctly in dev mode.
Git clones are cached across plugin installs for faster repeated installs, draft (local dev) installs are no longer cached, and stale cached clones are purged periodically.
lunar hub pullreports the full output of failed install commands, instead of a truncated error.Dependency installation is skipped for scripts that specify a container image, since the image already provides their dependencies.
Bug fixes
Fixed a permission-denied error when plugin installation copied directories with restrictive (read-only) permissions; failed partial copies are also cleaned up instead of blocking the next attempt.
The
.gitdirectory is no longer copied during plugin installation, avoiding file-permission errors it used to cause.Referencing a non-existent local or remote plugin path in
usesnow produces a clear validation error instead of failing obscurely.
v1.0.9 (2026-01-15)
Improvements
Release binaries are about 13% smaller: debug symbols are now stripped at build time.
v1.0.8 (2026-01-15)
Breaking changes
The CI/CD Tracer binary (
lunar-ci-agent-linux-amd64) is no longer attached tolunar-distreleases; it is published through its own release channel from this release onward. Update any automation that downloads the tracer binary fromlunar-dist.
v1.0.7 (2026-01-14)
Features
Releases now include a Linux arm64 build of the
lunarCLI (lunar-linux-arm64), alongside the existing Linux amd64 and macOS (Apple silicon) binaries.
v1.0.6 (2026-01-13)
Breaking changes
Collector, policy, and plugin names may no longer contain dots; configurations using dotted names are rejected when the Lunar config is loaded. The dot is reserved as the plugin/script separator.
The deprecated
lunar-ci-agent install <config-URI>command is removed; the CI/CD Tracer performs an initial configuration update check at startup instead, so a separate install step is no longer needed.
Features
lunar collector devandlunar policy devfetch the secrets a script needs from the Hub; a new--secretsflag supplies overrides or extra values.Collectors can now run at CI step boundaries on GitHub Actions using the new
ci-before-stepandci-after-stephook types.
Improvements
lunar collector devsets additional common environment variables for the collector script, bringing the local execution environment closer to what collectors receive in CI runs.lunar collector devandlunar policy devshow a spinner with progress information about what is happening in the background.Collector and policy name resolution is more consistent — plugin names take part in resolution with fixed precedence — and name conflicts are detected with clearer error messages.
The CI/CD Tracer now starts and runs without a locally installed Lunar configuration, picking it up automatically once the periodic update fetches it.
CI step detection on GitHub Actions now accounts for composite actions, pre/post hooks, and conditional steps.
Bug fixes
The CI/CD Tracer no longer duplicates collector runs when several traced commands complete in a row.
Collections from GitHub Actions matrix builds are now attributed to the correct matrix job instance instead of being conflated under the job's logical name.
Last updated
