# Introduction
Earthly Lunar is a guardrails platform for monitoring and enforcing engineering practices across your software development lifecycle.
Lunar works by instrumenting your existing CI/CD pipelines (no YAML changes needed) and source code repositories to collect structured metadata about how code is built, tested, scanned, and deployed. This metadata is then continuously evaluated against policies that you define—policies that are flexible, testable, and expressive enough to reflect your real-world engineering standards.
Want to block deployments that would violate compliance rules, like using unapproved licenses or bypassing required security scans? Or fail a PR if it introduces stale dependencies or vulnerable CI plugins? Or ensure that security-sensitive services are collecting SBOMs, running code scans, and deploying frequently enough to avoid operational drift? Lunar makes all of that possible—without requiring a wholesale rewrite of every team's CI pipeline, and without sacrificing developer velocity.
Lunar is designed to work with the messy reality of modern engineering. It's not a one-size-fits-all template. Its instrumentation is flexible and centralized—meaning platform teams stay in control, app teams stay autonomous, and standards actually get enforced.
## Overview
Earthly Lunar helps organizations maintain high engineering standards by:
* Monitoring components (services, libraries, repositories) across your organization
* Collecting metadata about your software development lifecycle
* Enforcing policies and best practices
* Providing visibility into engineering health through checks
## Key Features
* **Component Monitoring**: Track the health and status of individual software components
* **SDLC Instrumentation**: Collect data from various stages of your software development lifecycle
* **Policy Enforcement**: Define and enforce engineering standards across your organization
* [**200+ Pre-Built Guardrails**](https://earthly.dev/lunar/guardrails/): Ready-to-use policies for testing, security, compliance, and operational readiness
* [**50+ Integrations**](https://earthly.dev/lunar/integrations/): Connect to GitHub, Kubernetes, Docker, Codecov, Snyk, and more
* **Extensible Platform**: Create custom collectors and policies using Bash or Python SDKs
* **SQL API**: Query and analyze your engineering data
## AI Skills
To get started quickly with developing guardrails, see the [AI skills](/install/skills) compatible with Claude Code, Codex, and Cursor.
## Getting Started
1. [Install Lunar](/install)
2. [Learn the basics](/basics)
3. [Understand key concepts](/docs/key-concepts)
# Install Lunar
Overview of Lunar installation, covering Hub, CLI, CI Agent for self-hosted and managed runners, and AI skills for building plugins.
Welcome to the Lunar installation guide.
This section contains step-by-step instructions for installing Lunar. Install these pieces, in this order:
1. **Lunar CLI** – an admin and development CLI. Install this first: the Hub install walkthrough uses `lunar licence` to derive your GHCR image-pull secret from your licence JWT before `helm install`.
* [Install the Lunar CLI](/install/cli)
2. **Lunar Hub** – the central coordination service.
* [Overview](/install/lunar-hub/hub-overview) – the lay of the land: services, dependencies, ports.
* [Prerequisites](/install/lunar-hub/hub-prereqs) – what to have in place before `helm install`.
* [Install walkthrough](/install/lunar-hub/hub-install) – step-by-step from zero to a working Hub.
* [Day-2 operations](/install/lunar-hub/hub-day2) – upgrades, secret rotation, observability, uninstall.
3. **Lunar CI Agent** — instruments your CI runners to report data to the Hub. Choose based on how your CI is set up:
* [Self-hosted runners](/install/lunar-ci-agent/agent-self-hosted)
* [GitHub-hosted managed runners](/install/lunar-ci-agent/agent-managed) (the [earthly/lunar-ci-tracer](https://github.com/earthly/lunar-ci-tracer) action).
Optional:
* [`sync-config` GitHub Action](/install/github-actions) – pushes your config repo to Lunar Hub on every push.
* [AI Skills](/install/skills) – agent skills for building collectors and policies.
Want to try Lunar without installing anything? Get in touch for a guided demo or preview.
Request a demo
Before diving in, browse the [100+ pre-built guardrails](https://earthly.dev/lunar/guardrails/) and [30+ integrations](https://earthly.dev/lunar/integrations/) available out of the box.
# Lunar CLI
Install the Lunar CLI for managing configurations, inspecting components, running collectors, and testing policies locally.
The Lunar CLI is primarily an administration tool for platform engineers, with developer-focused capabilities secondarily. It uses the same `lunar` binary as the CI agent but provides different subcommands for interactive CLI usage versus CI instrumentation. It can be used to manage configurations, inspect components, run collectors, and test policies.
## Prerequisites
**Docker** is required for local development commands since collectors and policies run inside containers.
{% hint style="info" %}
**macOS Users:** If using Docker Desktop, you must enable the default Docker socket. Go to **Docker Desktop → Settings → Advanced** and enable **"Allow the default Docker socket to be used"**, then click **Apply & Restart**.
{% endhint %}
## Installation
{% stepper %}
{% step %}
## Download the binary
Download the Lunar CLI
{% endstep %}
{% step %}
## Move the binary into place
Move the binary to the `~/.lunar/bin` directory:
```bash
chmod +x lunar-linux-amd64 && mv ./lunar-linux-amd64 "$HOME/.lunar/bin/lunar"
```
If you prefer to install `lunar` to a different directory, you must set the `LUNAR_BIN_DIR` environment variable to the desired path (see below).
{% endstep %}
{% step %}
## Set environment variables
```bash
# Required
export LUNAR_HUB_TOKEN=your_hub_token
export LUNAR_HUB_HOST=your_hub_host
export LUNAR_HUB_GRPC_PORT=your_grpc_port
export LUNAR_HUB_HTTP_PORT=your_http_port
export PATH="$HOME/.lunar/bin:$PATH"
# Optional, if you want to override the default bin dir
export LUNAR_BIN_DIR="$HOME/.lunar/bin"
```
{% endstep %}
{% step %}
## Verify installation
```bash
lunar --help
```
{% endstep %}
{% endstepper %}
For usage examples and full CLI documentation, see the [Lunar CLI Docs](/docs/lunar-cli).
***
## Next Steps
Once installed, you can begin configuring:
* [Collectors](/configuration/lunar-config/collectors) to gather SDLC data
* [Policies](/configuration/lunar-config/policies) to enforce standards
* [Domains and Components](/docs/key-concepts) to organize your software landscape
For questions or enterprise onboarding:
Contact the Earthly team
# Lunar Hub
Install and configure Lunar Hub, the central service that stores metadata, evaluates policies, and provides visibility into engineering health.
# Overview
This page is a high-level overview of what a Lunar Hub deployment looks like on Kubernetes. It's meant to provide a conceptual overview of the system before you dive into the installation process. When you're ready to install, start by setting up the [prerequisites](/install/lunar-hub/hub-prereqs).
## What you're installing
A Lunar deployment primarily consists of:
* the Lunar Hub (a Kubernetes service)
* the Lunar Operator (a Kubernetes controller)
* a fleet of transient policy/cataloger/collector batches managed by the operator
* and three external dependencies you provide (PostgreSQL, S3, and a GitHub App)
### External boundaries
```mermaid
flowchart LR
CLI["Lunar CLI"]
Agent["Lunar CI Agent"]
Hub["Lunar Hub"]
PG[("PostgreSQL")]
S3[("S3 buckets
logs · resources")]
GH["GitHub"]
CLI -- gRPC --> Hub
Agent -- gRPC --> Hub
GH -- webhooks --> Hub
Hub -- SQL --> PG
Hub -- reads/writes --> S3
Hub -- API --> GH
```
#### Hub
This is the central API server. It:
* talks to Postgres, GitHub, and S3
* serves the gRPC API consumed by the CLI, CI agents, and the Lunar operator
* receives GitHub webhooks on its HTTP port
* issues pre-signed S3 URLs for bulk data (run resources, run logs) transferred between work units orchestrated by the operator
For more details on how this hooks into the rest of the system, see [Ports and protocols](#ports-and-protocols) below.
#### Lunar CLI
The `lunar` binary. Used by platform engineers to push configuration, inspect components, and run collectors/policies locally. [This is installed separately.](/install/cli).
#### Lunar CI Agent
Instruments your CI runners to report data to the Hub. This is also installed separately. We support [Self-hosted GitHub Actions](/install/lunar-ci-agent/agent-self-hosted) and [Managed GitHub Actions](/install/lunar-ci-agent/agent-managed) options.
### Inside the cluster
```mermaid
flowchart LR
subgraph K8s["Kubernetes cluster"]
subgraph CP["Control-plane namespace"]
Hub["Lunar Hub"]
Op["Lunar Operator"]
end
subgraph RP["Run-pods namespace"]
SP["Run Pods
(init + sidecar + user code)"]
end
Op -- creates --> SP
end
PG[("PostgreSQL")]
Hub -- SQL --> PG
Op -- polls queue --> PG
SP -- gRPC --> Hub
```
#### Lunar Operator
A Kubernetes controller that groups enqueued runs into batches and materializes each batch as a short-lived Kubernetes pod. It manages the whole lifecycle of these pods, from creation to cleanup.
#### Run pods
Short-lived batch pods. The init container fetches needed data from S3 and GitHub and coordinates the user containers. User containers execute the specified cataloger, collector, or policy. The sidecar streams each container's logs to S3 and reports exit codes back to the Hub over gRPC.
Splitting the control plane (Hub + operator) and run pods into separate namespaces is recommended. This provides different blast radius, different resource profile, and different RBAC for distinctly different pieces of the system. Single-namespace installs also work; see [Step 1](/install/lunar-hub/hub-prereqs#step-1--plan-your-kubernetes-namespaces) of the prerequisites for details.
### Grafana
Grafana is the primary UI for Lunar today — dashboards for policy results, component health, and collection activity, reading from the same Postgres database as the Hub. Lunar ships those dashboards (plus the datasources and panel plugins they need) and **installs them into a target Grafana over its HTTP API**. You pick which Grafana based on what you already run:
| Your situation | How Lunar reaches Grafana |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **No Grafana of your own** — you want Lunar to run one | The chart deploys a stock Grafana alongside the Hub and installs the dashboards into it for you. Enabled by default; admin credentials are auto-generated. |
| **Grafana Cloud or Grafana Enterprise** | Point Lunar at your Grafana and give it a **service-account token**. |
| **Self-hosted OSS Grafana** | Point Lunar at your Grafana and give it **admin username + password** (OSS Grafana needs a server admin to install the dashboards' panel plugins — a service-account token can't). |
In every case the chart provisions the dashboards for you on `helm install` / `helm upgrade` via a post-install/post-upgrade hook Job (`grafana.provisioning`).
[Install Step 4](/install/lunar-hub/hub-install#grafana) walks through all three. To turn Grafana off entirely, set `grafana.mode: off`; full configuration is in the [chart README](https://github.com/earthly/charts/blob/main/README.md#grafana).
## Networking
### Connectivity
Use this table when planning ingress rules, egress allowlists, and NetworkPolicies. Specific Hub ports are detailed in the [next section](#ports-and-protocols).
| Source | Destination | Direction | Purpose |
| --------------- | ---------------- | ---------- | ----------------------------------------- |
| GitHub | Hub HTTP ingress | Inbound | Webhook delivery |
| CLI / CI agents | Hub gRPC ingress | Inbound | API calls (config sync, results) |
| CLI / CI agents | Hub HTTP ingress | Inbound | Pre-signed log URL fetches |
| Hub | GitHub API | Outbound | Read repos, post checks/comments |
| Hub | Postgres | Outbound | Hub state (incl. work queue, migrations) |
| Hub | S3 | Outbound | Run pod resource uploads |
| Operator | Postgres | Outbound | Poll work queue (own schema) |
| Run pods | S3 | Outbound | Upload logs, download resources |
| Run pods | Hub Service | In-cluster | Exit codes (gRPC); log URL fetches (HTTP) |
### Ports and protocols
The Hub listens on three ports inside the pod. Only two are exposed externally; the third is for in-cluster health probes.
| Port | Protocol | Purpose | Who talks to it |
| ------ | -------- | ---------------------------------------------------------------- | ---------------------------------- |
| `8000` | gRPC | API — config sync, policy evaluation, run results | CLI, CI agents, run pods (sidecar) |
| `8001` | HTTP | GitHub webhook receiver + pre-signed URL redirector for run logs | GitHub, CLI, CI agents, sidecar |
| `8002` | HTTP | Liveness / readiness probes (`GET /health`) | Kubelet only |
The HTTP port serves exactly two path prefixes: `/webhooks/github` (webhook ingestion) and `/logs/runs/` (redirects to pre-signed S3 URLs for log upload/download). No other HTTP routes exist. The Hub does not currently expose Prometheus metrics; observability is via OpenTelemetry (OTLP).
## Next steps
* [Prerequisites](/install/lunar-hub/hub-prereqs) — external dependencies you need in place before `helm install`.
* [Install walkthrough](/install/lunar-hub/hub-install) — step-by-step from zero to a working Hub.
# Prerequisites
Before you run `helm install lunar`, the external dependencies below must be in place. The [install walkthrough](/install/lunar-hub/hub-install) assumes you have them.
If you want a total picture of what you're about to deploy, read the [overview](/install/lunar-hub/hub-overview) first.
{% hint style="info" %}
Lunar Hub is supported on Kubernetes only. Bare-metal and Docker installations are not supported.
{% endhint %}
{% hint style="info" %}
**Install the** [**Lunar CLI**](/install/cli) **first.** The walkthrough uses it on your workstation to derive the cluster's GHCR image-pull secret from your licence — before `helm install`.
{% endhint %}
## Before you begin
Make sure you have the following available before continuing.
| Step | What you need | Detail |
| ---------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| — | Workstation tools | [`lunar`](/install/cli), `kubectl`, `helm` 3.x |
| [2](#step-2--check-your-kubernetes-cluster) | Kubernetes cluster | 1.29+, with an ingress controller and a default StorageClass |
| [2](#step-2--check-your-kubernetes-cluster) | DNS hostnames + TLS certs | One hostname for the Hub (reachable from GitHub, or your GHES instance), plus a second for Grafana if you let the chart run it for you (reachable from your users) |
| [3](#step-3--provision-postgresql) | PostgreSQL instance | 16+, where you can create a dedicated owner role |
| [4](#step-4--provision-s3-compatible-object-storage) | S3-compatible buckets | Two private buckets (logs + resources) with IAM to read and write them |
| [5](#step-5--create-a-github-app) | GitHub org admin access | Or a personal account, where you can create a GitHub App for your org |
| [6](#step-6--plan-your-kubernetes-secrets) | Hub license key | Provided by Earthly; mounted by the chart as `lunar-hub-licence` |
{% hint style="info" %}
If you're standing up EKS from scratch, [`earthly/lunar-terraform-quickstart`](https://github.com/earthly/lunar-terraform-quickstart) is a working reference module you can fork if desired.
{% endhint %}
## Step 1 — Plan your Kubernetes namespaces
We recommend splitting the install across two namespaces:
* **Control-plane namespace** (e.g. `lunar`). This is the release namespace. It hosts the Lunar Hub, the Operator, and — if you use the chart's bundled Grafana — Grafana. These are the parts that need to stay up, and will be updated by Helm.
* **Run Pods namespace** (e.g. `lunar-scripts`). This hosts the short-lived pods the operator spawns to execute cataloger, collector, and policy batches. We recommend this separate namespace because:
* this workload is ephemeral, and can be rather "bursty" in number and resource requirements. You can tune resources and limits independently here.
* this code is user-supplied (e.g. your plugins, scripts, third-party catalogers), not Lunar's. This is a different trust boundary, where you can tighten RBAC, egress, and resource limits independently.
Both namespaces must exist **before** `helm install`. The chart will not create the run-pods namespace for you. Point the operator at it with `operator.snippetNamespace`.
Single-namespace installs also work — leave `operator.snippetNamespace` unset and everything runs in the release namespace. This is fine for trying things out, or small setups; but is *not recommended* for production configurations.
```bash
kubectl create namespace lunar
kubectl create namespace lunar-scripts
```
## Step 2 — Check your Kubernetes cluster
| Requirement | Detail |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Kubernetes** | 1.29 or newer. |
| **Helm** | 3.x. |
| **StorageClass** | A StorageClass must be available — your cluster default is probably fine. The chart provisions a 10 GiB `ReadWriteOnce` PVC for Hub state. You can tune details if needed via `hub.persistence.*` ([chart README](https://github.com/earthly/charts/blob/main/README.md)). |
| **Ingress controller** | Must support gRPC backend routing. See [Ingress](https://github.com/earthly/charts/blob/main/README.md#ingress) in the chart README for an NGINX-tested example. |
| **DNS** | A hostname for the Hub (e.g. `lunar.example.com`) pointing at your ingress controller's external IP — GitHub, CI integrations, and Lunar CLI users must reach it. If you let the chart run Grafana for you, add a second hostname for it (e.g. `grafana.lunar.example.com`) for your team's browser access; not needed if you point Lunar at your own Grafana. |
| **TLS certificate** | The Hub (and the bundled Grafana, when enabled) listen plaintext. Terminate TLS at your ingress or an upstream load balancer for each hostname. |
## Step 3 — Provision PostgreSQL
Lunar needs a single PostgreSQL database. Schema migrations run as a pre-rollout Job on each release, and the Hub manages several of its own schemas (including the default `public`). We recommend that you give it a dedicated DB where its role is the owner.
| Requirement | Detail |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Version** | PostgreSQL 16 or newer. |
| **Connectivity** | Reachable from both the Hub and Operator pod's network. The chart does **not** include Postgres. |
| **Role** | Dedicated DB role for the Hub. Minimum: **database owner** (to create schemas, and grants on created objects) **plus cluster-level `CREATEROLE`** (to create the read-only `sqlapi_user` and `grafana_user` roles during migration). `SUPERUSER` also works. |
| **Extensions** | Optional: `pg_stat_statements` enabled in `shared_preload_libraries`. The Hub's diagnostics bundle uses it when present. Setting `shared_preload_libraries` requires a Postgres restart (or parameter-group reboot on RDS / Cloud SQL), so it's easier to enable at provisioning time than later. |
| **Connection pool** | The Hub is stateless and runs as multiple replicas; each opens \~85 connections by default (`maxOpenConns + maxPoolConns + operatorPoolSize`), so total connections scale with `hub.replicaCount`. Size your Postgres (or PgBouncer) for `replicaCount × per-replica pool`. See [Scaling](/install/lunar-hub/hub-day2#scaling) in Day 2 Operations for tuning context. |
| **SSL** | The Hub negotiates TLS by default via `hub.db.connectionOptions: "sslmode=require"`. Most managed Postgres (RDS, Aurora, Cloud SQL) ships with TLS forced and will connect out of the box. Plain Postgres deployments without TLS must set `hub.db.connectionOptions: "sslmode=disable"` explicitly. **Format is libpq KV pairs, space-separated** — to pass extra options write `"sslmode=require connect_timeout=10"` (NOT `&`-separated URL query). The default is not merged in when overridden, so include `sslmode=` yourself. |
| **Backups** | Use your existing Postgres backup process; backups are your responsibility. All authoritative Hub and Operator state lives entirely in Postgres. |
{% hint style="info" %}
**Shared Postgres cluster?** Because `CREATEROLE` is a cluster-level attribute, Postgres has no mechanism to scope it to a single database. If granting it cluster-wide is too broad, pre-create the `sqlapi_user` role yourself (any password) and leave `HUB_SQLAPI_PASSWORD` unset. The migration's `IF NOT EXISTS` check skips role creation, leaving only schema-level grants — which the Hub's role can do as database owner.
{% endhint %}
## Step 4 — Provision S3-compatible object storage
Lunar needs two private S3 buckets, both writable by the Hub:
* A **Logs bucket**, which contains per-run log files. These can be short-lived; a 30-day lifecycle rule is reasonable here.
* A **Resources bucket**, which contains run-bundle archives fetched by init containers. Keep these as long as you might re-run historical catalogers, collectors, or policies.
Both buckets must block public access. Content may include credentials, user script source code, or PII surfaced from CI runs. The Hub serves all reads via time-limited pre-signed URLs.
{% hint style="warning" %}
**Object lifecycles are your responsibility.** Lunar never deletes from either bucket. Set S3 lifecycle rules yourself to cap storage growth. Check with your compliance requirements before settling on retention windows, since logs and run bundles may contain information that falls under your organization's data-retention policies.
{% endhint %}
The Hub *only* calls `PutObject`, `GetObject`, and `HeadObject` on both buckets, and issues pre-signed `GET`/`PUT` URLs for both. Minimum IAM policy on AWS:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:PutObject"],
"Resource": [
"arn:aws:s3:::your-logs-bucket/*",
"arn:aws:s3:::your-resources-bucket/*"
]
}
]
}
```
### Region and credentials
The Hub picks up AWS credentials via the standard [SDK credential chain](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) — the chart stays out of the credentials business. Region must be set explicitly:
```yaml
hub:
extraEnv:
- name: AWS_REGION
value: us-east-1
```
Common patterns (see the [chart README](https://github.com/earthly/charts/blob/main/README.md#object-storage--aws-credentials) for full YAML):
* **EKS**. Annotate the chart's service account with an [IAM role for service accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html).
* **Static credentials**. Inject `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` from a secret via `hub.extraEnv`. Not recommended for production.
* **IMDS, pod identity, external secrets operators**. All the usual AWS-SDK-friendly mechanisms work.
### Non-AWS backends
MinIO, Cloudflare R2, and GCS in S3-compatibility mode all work — set `AWS_ENDPOINT_URL_S3` via `hub.extraEnv`:
```yaml
hub:
extraEnv:
- name: AWS_REGION
value: auto
- name: AWS_ENDPOINT_URL_S3
value: https://your-minio.example.com
```
Lunar uses virtual-host-style S3 addressing only. Most MinIO, R2, and GCS deployments handle this out of the box. Path-style-only backends aren't currently supported.
## Step 5 — Create a GitHub App
The Hub authenticates to GitHub as a GitHub App. Use our hosted setup tool to create one in a couple of clicks.
{% hint style="info" %}
**Need to create the App manually?** If your GitHub instance is air-gapped, you're using GitHub Enterprise Server, or your security review needs every permission and event laid out before the App is created, see [manual GitHub App setup](/install/lunar-hub/hub-github-app-manual) instead.
{% endhint %}
### Using the setup tool
1. Visit [**earthly.dev/lunar/github-app-setup**](https://earthly.dev/lunar/github-app-setup/).
2. Follow the prompts. The tool uses GitHub's [manifest flow](https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app-from-a-manifest/about-creating-github-apps-from-a-manifest) to register the App with the right permissions and events.
3. **Download the PEM private key when prompted.** GitHub shows it exactly once — if you click past this page, you'll have to generate a new key from the App settings later.
4. Click *Install App on GitHub* and select the org. Choose **All repositories** unless you have a specific reason not to — Lunar's actual monitoring scope is configured in `lunar-config.yml`, so a narrower scope here just means coming back to **Org Settings → GitHub Apps → Lunar → Repository access** every time you add a new repo to Lunar.
The hosted tool proxies the manifest exchange to GitHub and returns the credentials to your browser; we never persist them.
### Capture these before continuing
When you finish Step 5, you'll have four things — confirm you've saved all four before moving on:
| What | Source |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Owner** (the GitHub org or user the App is installed on, e.g. `earthly`) | The `` in the install URL below |
| **App ID** (numeric, e.g. `3635822`) | Setup tool result page |
| **Installation ID** (numeric) | URL after install: `https://github.com/organizations//settings/installations/` — the trailing number |
| **PEM private key** | Downloaded from the setup tool — **shown only once, save it now** |
Set them via `HUB_GITHUB_APP_OWNER`, `HUB_GITHUB_APP_ID`, `HUB_GITHUB_APP_INSTALL_ID`, and `HUB_GITHUB_APP_PRIVATE_KEY` (or the chart equivalents under `hub.github.app.*`). All four are required in single-App mode; the Hub refuses to start without them.
For GitHub Enterprise Server, you also need to set `hub.github.baseUrl` in your values to point at your GHES instance.
### Installing in multiple GitHub orgs with one Hub
When the Hub fronts multiple customer orgs that each install their own Lunar App, register one entry per owner in `HUB_GITHUB_APPS`:
```bash
export HUB_GITHUB_APPS=$(cat <<'EOF'
[
{"owner": "earthly", "app_id": 123, "private_key_path": "/secrets/github-apps/earthly.pem", "install_id": 100},
{"owner": "acme", "app_id": 456, "private_key_path": "/secrets/github-apps/acme.pem", "install_id": 200}
]
EOF
)
```
Each entry pins its own App credentials and installation; the Hub mints tokens scoped to the right org per request. Owner matching is case-insensitive and trimmed.
For the PEM files, the recommended pattern is one Kubernetes Secret with multiple keys, mounted as a single volume:
```yaml
# Secret
data:
earthly.pem:
acme.pem:
# Pod
volumes:
- name: github-apps
secret: { secretName: github-apps }
volumeMounts:
- { name: github-apps, mountPath: /secrets/github-apps, readOnly: true }
```
`HUB_GITHUB_APPS` is mutually exclusive with the single-App env vars (`HUB_GITHUB_APP_OWNER` / `HUB_GITHUB_APP_ID` / `HUB_GITHUB_APP_PRIVATE_KEY` / `HUB_GITHUB_APP_INSTALL_ID`). Use one mode or the other.
## Step 6 — Plan your Kubernetes secrets
Several Kubernetes secrets come into play at install time. You create the first four below; the chart auto-generates the rest (with `helm.sh/resource-policy: keep`, so they survive upgrades and uninstalls).
| Secret | Who creates it | Contents |
| -------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lunar-db` | You | DB `username` and `password` |
| `lunar-github-app` | You | `private-key` — the PEM from Step 5 |
| `lunar-hub-licence` | You | `hub-licence.jwt` — Hub licence token |
| `regcred` | You (derived from licence) | GHCR image-pull credentials — generated by [`lunar licence pull-secret`](/install/lunar-hub/hub-install#pulling-images-from-ghcr) from your licence JWT |
| `-auth-token` | Chart (auto-generated) | Shared bearer token for the CLI and CI agents |
| `-github-webhook` | Chart (auto-generated) | Per-repo webhook signing secret — the Hub registers this with GitHub automatically when it creates per-repo webhooks |
| `-grafana-admin` | Chart (auto-generated) | Grafana admin username and password — **only when the chart runs Grafana for you** ([Option A](/install/lunar-hub/hub-install#grafana)) |
| `-grafana-db` | Chart (auto-generated) | Read-only `grafana_user` DB-role password (used by the dashboards' datasource) — whenever the provisioning Job runs (bundled **or** your own Grafana). BYO via `grafana.provisioning.dbPassword.secretName`. |
Pointing Lunar at **your own Grafana** ([Option B or C](/install/lunar-hub/hub-install#grafana))? The chart doesn't generate `-grafana-admin` — you create a secret holding your Grafana service-account token (or admin username/password). The `-grafana-db` secret above is still chart-managed. See [Install Step 4 → Grafana](/install/lunar-hub/hub-install#grafana).
{% hint style="info" %}
**Your licence also covers the CI agent.** The credential the chart uses to pull Lunar's container images — derived from your licence with [`lunar licence pull-secret`](/install/lunar-hub/hub-install#pulling-images-from-ghcr) for the `regcred` secret above — is also what the Hub uses to fetch the CI agent binary for your runners. You don't need a separate credential for the CI agent.
If your licence doesn't include CI agent distribution, the Lunar CLI reports a clear error the first time a runner tries to download the agent. If you plan to use the CI agent, make sure your licence covers it — contact Earthly if you're unsure.
{% endhint %}
**GitOps alternative.** If your setup needs deterministic secret management, you can pre-create any chart-managed secret and point the chart at it (e.g. `hub.github.webhookSecret.secretName`). See the [chart README](https://github.com/earthly/charts/blob/main/README.md) for the full list of `*.secretName` values you can override.
The [install walkthrough](/install/lunar-hub/hub-install#step-3--create-kubernetes-secrets) has the exact `kubectl create secret` commands for the three user-created secrets.
## Step 7 — Size for capacity
The chart sets **no** default resource requests or limits. The numbers below are reasonable starting points, but you should monitor and adjust them based on your specific needs.
| Component | CPU request | Memory request |
| --------- | ----------- | -------------- |
| Hub | 500m | 1 Gi |
| Operator | 100m | 128 Mi |
**Run pods** are short-lived batch pods spawned by the operator. Each pod contains N **user containers** (one per script in the batch) plus an init container and a sidecar. Per-user-container resources come from `operator.snippetContainerSpec*` — the operator's built-in defaults request 250m / 256 Mi for collectors and catalogers, 50m / 128 Mi for policies.
**Batch size** is per script type via `operator.batchMaxCount*` (defaults: 10 for collectors and catalogers, 20 for policies — policies pack denser because each container is lighter). Concurrent batch pods are capped by `operator.maxConcurrent` (default `10`), shared across script types.
Hub workers that feed run pods can be capped with `HUB_MAX_WORKERS_COLLECT`, `HUB_MAX_WORKERS_POLICY`, `HUB_MAX_WORKERS_CRON_COLLECT`, and `HUB_MAX_WORKERS_CATALOGER`; `0` means unlimited. Tune these when increasing `operator.maxConcurrent`. The Hub and operator have separate Postgres pool caps for operator work via `HUB_MAX_OPERATOR_POOL_SIZE` and `OPERATOR_MAX_POOL_SIZE`.
The run-pods namespace needs headroom for:
```
maxConcurrent × batchMaxCount(type) × per-user-container requests
```
At defaults that's \~25 GiB of concurrent-run memory per script type (10 pods × 10 collectors × 256 Mi, or 10 × 20 × 128 Mi for policies).
If you want sizing guidance once you're past initial install, please reach out.
## Next steps
When your prerequisites are in place:
* [Install walkthrough](/install/lunar-hub/hub-install) — step-by-step from zero to a working Hub.
* [Chart README](https://github.com/earthly/charts/blob/main/README.md) — complete `values.yaml` reference.
# Manual GitHub App Setup
This page is the fallback for [prereqs Step 5](/install/lunar-hub/hub-prereqs#step-5--create-a-github-app). Most users should use [the hosted setup tool](https://earthly.dev/lunar/github-app-setup/) — it creates the App with the right permissions and events in a couple of clicks.
Use the manual flow if:
* Your GitHub instance is air-gapped or otherwise can't reach `earthly.dev` from a browser session.
* You're standing the App up against **GitHub Enterprise Server** and prefer your GHES web UI for the audit trail.
* Your security review needs explicit visibility into every permission and event before the App is created.
## Create the App
Create the App at GitHub's [App creation page](https://github.com/settings/apps/new) (or for an org: **Org Settings → Developer settings → GitHub Apps → New GitHub App**). GitHub's [registering-a-github-app docs](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) walk through every form field if you want a reference.
For GHES, create the App on your GHES instance instead.
**Permissions:**
| Permission | Access | Why |
| -------------------- | ------ | --------------------------------------------- |
| `actions` | read | Read workflow runs for CI data collection |
| `checks` | write | Post policy results as PR checks |
| `contents` | read | Fetch config and source for policy evaluation |
| `metadata` | read | Required by GitHub on every App |
| `pull_requests` | write | Post PR comments and statuses |
| `repository_hooks` | write | Auto-register per-repo webhooks |
| `organization_hooks` | write | Auto-register organization-level webhooks |
**Subscribe to events:** `push`, `pull_request`, `workflow_run`.
**Other fields:**
* **Homepage URL** — any URL works (e.g. your internal Lunar URL, or `https://earthly.dev/lunar`).
* **Webhook** — uncheck "Active." The Hub registers its own per-repo webhooks at runtime; the App-level webhook is unused. URL can be a placeholder (e.g. `https://example.com/placeholder`) — GitHub requires a value but nothing will ever hit it.
* **Webhook secret** — leave blank. Since you unchecked "Active" above, GitHub won't deliver App-level events. The Hub's per-repo webhook signing secret is a separate thing — see [prereqs Step 6](/install/lunar-hub/hub-prereqs#step-6--plan-your-kubernetes-secrets).
* **Where can this app be installed?** — "Only on this account."
## After creating the App
1. **Generate a private key** (App settings → "Private keys" → "Generate a private key"). Save the `.pem` file — GitHub does not show it again.
2. **Install the App** on your organization (App settings → "Install App"). Choose **All repositories** unless you have a specific reason not to — Lunar's actual monitoring scope is configured in `lunar-config.yml`, so a narrower scope here just means coming back to this page every time you add a new repo to Lunar.
## Capture these before continuing
| What | Source |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **App ID** (numeric, e.g. `3635822`) | App settings page |
| **Installation ID** (numeric) | URL after install: `https://github.com/organizations//settings/installations/` — the trailing number |
| **PEM private key** | Downloaded from "Generate a private key" — **shown only once, save it now** |
For GitHub Enterprise Server, you also need to set `hub.github.baseUrl` in your values to point at your GHES instance.
Return to [prereqs Step 6](/install/lunar-hub/hub-prereqs#step-6--plan-your-kubernetes-secrets) once you've captured all three.
# Install Walkthrough
This walkthrough takes you from zero to a working Lunar Hub. It assumes you've worked through the [prerequisites](/install/lunar-hub/hub-prereqs), and have:
* Kubernetes cluster with your namespaces created
* Postgres database
* two S3 buckets
* GitHub App
* hub licence key
* DNS name for the Hub
Assuming your prerequisites are in order, expect the install to take 15–30 minutes end to end. The bulk of that is waiting for external systems (e.g. first-boot migrations).
## Step 1 — Add the Helm repo
```bash
helm repo add earthly https://earthly.github.io/charts
helm repo update
```
Verify:
```bash
helm search repo earthly/lunar
```
You should see the chart listed with a version number.
## Step 2 — Verify your prerequisites
Before going further, sanity-check the external dependencies you provisioned in the [prerequisites](/install/lunar-hub/hub-prereqs). An issue here is cheaper to find now than after you've created secrets and written your `values.yaml`.
**DNS** ([prereqs Step 2](/install/lunar-hub/hub-prereqs#step-2--check-your-kubernetes-cluster)):
```bash
nslookup lunar.example.com
```
Should resolve to your ingress controller's external IP. If it doesn't yet, either wait or add an `A` / `CNAME` record now — GitHub webhook auto-registration needs a publicly reachable URL.
**Postgres reachability** ([step 3](/install/lunar-hub/hub-prereqs#step-3--provision-postgresql)):
```bash
kubectl run -it --rm --restart=Never -n lunar pg-check \
--image=postgres:16 -- \
psql "postgresql://:@:5432/lunar" \
-c "SELECT 1;"
```
Should return `1`. If the connection fails or the role is rejected, fix that before installing — the Hub will crash-loop otherwise.
**S3 access** ([prereqs Step 4](/install/lunar-hub/hub-prereqs#step-4--provision-s3-compatible-object-storage)):
```bash
aws s3api head-bucket --bucket your-lunar-logs-bucket
aws s3api head-bucket --bucket your-lunar-resources-bucket
```
Both should succeed silently (exit code `0`). This requires the AWS CLI with credentials configured on your workstation — it confirms the buckets exist and that *some* credentials can reach them, but doesn't validate the in-cluster IRSA path. If your workstation isn't AWS-configured, skip this check; Hub logs surface S3 misconfiguration immediately on install.
## Step 3 — Create Kubernetes secrets
You'll need to create three Kubernetes secrets yourself:
* Database credentials
* The GitHub App private key (the PEM you saved during [prereqs Step 5](/install/lunar-hub/hub-prereqs#step-5--create-a-github-app))
* A signed Hub licence JWT (from your Earthly contact)
Other secrets, like the Hub auth token, GitHub webhook secret, and Grafana admin password — are auto-generated by the chart on first install and preserved across upgrades. You'll retrieve their values after install in [Step 6](#step-6--verify-the-install).
Create the three with `kubectl`, or provision them with your secret manager of choice, using the same names and keys as specified below.
**Database credentials:**
```bash
kubectl -n lunar create secret generic lunar-db \
--from-literal=username='' \
--from-literal=password=''
```
**GitHub App private key** — base64-encode the PEM and store it as the `private-key` field:
```bash
kubectl -n lunar create secret generic lunar-github-app \
--from-literal=private-key="$(base64 < path/to/lunar-github-app-.pem | tr -d '\n')"
```
{% hint style="info" %}
The PEM must be base64-encoded inside the secret value — the Hub decodes it after reading the env var. (Kubernetes then base64-encodes the whole secret again for etcd storage, so it's double-encoded at rest.)
{% endhint %}
**Hub licence JWT** — store the signed token in `hub-licence.jwt`:
```bash
kubectl -n lunar create secret generic lunar-hub-licence \
--from-literal=hub-licence.jwt=''
```
If your collectors need credentials at runtime (`github.*` collectors, Datadog, Jira, Linear, etc.), provision a fourth secret as well — see [Script runtime secrets](#script-runtime-secrets) at the bottom of this page.
## Step 4 — Write `values.yaml`
Create a `values.yaml` with the minimum configuration the chart needs. The example below is a working baseline — copy it, fill in the placeholders, and adjust for your environment. The GitHub App ID and installation ID come from [prereqs Step 5](/install/lunar-hub/hub-prereqs#step-5--create-a-github-app).
```yaml
# Cluster assumptions baked into this sample:
# - NGINX ingress controller → hub.ingress.className + grpcAnnotations
# - cert-manager for TLS → ingress annotations (drop if BYO secret)
# - EKS IRSA for S3 credentials → serviceAccount.annotations (see "AWS credentials" below)
# IRSA on EKS: annotate the service account with your IAM role ARN.
# See "AWS credentials" below for non-EKS options.
serviceAccount:
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/lunar-hub-s3
hub:
publicBaseURL: "https://lunar.example.com"
licence:
secretName: "lunar-hub-licence"
secretKey: "hub-licence.jwt"
# Run the Hub as multiple replicas. The Hub is stateless — all state lives
# in Postgres and S3 — so replicas coordinate through Postgres (leader
# election, advisory locks) with no peer-to-peer wiring. See "Replicas and
# the Postgres connection budget" below before raising this.
replicaCount: 3
# Keep a quorum during node drains and rollouts. Enable this whenever
# replicaCount > 1 (a PDB on a single replica blocks voluntary node drains).
podDisruptionBudget:
enabled: true
maxUnavailable: 1
# Pin all four image tags (hub, operator, initImage, sidecarImage) to the
# same released hub version for a reproducible install. The latest is
# published to ghcr.io/earthly/lunar-hub — see the repo's `lunar-hub-v*`
# release tags. This example is bumped automatically on each Hub release.
image:
tag: "3.2.0"
db:
host: "your-db-host.example.com"
name: "lunar"
s3:
logsBucket: "your-lunar-logs-bucket"
resourcesBucket: "your-lunar-resources-bucket"
github:
app:
# Don't forget the quotes, otherwise they might get rendered as scientific notation!
id: "123456"
installId: "78901234"
# The GitHub org (or user) the App is installed on. Required since chart 2.2.0.
owner: ""
# AWS region for S3. Credentials themselves come from the AWS SDK
# credential chain (IRSA above, or see "AWS credentials" below).
extraEnv:
- name: AWS_REGION
value: us-east-1
# The chart sets no resource defaults. Numbers below are the starting
# recommendations from prereqs Step 7 — tune as you observe real load.
resources:
requests:
cpu: 500m
memory: 1Gi
ingress:
enabled: true
host: lunar.example.com
className: nginx
tls:
- secretName: lunar-tls
hosts: [lunar.example.com]
annotations:
# cert-manager provisions the `lunar-tls` secret automatically.
# Remove this annotation if you supply the TLS secret yourself
# (corporate CA, external LB, ACM, etc.).
cert-manager.io/cluster-issuer: letsencrypt
# gRPC backend-protocol applies only to the gRPC Ingress. Both
# Ingresses are always rendered when ingress.enabled is true.
grpcAnnotations:
nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
operator:
# Run pods are created here. The namespace must already exist; the chart
# will not create it. See prereqs Step 1 for the trust-boundary rationale.
snippetNamespace: "lunar-scripts"
image:
tag: "3.2.0"
initImage:
tag: "3.2.0"
sidecarImage:
tag: "3.2.0"
resources:
requests:
cpu: 100m
memory: 128Mi
# Grafana — the primary UI for Lunar. Enabled by default: the chart runs a
# stock Grafana and installs Lunar's dashboards into it. This block just wires
# up its ingress. If you'd rather use a Grafana you already run (Cloud,
# Enterprise, or self-hosted OSS), drop this block and see the "Grafana"
# section below for how to point Lunar at it instead.
grafana:
ingress:
enabled: true
hosts: [grafana.lunar.example.com]
tls:
- secretName: lunar-grafana-tls
hosts: [grafana.lunar.example.com]
annotations:
cert-manager.io/cluster-issuer: letsencrypt
```
Everything else has a sensible default. See the [chart README](https://github.com/earthly/charts/blob/main/README.md#values-reference) for the full values reference.
### Replicas and the Postgres connection budget
The Hub is stateless, so `replicaCount` scales it horizontally with no extra wiring — but each replica opens its own pool of Postgres connections, so total connections scale roughly linearly with the replica count:
```
total ≈ replicaCount × (hub.db.maxOpenConns + hub.db.maxPoolConns + hub.db.operatorPoolSize)
```
The chart defaults (`40 + 40 + 5 ≈ 85` per replica) match the Hub's built-in values, so a single replica is unchanged. Before running several replicas, confirm the total stays within your Postgres `max_connections` — leave headroom for the migrate Job, `psql`, and superuser-reserved slots. For larger replica counts, **lower `hub.db.maxOpenConns` / `hub.db.maxPoolConns`** so the total fits, and/or front Postgres with a connection pooler. Keep `maxPoolConns` at or above your peak concurrent queue workers (the sum of `hub.maxWorkers.*`) — the pool is shared by every queue, so a pool below that serializes store queries under load.
The chart soft-spreads replicas across nodes by default (`topologySpreadConstraints`, `maxSkew 1` across `kubernetes.io/hostname`, `ScheduleAnyway`) so a single node loss doesn't take out the whole Hub. Override `hub.topologySpreadConstraints` to impose your own (e.g. a hard zone spread) — it replaces the default wholesale.
### A note on ingress
The Hub serves two protocols on separate ports — gRPC on `8000` (API) and plain HTTP on `8001` (webhook receiver + pre-signed URL redirector for run logs). Most ingress controllers apply `backend-protocol` per-Ingress rather than per-path, so the chart renders **two** Ingress resources sharing the same hostname and TLS config whenever `hub.ingress.enabled: true`. Per-protocol annotations layer over the shared `annotations` map: `grpcAnnotations` apply only to the gRPC Ingress, `httpAnnotations` only to the HTTP one. Both Ingresses are always created together — there's no per-protocol toggle.
If you'd rather front the Hub yourself (a controller with per-path backend protocols, a service mesh, or a LoadBalancer Service), set `hub.ingress.enabled: false` and route to the `hub-grpc` (port `8000`) and `hub-http` (port `8001`) service ports directly.
### Grafana
Lunar ships dashboards for policy results, component health, and collection activity, and installs them — with their datasources and panel plugins — into a Grafana over its HTTP API. There are three ways to provide that Grafana; pick the one that matches what you already run. The `grafana:` block in the values above shows the first (default) option.
In every case the chart auto-generates the read-only `grafana_user` datasource password (`-grafana-db`) and wires it end-to-end for you. If you'd rather provide your own secret, set `grafana.provisioning.dbPassword.secretName` (recommended for GitOps).
#### Option A — bundled Grafana (default)
The default (`grafana.mode: chart`): the chart deploys a stock Grafana next to the Hub, runs a post-install/upgrade Job that installs the dashboards into it, and auto-generates the admin login (which the Hub uses to reach the pod).
Wire up the ingress in the `grafana:` block above so your team can reach it in a browser, and retrieve the admin login in [Step 6](#step-6--verify-the-install). Nothing else is required — `grafana.mode` defaults to `chart`.
#### Option B — Grafana Cloud or Grafana Enterprise (service-account token)
Point the Hub at your existing Grafana with a [service-account token](https://grafana.com/docs/grafana/latest/administration/service-accounts/). Create a service account with the **Admin** role, generate a token, then disable the bundled Grafana and wire the token in:
```yaml
grafana:
mode: external # bring your own Grafana (no bundled pod)
url: "https://your-org.grafana.net"
auth:
secretName: lunar-grafana # holds the service-account token (created below)
tokenKey: token
```
That's the whole configuration. On `helm install` / `helm upgrade` the chart's `post-install` / `post-upgrade` hook Job runs the provisioning tool against your Grafana — `deploy.sh` resolves the URL, credentials, and read-only datasource connection from the Hub over gRPC, then installs the plugins, datasources, and dashboards over Grafana's HTTP API. The Job is idempotent and non-blocking (a failed provision is logged but never rolls back the Hub upgrade), and it re-runs on every subsequent upgrade so the dashboards stay in sync with the Hub's schema. No manual step.
#### Option C — self-hosted OSS Grafana (admin username + password)
Same as Option B, but OSS Grafana can't install plugins with a service-account token — the dashboards' panel plugins need a **server admin**. Give the Hub an admin username and password instead of a token:
```yaml
grafana:
mode: external
url: "https://grafana.example.com"
auth:
secretName: lunar-grafana # holds username + password (created below)
# userKey / passwordKey default to "username" / "password"
```
Deploy the same way as Option B: `helm install` / `helm upgrade` runs the chart's hook Job automatically.
The examples reference a `lunar-grafana` secret you create — the key depends on your option: `token` for Option B, or `username` + `password` for Option C:
```bash
# Option B (Cloud / Enterprise)
kubectl -n lunar create secret generic lunar-grafana \
--from-literal=token=''
# Option C (OSS) — use these keys instead of `token`
kubectl -n lunar create secret generic lunar-grafana \
--from-literal=username='admin' \
--from-literal=password=''
```
{% hint style="info" %}
`grafana.url` + `grafana.auth` are all the chart needs for an external Grafana — it wires them into the Hub for you (as `HUB_GRAFANA_URL_BASE` and `HUB_GRAFANA_TOKEN`, or `HUB_GRAFANA_USER` / `HUB_GRAFANA_PASSWORD`), so there's no `hub.extraEnv` plumbing. The chart's provisioning Job runs whenever `grafana.mode != off` — the same Job that serves the bundled pod — installing the dashboards on every install/upgrade.
{% endhint %}
{% hint style="warning" %}
Options B and C need three network paths:
* **your Grafana → the Hub's Postgres** (as the read-only `grafana_user` role) — the Postgres datasource
* **your Grafana → the Hub's HTTP API** — the Infinity datasource
* **the in-cluster Job → your Grafana** (HTTP) — the deploy Job
Same-network self-hosted Grafana has all three. Grafana Cloud needs a route to both Hub endpoints (public endpoint, PrivateLink, or Private Data Source Connect) so the in-cluster Job can reach it.
{% endhint %}
### AWS credentials
The chart does not manage AWS credentials. The example above uses **IRSA on EKS** (annotation on the service account), which is the recommended pattern. The conceptual breakdown of patterns is in [prereqs Step 4 → Region and credentials](/install/lunar-hub/hub-prereqs#region-and-credentials).
### Pulling images from GHCR
Lunar Hub images are published to a private GitHub Container Registry (`ghcr.io/earthly/*`). To pull them your cluster needs an image pull secret. You can derive the pull secret with the [Lunar CLI](/install/cli):
```bash
lunar licence pull-secret \
--licence-file=path/to/hub-licence.jwt \
--namespace=lunar \
--name=regcred | kubectl apply -f -
```
If your snippet pods run in a separate namespace (`operator.snippetNamespace`), run it again for that namespace:
```bash
lunar licence pull-secret \
--licence-file=path/to/hub-licence.jwt \
--namespace=lunar-scripts \
--name=regcred | kubectl apply -f -
```
Reference the secret in your `values.yaml`:
```yaml
imagePullSecrets:
- name: regcred
hub:
image:
repository: ghcr.io/earthly/lunar-hub
operator:
image:
repository: ghcr.io/earthly/lunar-snippet-operator
initImage:
repository: ghcr.io/earthly/lunar-snippet-init
sidecarImage:
repository: ghcr.io/earthly/lunar-snippet-sidecar
```
Lunar also ships the Grafana dashboards in a private deploy image, `ghcr.io/earthly/lunar-dashboards`, which the chart's dashboards-deploy Job pulls under the same `imagePullSecrets` — it uses that repository by default, so no extra image configuration is needed.
## Step 5 — Install
```bash
helm install lunar earthly/lunar \
--namespace lunar \
-f values.yaml
```
The chart fails fast with a clear error if any of the [required fields](https://github.com/earthly/charts/blob/main/README.md#required-values) are missing.
Watch the pods come up:
```bash
kubectl -n lunar get pods -w
```
Expected rollout, in order:
1. `lunar-hub-migrate-` runs first — a pre-install Helm hook Job that applies DB migrations and gates the rest of the rollout. It runs to `Completed` before any Hub pod is created.
2. `lunar-hub-` pods start (one per `replicaCount`). Each asserts the schema is current at boot and refuses to start if it's behind — so serving pods never run against an un-migrated schema. They flip to `Running 1/1` once the readiness probe (`/ready`) passes.
3. `lunar-operator-` depends on the applied migrations. Once the Hub is up, it flips to `Running 1/1` shortly after.
Migrations can take a minute or two on a warm DB. If the migrate Job fails, or a Hub pod restarts repeatedly, check the logs:
```bash
# Migrate Job (if it failed the hook, the whole install/upgrade is rolled back):
kubectl -n lunar logs -l app.kubernetes.io/component=hub-migrate --tail=200
# Hub pods:
kubectl -n lunar logs -l app.kubernetes.io/component=hub --tail=200
```
Common first-install failures (visible while the Hub is starting up):
| Symptom in logs | Fix |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pq: permission denied for schema public` | The DB role lacks `CREATE` on the database. Grant it, or use a database-owner role. See [prerequisites step 3](/install/lunar-hub/hub-prereqs#step-3--provision-postgresql). |
| `dial tcp ...: i/o timeout` | The Hub pod can't reach Postgres on the network — security group, network policy, or firewall block between the pod and the DB. Check VPC routing and any `NetworkPolicy` in the `lunar` namespace. |
| `dial tcp ...: connect: connection refused` | Postgres is reachable but not listening on the configured port (`hub.db.port`, default `5432`), or the process is down. |
| `lookup ...: no such host` | DNS issue — the DB hostname doesn't resolve from inside the cluster. |
| `failed to parse private key` | The `lunar-github-app` secret doesn't contain a valid PEM, or the PEM wasn't base64-encoded before going into the secret value (see the base64 note in [Step 3](#step-3--create-kubernetes-secrets)). Recreate from the PEM you saved during [prerequisites step 5](/install/lunar-hub/hub-prereqs#step-5--create-a-github-app). |
The Hub validates Postgres at startup, but **defers GitHub and S3 to first use** — those misconfigurations won't appear in install logs. They surface once something exercises them (e.g. `lunar hub pull github://...` or a script run):
| Symptom (after triggering an operation) | Likely cause |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` from GitHub API | Wrong `hub.github.app.id`, or the PEM in the `lunar-github-app` secret doesn't match the App GitHub knows about. |
| `404 Not Found` on `installations//...` | Wrong `hub.github.app.installId`, or the App is no longer installed on the org. |
| `AccessDenied` from S3 | IAM policy too narrow — confirm `s3:GetObject` and `s3:PutObject` on both buckets. See [prerequisites step 4](/install/lunar-hub/hub-prereqs#step-4--provision-s3-compatible-object-storage). |
| `NoSuchBucket` from S3 | Bucket name mismatch between `hub.s3.logsBucket` / `hub.s3.resourcesBucket` and what actually exists. |
| `PermanentRedirect` from S3 | `AWS_REGION` doesn't match the bucket's region. |
## Step 6 — Verify the install
Once the Hub and Operator pods are `Running 1/1`, confirm the Hub is healthy end to end.
**Retrieve the Hub auth token** — the chart generated this on first install. You'll need it for the CLI step below.
```bash
kubectl -n lunar get secret lunar-auth-token \
-o jsonpath='{.data.token}' | base64 -d
```
**Grafana access** — this depends on which [Grafana option](#grafana) you chose.
If you use the **bundled Grafana** (Option A), retrieve its auto-generated admin credentials:
```bash
kubectl -n lunar get secret lunar-grafana-admin \
-o jsonpath='{.data.username}' | base64 -d
kubectl -n lunar get secret lunar-grafana-admin \
-o jsonpath='{.data.password}' | base64 -d
```
The commands above assume the release name `lunar` (from `helm install lunar ...`). For other release names, see [Required secrets](https://github.com/earthly/charts/blob/main/README.md#required-secrets) in the chart README for the resolved name.
Open `https://grafana.lunar.example.com` and log in with the credentials above. The home dashboard surfaces policy results, component health, and collection activity. If the page doesn't load, confirm the `grafana.lunar.example.com` `A` / `CNAME` record points at your ingress controller and the cert is valid.
If you pointed Lunar at **your own Grafana** (Option B or C), log in there with your existing credentials — the Lunar dashboards appear in a "Lunar" folder.
**HTTP ingress reachability** — the webhook endpoint rejects unsigned requests but returns a predictable status, so it's a decent routing smoke test:
```bash
curl -sS -o /dev/null -w "%{http_code}\n" https://lunar.example.com/webhooks/github
```
Expected: `400` (the Hub rejects the request for missing headers). `404` or `502` probably means the HTTP Ingress isn't reaching the Hub — confirm `hub.ingress.enabled: true` in your values, and that DNS still resolves to your ingress controller.
**CLI connectivity smoke test** — install the [Lunar CLI](/install/cli), then save this minimal [`lunar-config.yml`](/configuration/lunar-config) locally and run:
```yaml
version: 0
hub:
host: lunar.example.com
grpcPort: 443
httpPort: 443
collectors: []
policies: []
```
```bash
export LUNAR_HUB_TOKEN=
lunar secret list
```
This authenticates over gRPC and returns the configured script runtime secrets (an empty list on a fresh install). Success means the CLI can reach the Hub through ingress, TLS terminates correctly, and the auth token is valid. Adjust the ports if you're using NodePort or non-default ingress.
**End-to-end with a config repo** — if you have a [`lunar-config.yml`](/configuration/lunar-config) repository ready, pull it in:
```bash
lunar hub pull github://your-org/your-config-repo@main
```
This exercises the full path: CLI → Hub → GitHub (App auth) → repo fetch → Hub stores config. As a side effect, the Hub registers a webhook on every repo referenced in the config. Verify webhook registration by checking any of those repos → **Settings → Webhooks** in GitHub — you should see a new entry pointing at `https://lunar.example.com/webhooks/github`.
If you don't have a config repo yet, that's the natural next step — see [the lunar-config docs](/configuration/lunar-config) for setup.
## Script runtime secrets
Collectors or catalogers that hit external APIs (`github.*` collectors, Datadog, Jira, Linear, etc.) may need credentials at runtime. Each plugin's README in [`earthly/lunar-lib`](https://github.com/earthly/lunar-lib) lists the `LUNAR_SECRET_*` variables it expects — drop the prefix when writing the secret. The Hub re-adds `LUNAR_SECRET_` when it injects each key as an env var in the script pod, so `GH_TOKEN` in the secret surfaces as `$LUNAR_SECRET_GH_TOKEN` in the script.
Provision the secret with one `--from-literal` per variable:
```bash
kubectl -n lunar create secret generic lunar-script-secrets \
--from-literal=GH_TOKEN='' \
--from-literal=LINEAR_API_KEY=''
# ... one --from-literal per LUNAR_SECRET_* variable your plugins expect
```
Wire it into `values.yaml` (`hub.secrets.*.perKey` requires chart `2.2.0+`). The same secret can back both scopes; omit the one you don't use:
```yaml
hub:
secrets:
collector:
secretName: lunar-script-secrets
perKey: true
cataloger:
secretName: lunar-script-secrets
perKey: true
```
See [day-2 → Other secrets](/install/lunar-hub/hub-day2#other-secrets) for rotation.
## Next steps
* [Install the Lunar CLI](/install/cli) on your workstation.
* [Install the Lunar CI Agent](/install/lunar-ci-agent/agent-self-hosted) on your CI runners.
* [Day-2 operations](/install/lunar-hub/hub-day2) — upgrades, secret rotation, observability, uninstall.
# Day-2 Operations
This page covers what you need to run Lunar Hub after the initial install: upgrades, secret rotation, observability, and uninstall. For the per-version upgrade notes (what values changed, what to migrate), see the [chart README's Upgrading section](https://github.com/earthly/charts/blob/main/README.md#upgrading).
## Upgrading
```bash
helm repo update
helm upgrade lunar earthly/lunar \
--namespace lunar \
-f values.yaml
```
Migrations run once per release as a **pre-rollout Job** (`lunar-hub-migrate`), installed via a Helm pre-install/pre-upgrade hook that completes — and gates the rollout — before any new Hub pod is created. Serving pods then **assert the schema is current at boot and refuse to start if it's behind**, which also keeps scaled-up and restarted pods safe (they don't re-run the Job). Migrations are forward-only and an interrupted one is safe to retry.
**Before every upgrade:**
1. **Back up Postgres.** Migrations are forward-only. If you need to roll back, roll the database back.
2. **Preview the chart changes.** The [`helm-diff`](https://github.com/databus23/helm-diff) plugin is worth installing — `helm diff upgrade lunar earthly/lunar -f values.yaml` shows exactly what Kubernetes resources will change.
3. **Read the version-specific notes** in the [chart README](https://github.com/earthly/charts/blob/main/README.md#upgrading). Minor version bumps occasionally require values changes.
4. **Pin your new image tags** in `values.yaml`. Don't rely on the chart's default tags.
{% hint style="warning" %}
Migrations are forward-only — back up Postgres first (step 1). Author schema changes **expand/contract** (add first, drop in a later release) so the common upgrade stays zero-downtime: the migrate Job runs while the old-version pods keep serving, then Helm rolls the Deployment. Reserve a maintenance window only for an unavoidable breaking change, and confirm the budget with stakeholders — a heavy migration can take tens of minutes, during which the old version keeps serving.
{% endhint %}
With multiple replicas and a PodDisruptionBudget, Helm's rolling update replaces Hub pods a few at a time while the rest keep serving, so a routine upgrade has no API-unavailability window.
## Rotating secrets
Lunar's secrets split into two categories — **user-managed** (you create and rotate them) and **chart-managed** (auto-generated on first install, preserved across upgrades via `helm.sh/resource-policy: keep`). See [Required secrets](https://github.com/earthly/charts/blob/main/README.md#required-secrets) in the chart README for the full list and naming rules.
### Hub auth token (`-auth-token`)
Used by the CLI and CI agents to authenticate to the Hub. The Hub accepts a single token today — rotation requires a coordinated cutover. To force a regeneration, delete the secret and re-run `helm upgrade` (the chart will generate a fresh token):
```bash
kubectl -n lunar delete secret lunar-auth-token
helm upgrade lunar earthly/lunar -n lunar -f values.yaml
kubectl -n lunar rollout restart deployment/lunar-hub
kubectl -n lunar rollout restart deployment/lunar-operator
```
Both the Hub and the Operator read this token from the same secret (the Operator uses it as `OPERATOR_HUB_TOKEN` to call the Hub), so restart both. Retrieve the new token with `kubectl -n lunar get secret lunar-auth-token -o jsonpath='{.data.token}' | base64 -d`, then update every CI agent's `LUNAR_HUB_TOKEN` and every developer's CLI config. Active builds authenticated with the old token will fail mid-run and need to be retried. Dual-token support is on the roadmap.
To pin to an externally-managed token instead, set `hub.auth.secretName` in values to a secret you control — the chart will consume it instead of generating its own.
### GitHub App private key (`lunar-github-app`)
GitHub supports multiple active private keys per App — rotate with zero downtime:
1. **Generate a new key** in GitHub → **Apps → your App → Private keys → Generate a private key**. Download the new PEM.
2. **Update the Kubernetes secret** in place, matching the install-time encoding (the Hub expects a base64-encoded PEM inside the secret value):
```bash
kubectl -n lunar create secret generic lunar-github-app \
--from-literal=private-key="$(base64 < path/to/new-key.pem | tr -d '\n')" \
--dry-run=client -o yaml | kubectl apply -f -
```
3. **Roll the Hub** — `kubectl -n lunar rollout restart deployment/lunar-hub`. The App credentials (App ID, installation ID, private key) are read **once at boot** and frozen for the process lifetime, so updating the secret alone has no effect on running pods — a rolling restart is required. With multiple replicas the rollout is zero-downtime.
4. **Verify** webhooks still deliver successfully (GitHub → any repo → **Settings → Webhooks → Recent Deliveries**).
5. **Delete the old key** in GitHub.
### GitHub webhook secret (`-github-webhook`)
Changing the webhook secret requires re-registering every repo's webhook. Easier path: delete and regenerate, then re-pull your primary config to trigger re-registration.
```bash
kubectl -n lunar delete secret lunar-github-webhook
helm upgrade lunar earthly/lunar -n lunar -f values.yaml
kubectl -n lunar rollout restart deployment/lunar-hub
# Re-pull triggers webhook re-registration on every repo in your config.
lunar hub pull github://your-org/your-config-repo@main
```
During the window between Hub restart and `lunar hub pull`, per-repo webhooks from GitHub are still signed with the old secret, and the new Hub rejects them with a `500`. **GitHub does not auto-retry failed webhook deliveries** — any events in that window are lost unless you manually redeliver them from **Settings → Webhooks → Recent Deliveries** on the affected repos. Minimize the gap by running `lunar hub pull` immediately after the Hub restart comes up healthy.
### Database password (`lunar-db`)
Standard Kubernetes secret rotation. If your Postgres supports multiple active passwords (e.g. RDS password grace), rotate without downtime:
1. Set the new password in Postgres (keeping the old one active).
2. Update the `lunar-db` secret.
3. Restart the Hub.
4. Revoke the old password.
If your Postgres doesn't support multiple active passwords, expect \~1 minute of Hub unavailability during the rotation.
### Other secrets
A few secrets don't get their own recipe above:
| Secret | Managed by | Consumed by |
| -------------------------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------- |
| `-grafana-admin` | Chart | The bundled Grafana + the Hub (only in `grafana.mode: chart`) |
| `-grafana-db` — read-only `grafana_user` role | Chart | Grafana datasource — whenever dashboards deploy (bundled **or** your own) |
| Your own Grafana login (`HUB_GRAFANA_TOKEN`, or `HUB_GRAFANA_USER` + `HUB_GRAFANA_PASSWORD`) | You | Hub — only with your own Grafana ([Option B/C](/install/lunar-hub/hub-install#grafana)) |
| Hub licence JWT (example `lunar-hub-licence`) | You | Hub |
| Per-scope runtime secrets (`hub.secrets.{collector,cataloger,policy}.secretName`) | You | Hub |
The rotation shape follows the same split as the sections above:
* **Chart-managed** (Grafana admin): `kubectl delete secret ` → `helm upgrade` to regenerate → restart the consumer deployment. This does **not** apply to `-grafana-db` — treat it as immutable after install.
* **User-managed** (hub licence JWT, runtime secrets, your own Grafana credentials): update the secret in place (`kubectl apply` or `kubectl create --dry-run=client -o yaml | kubectl apply -f -`) → restart the consumer(s). After rotating your own Grafana credentials, restart the Hub so it picks up the new value — the next `helm upgrade` re-runs the chart's dashboard-deploy Job with it.
To find what consumes an arbitrary secret:
```bash
kubectl -n lunar get deployments -o yaml | grep -B2 ''
```
## Observability
### Logs
The Hub and Operator log in structured JSON by default (`logging.format: json`). Log level defaults to `info`; raise to `debug` temporarily by editing `values.yaml` and running `helm upgrade`.
The Hub and Operator don't ship logs anywhere themselves — they stream to stdout. To get them into your log aggregator, point a cluster-level log shipper (Fluent Bit, Vector, Datadog Agent, etc.) at the `lunar` namespace.
### Telemetry to Earthly
Hub tenant identity and telemetry destinations come from the signed licence JWT, not from `HUB_TENANT_ID`, `HUB_ELASTIC_*`, or `HUB_OTEL_*` environment variables.
The chart handles the mount and `HUB_LICENCE_FILE` wiring for you. Keep (or override) the licence secret reference in values:
```yaml
hub:
licence:
secretName: lunar-hub-licence
secretKey: hub-licence.jwt
# optional; defaults to /var/run/secrets/lunar/hub-licence.jwt
# filePath: /var/run/secrets/lunar/hub-licence.jwt
```
Rotation flow:
* Request a new JWT from Earthly.
* Update the Kubernetes secret value (`hub-licence.jwt`) in place.
* The Hub re-validates every 5 minutes and also enforces the exact `exp` boundary.
### Metrics
The Hub exports request-duration histograms (HTTP and gRPC) via OTLP when the active licence includes `telemetry.otel.endpoint` and `telemetry.otel.token`.
If `telemetry.otel` is omitted, the Hub falls back to writing metrics to a local temp file.
Secure (TLS) OTLP is not implemented yet, so OTLP export runs insecure today.
{% hint style="info" %}
The Hub does not export distributed traces today — only metrics. Trace support is on the roadmap.
{% endhint %}
### Aggregating metrics across replicas
With multiple replicas, be deliberate about how dashboards and alerts aggregate the Hub's job-queue metrics. Queue-depth **gauges** (e.g. `river_jobs`) read from the queue tables in Postgres, which are **shared** by every replica, so each replica reports the same global count — aggregate with **`max`** (or `avg`), never `sum`, which multiplies the backlog by the replica count. Per-replica **counters** are the opposite: `river_insert_count_total` / `river_work_count_total` count work done by *each* replica, so `sum(rate(...))` is the correct cluster-wide throughput.
### Diagnostics bundle
The Hub can produce a diagnostics bundle (Postgres queue state, recent error logs, slow-query stats) for support requests. Generate one with:
```bash
lunar hub get-logs
```
This collects `kubectl` logs from the Hub pods plus Postgres telemetry from the Hub, then writes a `lunar-hub-logs-.tar.gz` in the current directory and prints its path. Run it from a machine with `kubectl` access to the Hub's cluster and your Lunar CLI configured to reach the Hub. Common flags:
* `-n`, `--namespace` — Kubernetes namespace to read Hub pods from (defaults to the current kubectl context's namespace).
* `-o`, `--output` — path to write the bundle to (defaults to `lunar-hub-logs-.tar.gz` in the current directory).
* `--tail` — log lines to capture per container (default: `1000`).
The bundle gathers extra Postgres telemetry when the `pg_stat_statements` extension is enabled — without it the bundle still works, just with less query-performance data. To enable the extension:
* **Amazon RDS / Aurora:** add `pg_stat_statements` to `shared_preload_libraries` in the DB parameter group, then reboot the instance.
* **Self-managed:** add `pg_stat_statements` to `shared_preload_libraries` in `postgresql.conf` and restart, then `CREATE EXTENSION pg_stat_statements;` as a superuser.
The Hub does not require this extension — it's only used by the diagnostics path.
## Scaling
The Hub is stateless — all durable state lives in Postgres and S3 — so it scales **horizontally**: raise `hub.replicaCount` and the replicas coordinate through Postgres (leader election, advisory locks) with no peer-to-peer wiring. Size the connection pool against your Postgres `max_connections` first — see [Replicas and the Postgres connection budget](/install/lunar-hub/hub-install#replicas-and-the-postgres-connection-budget). Add a PodDisruptionBudget (`hub.podDisruptionBudget.enabled: true`) so node drains and rollouts keep a quorum.
Vertical scaling still helps a single busy replica: CPU, memory, and the Postgres pool via `hub.db.maxOpenConns` / `hub.db.maxPoolConns`.
Run throughput scales independently — raise `operator.maxConcurrent` and size run pod resources accordingly. See [`operator.scriptContainerSpec*`](https://github.com/earthly/charts/blob/main/README.md#values-reference) in the chart README.
### Leader election and periodic jobs
Exactly one replica is the elected **leader** at a time; it runs the periodic and maintenance jobs (cleanup, reconcile, backfill). Jobs marked `RunOnStart` fire **immediately whenever leadership is (re)acquired** — not just at process boot — so a failover re-runs them on the new leader. Their handlers must be **idempotent**; the current `RunOnStart` jobs already are. Don't add one whose effect isn't safe to repeat on an arbitrary leadership flip.
## Prioritizing core services over script pods
By default the Operator creates script pods (collectors, policies, catalogers) at the cluster's default priority — the same priority as the Hub, Operator, and Grafana. When those script pods share a node with the core services, a burst of runs can drive the node into memory pressure and the kubelet may evict a *core* pod when it should be shedding an ephemeral script instead.
This matters in two setups:
* **Single-namespace installs** — the Operator runs scripts in the same namespace (and usually the same node group) as the Hub, so core and ephemeral workloads compete for the same memory.
* **Shared scratch namespaces or node groups** — scripts land on nodes shared with other workloads, and you want Lunar's ephemeral pods to yield first under contention.
`operator.scriptPodPriorityClassName` (chart `>= 2.3.0`) sets the [PriorityClass](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/) on every script pod the Operator creates. Point it at a class whose value sits *below* your core services, and the kubelet evicts scripts first under pressure — the scheduler also won't preempt a higher-priority pod to make room for a script.
### Setup
1. **Create the PriorityClass.** The chart references it by name but does not create it.
```yaml
apiVersion: scheduling.k8s.io/v1
kind: PriorityClass
metadata:
name: lunar-script
value: -10 # negative → below the default (0) your core pods use
globalDefault: false
description: Ephemeral Lunar script pods; evicted before core services.
```
```bash
kubectl apply -f lunar-script-priorityclass.yaml
```
2. **Point the Operator at it** in `values.yaml`:
```yaml
operator:
scriptPodPriorityClassName: lunar-script
```
3. **Upgrade and restart the Operator** — only script pods created *after* the restart inherit the class:
```bash
helm upgrade lunar earthly/lunar -n lunar -f values.yaml
kubectl -n lunar rollout restart deployment/lunar-operator
```
Leave the Hub, Operator, and Grafana on the cluster default priority — don't set a class on them. The gap between their `0` and the script class's negative value is what orders eviction; you lower scripts rather than raise core services. In a shared scratch node group, pick a value below whatever neighbouring workloads run at so Lunar's scripts are the first thing to go.
{% hint style="warning" %}
PriorityClasses are **cluster-scoped**, and a pod that references one that doesn't exist is rejected at admission — so the Operator will fail to launch scripts until the class is applied. Create the class *before* (or in the same change as) the `helm upgrade`, and delete it only once no workload references it.
{% endhint %}
{% hint style="info" %}
Priority orders *who gets evicted first* — it is not a resource cap. Keep your script pod requests/limits set (see [`operator.scriptContainerSpec*`](https://github.com/earthly/charts/blob/main/README.md#values-reference) in the chart README) so a single run can't consume a whole node before the kubelet reacts. Priority decides the order; requests and limits decide the ceiling.
{% endhint %}
## Backup and disaster recovery
Lunar's authoritative state lives in the systems you already back up:
* **Postgres** — use your existing Postgres backup process. Everything the Hub cares about (components, policies, run history, queue state) is here.
* **S3 buckets** — enable object versioning on both buckets and, if compliance requires, cross-region replication. Lost resource archives cause re-building the cache of catalogers, collectors, and policies; lost log archives mean lost history. Neither impedes Hub operation.
* **Hub local scratch** — each Hub pod's `/var/lib/lunar` is an ephemeral `emptyDir` (re-extracted runtimes and cached bundles; the authoritative copy is in S3). It is per-pod and regenerable, so there's nothing to back up.
* **Kubernetes secrets** — keep the GitHub App PEM, DB credentials, auth token, and webhook secret in your organization's secret-management system of record. Losing them means re-provisioning.
## Uninstalling
```bash
helm uninstall lunar --namespace lunar
```
Helm removes all resources the chart created: the Hub and operator deployments, services, ingress, RBAC, and service accounts.
**Not removed automatically:**
* The `lunar` namespace itself (and, if used, the Operator's execution namespace).
* Kubernetes secrets you created manually (e.g. `lunar-db`, `lunar-github-app`, `lunar-hub-licence`).
* Chart-managed secrets (`-auth-token`, `-github-webhook`, `-grafana-admin`). These carry `helm.sh/resource-policy: keep` so a re-install reuses the same values — by design. Delete them explicitly if you want fresh credentials on the next install.
* Your Postgres database, S3 buckets, or their contents.
* The GitHub App. Webhooks previously registered by this Hub are tagged with the Hub's instance ID (`earthly-lunar-` as a URL fragment); they remain on your repos until you remove them manually or install a fresh Hub with the same tenant ID, which will clean up its own stale webhooks on next config pull.
To fully tear down:
```bash
helm uninstall lunar --namespace lunar
kubectl -n lunar delete secret lunar-db lunar-github-app \
lunar-hub-licence \
lunar-auth-token lunar-github-webhook lunar-grafana-admin \
--ignore-not-found
kubectl delete namespace lunar
# Externally:
# - Drop the Postgres database
# - Delete or empty the S3 buckets
# - Uninstall the GitHub App from your organization
```
## Getting help
* [Chart values reference](https://github.com/earthly/charts/blob/main/README.md#values-reference)
* [Chart source](https://github.com/earthly/charts)
* [Lunar source](https://github.com/earthly/lunar)
* For enterprise onboarding or production sizing guidance, [contact the Earthly team](https://earthly.dev/earthly-lunar/demo).
# Lunar Dedicated
Lunar Dedicated is a single-tenant Lunar install that Earthly provisions, operates, and upgrades end-to-end in a dedicated AWS account, reachable only over private networking.
Lunar Dedicated is a fully managed, single-tenant Lunar install. Earthly provisions, operates, and upgrades it end-to-end in an AWS account dedicated to you, and it runs behind private networking that you reach from your own network. It's for teams that want Lunar's guardrails without running the [Hub](/install/lunar-hub/hub-overview) themselves.
This page explains how it works, who it fits, and what Earthly needs from you to stand one up.
{% hint style="info" %}
Lunar Dedicated is a managed offering, distinct from the self-hosted [Lunar Hub](/install/lunar-hub/hub-overview). With Dedicated, Earthly runs the infrastructure; with the self-hosted Hub, you do. The CLI and CI agent are installed and configured the same way in both.
{% endhint %}
## How it works
```mermaid
flowchart LR
GH["GitHub.com"]
subgraph Earthly["Earthly (management account)"]
Mgmt["Deploy and operate tooling"]
end
subgraph Dedicated["Your dedicated AWS account"]
Hub["Lunar Hub
(private)"]
WH["Webhook listener
(public)"]
Data[("Postgres · S3 · secrets")]
Hub --> Data
end
subgraph You["Your network"]
CI["CI runners · Lunar CLI"]
end
Mgmt -- "assume-role (IAM)" --> Dedicated
CI -- "PrivateLink / peering" --> Hub
GH -- "webhooks" --> WH
```
* **One dedicated AWS account.** The strongest isolation AWS offers — a hard billing and security boundary, with nothing else running inside it.
* **Earthly operates it by assuming an IAM role.** Management is identity-based, so Earthly needs no VPN or peering to run your install.
* **The hub is private.** You reach it over PrivateLink or a joined network (peering / Transit Gateway). The only thing exposed to the public internet is a locked-down GitHub webhook listener.
* **Your data stays in the install.** Authoritative state (Postgres), run inputs and outputs (S3), and secrets all live in your dedicated account and region. Earthly stores none of your data centrally.
* **Earthly manages the whole lifecycle.** Provisioning, version upgrades, patching, and monitoring — on a [maintenance schedule](#maintenance-and-upgrades) you choose.
## Requirements
Lunar Dedicated fits cleanly when the following are true:
| Requirement | Detail |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **A network to connect from** | An AWS VPC you can peer/route to the install, or that can reach a PrivateLink endpoint. The hub is private and never exposed to the public internet. |
| **Network-reachable CI** | The Lunar CLI and [CI agent](/install/lunar-ci-agent/agent-self-hosted) must run where they can reach the private hub — self-hosted runners in your network, or runners with VPN/PrivateLink access. |
| **An outbound allowlist you can permit** | The install needs egress for operational telemetry, container image pulls, and AWS APIs. |
| **A single region** | Each install lives in one AWS region. |
| **A GitHub App** | You create a GitHub App and install it on the org(s) and repositories Lunar should monitor. |
{% hint style="info" %}
**Coming soon.** Support for GitHub-hosted (public) CI runners, connecting with no existing AWS footprint (site-to-site VPN), and multi-region or high-availability installs are on the roadmap.
{% endhint %}
{% hint style="info" %}
**Need a fully air-gapped, no-egress install?** Dedicated isn't air-gapped — it requires outbound egress to operate. For an air-gapped environment, the [self-hosted Lunar Hub](/install/lunar-hub/hub-overview) is a better fit — [book a demo](https://earthly.dev/book-demo/) to work with us.
{% endhint %}
## How you connect
Every install is private. There are two ways to reach it — Earthly helps you pick based on where your CI runs and whether Lunar needs to reach systems that aren't on the public internet.
| | **PrivateLink** (typical starting point) | **Joined network** (peering / Transit Gateway) |
| -------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------- |
| What it is | Private one-way "doors" between your network and the install | Your network and the install's network are routed together |
| Reaching the hub | Through one private endpoint you create | Over the joined network, at a private address |
| Lunar reaching *your* internal systems | One private door per internal target | Anything your routes and firewall rules allow |
| Address coordination | None — address ranges can overlap freely | Address ranges must not overlap |
| Best when | You want tight, per-service exposure and minimal coordination | You already run a Transit Gateway, or Lunar needs many internal targets |
{% hint style="info" %}
Lunar's collectors, catalogers, and policies run *inside* your install and reach out to the systems they gather data from — which, for a dedicated customer, may be internal (internal Git, registries, ticketing, internal APIs). That's why connectivity is two-way, and why onboarding asks where your CI runs and what your collectors need to reach.
{% endhint %}
## What Earthly needs from you
These answers shape your install:
| What | Why |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Region** | Where the install (and your data) lives |
| **Connectivity** | PrivateLink or joined network — plus where your CI runs, and whether collectors need internal systems |
| **DNS** | Use Earthly's subdomain (`you.dedicated.earthly.dev`), or delegate a subdomain of your own (e.g. `lunar.yourco.com`) for Earthly to manage |
| **GitHub App** | You create it and tell us the org(s)/repos it's installed on |
| **Sizing** | Rough org/repo count and CI volume, which maps to a t-shirt size (final sizing confirmed together) |
| **Maintenance windows** | A recurring weekly app window and a monthly infra window, in your timezone |
| **Contacts** | An operations contact (for maintenance notices) and a security contact (for incidents) |
| **WAF** (optional) | A web-application firewall on the public webhook listener — off by default, or on with a rule group you provide |
## Setup
Earthly handles initial provisioning and setup. This includes account creation, infrastructure provisioning, bringing up your hub, every upgrade (within your chosen window), version selection, monitoring, backup/restore, and clean offboarding.
However, we do need some help from your end.
### What you do
{% stepper %}
{% step %}
### Kickoff
Answer the [questionnaire](#what-earthly-needs-from-you) above. These answers parameterize your install.
{% endstep %}
{% step %}
### Create your GitHub App
Create a GitHub App and install it on your org. Use the [hosted setup tool](https://earthly.dev/lunar/github-app-setup/), or see [manual GitHub App setup](/install/lunar-hub/hub-github-app-manual) if your security review needs every permission laid out first. Hand Earthly the App ID and the org(s) it's installed on.
{% endstep %}
{% step %}
### Go live
Earthly provisions the install and hands you an access token plus your install's Grafana login. Then:
* **Load your workload secrets** (the API keys your catalogers, collectors, and policies need) via the CLI:
```bash
lunar secret set DATADOG_API_KEY --scope collector # value read from stdin
```
* **Complete one network step** — for **PrivateLink**, create the inbound endpoint(s), and coordinate with Earthly; for a **joined network**, accept the network join and add the routes Earthly provides (usually your networking team). If you delegated a subdomain, add the NS records Earthly provides to hand off the zone — Earthly manages every record and the TLS cert under it.
{% endstep %}
{% endstepper %}
## Maintenance and upgrades
The Earthly team manages Lunar Hub updates for you; you choose *when* upgrades land. There are two recurring maintenance windows:
* **A weekly app window** for routine Lunar version bumps — a brief hub restart.
* **A monthly infra window** for node patches, add-on updates, and the occasional Kubernetes upgrade.
The hub runs as a single replica, so each upgrade is a brief, scheduled pause while it restarts. Planned windows are excluded from the uptime clock. Critical security patches and forced version deprecations can land out-of-window, with notice.
## Security and data
How a Dedicated install handles isolation, data, secrets, and audit:
* **Exclusive, isolated account.** Your install runs alone in a dedicated AWS account — no other workloads.
* **Your data stays put.** Authoritative state (Postgres), run inputs/outputs (S3), and secrets all live in your dedicated account and region. Earthly stores none of your data centrally.
* **Secrets are encrypted at rest.** Your GitHub App credentials and your workload secrets (API keys) live encrypted inside your install — workload secrets go straight to your hub via the CLI, never through Earthly's central systems.
* **Full audit visibility.** Every action Earthly's roles take is recorded in AWS CloudTrail.
* **Defined data lifecycle.** Run inputs and outputs are retained 30 days. On exit, Earthly returns your data (a portable database dump plus your storage buckets) and **provably deletes** the install by destroying its encryption keys, with the deletion recorded in CloudTrail.
* **Operational telemetry is required.** The install sends metrics and logs back to Earthly so it can monitor the install and meet the SLA. This covers operational data only — never your source code, data, or secrets — and Earthly details exactly what it includes in your security review. If you need telemetry fully off, the [self-hosted Lunar Hub](/install/lunar-hub/hub-overview) is a better fit — [book a demo](https://earthly.dev/book-demo/).
{% hint style="warning" %}
**Custody is audited, not zero-knowledge.** Your secrets are encrypted with a key that lives inside your account and is readable only by the hub. Routine operation can't read your secrets, and any access that could is a deliberate, audited action. It is not a cryptographic guarantee that Earthly *cannot* read them. If you need hard zero-knowledge, the [self-hosted Lunar Hub](/install/lunar-hub/hub-overview) is the better fit — [book a demo](https://earthly.dev/book-demo/).
{% endhint %}
## What's included
* A single-tenant, fully managed Lunar install in a dedicated AWS account
* Private hub access via PrivateLink or a joined network
* A single region per install
* Full lifecycle management: provisioning, upgrades, patching, monitoring, backup/restore, and clean offboarding
## Next steps
Earthly walks through the model live, answers your security team's questions, and maps out what onboarding looks like for your environment.
Book a demo
# Lunar CI Agent
# Self-Hosted Runners
Install the Lunar CI Agent on self-hosted runners to instrument CI/CD pipelines and collect metadata during builds, tests, scans, and deploys.
The Lunar CI Agent instruments CI/CD pipelines to collect metadata during builds, tests, scans, and deployments. It wraps your existing runner process, monitors execution, and triggers scripts at the right moments.
This page covers the most common setup: **self-hosted runners** (including GitHub Actions self-hosted runners). If you're using GitHub-hosted managed runners, see [Managed Runners](/install/lunar-ci-agent/agent-managed).
## Prerequisites
You need an existing self-hosted runner infrastructure (e.g. GitHub Actions self-hosted runner). Lunar adds instrumentation on top of your existing setup — it does not manage the runner lifecycle.
## Adding to an Existing Runner
{% stepper %}
{% step %}
## Download and install the Lunar CLI
Download the Lunar CLI
Or via the command line:
```bash
curl -LO https://github.com/earthly/lunar-dist/releases/download/v2.5.0/lunar-linux-amd64
chmod +x lunar-linux-amd64 && sudo mv lunar-linux-amd64 /usr/local/bin/lunar
```
{% hint style="info" %}
Replace the version above with the latest from the [releases page](https://github.com/earthly/lunar-dist/releases/latest).
{% endhint %}
The CI agent is no longer installed separately. The CLI fetches it on first use through your Lunar Hub (see the last step), so the only binary you install here is `lunar`.
{% endstep %}
{% step %}
## Set the required environment variables
```bash
export LUNAR_CI_TYPE=github
export LUNAR_HUB_TOKEN=your_hub_token
export LUNAR_HUB_HOST=your_hub_host
export LUNAR_HUB_GRPC_PORT=your_grpc_port
export LUNAR_HUB_HTTP_PORT=your_http_port
export LUNAR_RUN_CMD=path_to_github_runner_run.sh
```
The agent auto-detects state, cache, and bundle directories based on the running user:
* **Root** → system paths (`/var/lib/lunar`, `/var/cache/lunar/git-repos`, `/var/tmp/lunar/...`).
* **Non-root** → user paths under `$HOME/.lunar/`.
Override any of them by setting `LUNAR_STATE_DIR`, `LUNAR_GIT_CACHE_DIR`, `LUNAR_BUNDLE_DIR`, `LUNAR_SNIPPET_DIR`, `LUNAR_SCRIPT_LOG_DIR`, `LUNAR_BIN_DIR`, or `LUNAR_LOCK_DIR` — useful for read-only rootfs runners, systemd units with `ProtectHome=`, or non-standard home directories.
{% endstep %}
{% step %}
## Run the agent
```bash
lunar ci-tracer run
```
On first run, `lunar ci-tracer run` downloads the agent through your Hub, verifies it, caches it under `LUNAR_BIN_DIR` (`$HOME/.lunar/bin` by default), and then runs it. Subsequent runs reuse the cached binary and skip the download.
{% hint style="info" %}
The Hub must be reachable the first time you run this on a host (or whenever the cache is empty). Once the agent binary is cached, the agent only needs the Hub for its normal runtime traffic.
{% endhint %}
{% hint style="info" %}
**Upgrading from an earlier agent install?** Previous versions shipped a separate `lunar-ci-agent` binary that you downloaded and started yourself. That separate download no longer exists — install only the `lunar` CLI and start the agent with `lunar ci-tracer run`, which fetches the agent for you.
{% endhint %}
{% hint style="info" %}
For production usage, run `lunar ci-tracer run` under a process supervisor such as `systemd` so it restarts automatically on failure. See [Systemd Configuration](/install/lunar-ci-agent/systemd) for an example unit file.
{% endhint %}
{% endstep %}
{% endstepper %}
## Using a Custom Runner Image
If your runners are containerized, install the `lunar` CLI inside a `Dockerfile` and make `lunar ci-tracer run` the entrypoint. The agent binary is fetched on first boot through your Hub — the build host does not need Hub connectivity:
{% code title="Dockerfile" %}
```dockerfile
FROM my-custom-runner-image:ubuntu-slim
ENV LUNAR_HUB_HOST=my.cool.host.com
ENV LUNAR_HUB_GRPC_PORT=443
ENV LUNAR_HUB_HTTP_PORT=443
ENV LUNAR_CI_TYPE=github
ENV LUNAR_RUN_CMD=/home/ubuntu/actions-runner/run.sh
# Replace /home/ubuntu with your runner user's home directory
ENV LUNAR_STATE_DIR=/home/ubuntu/.lunar/state
ENV LUNAR_GIT_CACHE_DIR=/home/ubuntu/.lunar/git-repos
ENV LUNAR_BUNDLE_DIR=/home/ubuntu/.lunar/bundles
ENV LUNAR_SNIPPET_DIR=/home/ubuntu/.lunar/snippets
ENV LUNAR_SCRIPT_LOG_DIR=/home/ubuntu/.lunar/scripts
ENV LUNAR_BIN_DIR=/home/ubuntu/.lunar/bin
ENV LUNAR_LOCK_DIR=/home/ubuntu/.lunar/lock
RUN curl -LO https://github.com/earthly/lunar-dist/releases/download/v2.5.0/lunar-linux-amd64 && \
chmod +x lunar-linux-amd64 && mv lunar-linux-amd64 /usr/local/bin/lunar
ENTRYPOINT ["lunar", "ci-tracer", "run"]
```
{% endcode %}
On the first container boot, `lunar ci-tracer run` accesses your Lunar Hub to download and cache the agent under `LUNAR_BIN_DIR`, then runs it. Subsequent boots reuse the cached binary **only if `LUNAR_BIN_DIR` is persisted** across container restarts (e.g. a mounted volume) — otherwise each fresh container downloads the agent again on first boot.
{% hint style="info" %}
**Optional: warm the cache at build time.** Run `lunar ci-tracer install` during the build to download and cache the agent without starting it. This requires the build host to reach the Hub. Pass the Hub token as a build secret so it never lands in an image layer:
```dockerfile
# syntax=docker/dockerfile:1
RUN --mount=type=secret,id=lunar_hub_token \
LUNAR_HUB_TOKEN="$(cat /run/secrets/lunar_hub_token)" \
lunar ci-tracer install
```
```bash
docker build --secret id=lunar_hub_token,env=LUNAR_HUB_TOKEN .
```
The agent is cached in `LUNAR_BIN_DIR`, so it's baked into the image layer. Make sure `LUNAR_BIN_DIR` points at a path that stays in the image.
{% endhint %}
{% hint style="info" %}
The GitHub Actions runner may not work correctly when run as root. See GitHub's [self-hosted runner documentation](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners) for details.
{% endhint %}
Bake everything into the image except secrets. Pass the Hub token at runtime:
```bash
docker run -e LUNAR_HUB_TOKEN=$(vault read /lunar/hub/token) runner-image:latest
```
Or in Kubernetes, reference a Secret:
```yaml
env:
- name: LUNAR_HUB_TOKEN
valueFrom:
secretKeyRef:
name: lunar-hub
key: token
```
For all environment variable details, see the [Configuration Reference](/install/lunar-ci-agent/agent-config).
***
## Running `sudo` and setuid binaries in traced workflows
To trace command execution, the agent installs a seccomp filter on the runner process. Linux only permits installing that filter when the process either holds the `CAP_SYS_ADMIN` capability or has the `no_new_privs` flag set. When the runner does **not** have `CAP_SYS_ADMIN`, the agent falls back to setting `no_new_privs`, which makes the kernel ignore the setuid bit. Non-root processes can then no longer escalate through setuid-root binaries — `sudo`, for example, refuses to run:
```
sudo: The "no new privileges" flag is set, which prevents sudo from running as root.
```
`no_new_privs` is inherited by every child process and can never be cleared, so this affects any unprivileged user your workflow switches to, not just the top-level runner user.
To keep `sudo` and other setuid binaries working under tracing, run the runner **as root** in a container that adds `CAP_SYS_ADMIN`. The agent detects the capability on the runner process and skips `no_new_privs`, installing the seccomp filter through the capability instead.
{% code title="docker" %}
```bash
docker run --cap-add SYS_ADMIN runner-image:latest
```
{% endcode %}
{% code title="kubernetes" %}
```yaml
securityContext:
capabilities:
add: ["SYS_ADMIN"]
```
{% endcode %}
{% hint style="info" %}
The runner must run **as root** for this to take effect: a capability added to a container is only held by a root (uid 0) process. A non-root runner process does not gain `CAP_SYS_ADMIN` from the container, so the agent still falls back to `no_new_privs` there.
{% endhint %}
{% hint style="warning" %}
`CAP_SYS_ADMIN` is a broad, privileged capability — grant it only when your workflows genuinely need setuid escalation (e.g. `sudo`) under tracing. On [GitHub-hosted managed runners](/install/lunar-ci-agent/agent-managed) the job runs as the non-root `runner` user with no way to hold `CAP_SYS_ADMIN` — its passwordless `sudo` is a sudoers grant, not a capability — so setuid escalation is not supported while tracing there.
{% endhint %}
***
## Next Steps
Once installed, you can begin configuring:
* [Collectors](/configuration/lunar-config/collectors) to gather SDLC data
* [Policies](/configuration/lunar-config/policies) to enforce standards
* [Domains and Components](/docs/key-concepts) to organize your software landscape
For questions or enterprise onboarding:
Contact the Earthly team
# Managed Runners
Use the Lunar CI Tracer action to instrument GitHub-hosted and self-hosted GitHub Actions runners with the Lunar CI Agent.
The [`earthly/lunar-ci-tracer`](https://github.com/earthly/lunar-ci-tracer) action is the easiest way to add the Lunar CI Agent to your GitHub Actions workflows. It works with both **GitHub-hosted** and **self-hosted** runners.
For **GitHub-hosted runners** (managed runners), this action is the only installation method — you cannot modify the runner startup process.
For **self-hosted runners**, you can either use this action or configure the agent to [wrap the runner's `run.sh` command](/install/lunar-ci-agent/agent-self-hosted) directly, which avoids adding a step to every job.
## Setup
Add the Lunar CI Tracer action as an early step in your workflow jobs:
```yaml
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Run Lunar CI Tracer
id: lunar
uses: earthly/lunar-ci-tracer@
env:
LUNAR_HUB_TOKEN: ${{ secrets.LUNAR_HUB_TOKEN }}
LUNAR_HUB_HOST: your_hub_host
- uses: actions/checkout@v5
# ... rest of your workflow
```
The action installs the `lunar` CLI for you (no pre-install step needed) and runs `lunar ci-tracer run`, which fetches the agent through your Lunar Hub on first use, verifies it, and attaches it to the job process. All subsequent steps in the job are automatically instrumented. Your Hub must be reachable when the action starts.
## How It Works
The action runs as a step in a job. It downloads the `lunar` CLI, then runs `lunar ci-tracer run`, which fetches the agent through your Hub on first use and execs it. The agent attaches to the current shell process via ptrace and traces all commands executed by subsequent steps. The agent exits automatically when the job completes.
The same [configuration reference](/install/lunar-ci-agent/agent-config) applies. The only difference is that `LUNAR_RUN_CMD` is not needed — the action handles process supervision internally.
{% hint style="warning" %}
For self-hosted runners that require the use of `sudo` in workflows, the `CAP_SYS_ADMIN` capability should be provided — see [Running `sudo` and setuid binaries in traced workflows](/install/lunar-ci-agent/agent-self-hosted).
{% endhint %}
## Failure Handling
Agent installation failures (CLI download, agent download through the Hub, agent startup) are gated by `LUNAR_STRICT_MODE`:
* `LUNAR_STRICT_MODE=true` — the step **fails** with the error output.
* Unset or `false` (default) — the action emits an `::error::` annotation plus a warning, sets the `agent-installed` output to `false`, and the step **succeeds** so the rest of the job continues uninstrumented.
The action exposes an `agent-installed` output (`'true'` / `'false'`) so downstream steps can branch on whether instrumentation is active:
```yaml
- name: Run checks that need the tracer
if: steps.lunar.outputs.agent-installed == 'true'
run: ./run-traced-tests.sh
```
# Configuration Reference
Reference for all environment variables that configure the Lunar CI Agent, including required settings, Docker options, and state directories.
## Required
| Variable | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LUNAR_HUB_TOKEN` | Auth token for your Hub installation. |
| `LUNAR_HUB_HOST` | Hostname of your Hub installation. Must be reachable from the runner. |
| `LUNAR_HUB_GRPC_PORT` | Hub's gRPC port. Used for configuration sync, collection results, and GitHub token resolution. |
| `LUNAR_HUB_HTTP_PORT` | Hub's HTTP port. Used for log uploads and script downloads. |
| `LUNAR_CI_TYPE` | CI platform type: `github` (GitHub Actions) or `buildkite`. See [Buildkite](/install/lunar-ci-agent/buildkite) for Buildkite setup. |
| `LUNAR_RUN_CMD` | Command to start the runner process. For GitHub Actions self-hosted runners, this is the path to `run.sh` (e.g. `/home/ubuntu/actions-runner/run.sh`). Not needed when using the [managed runners](/install/lunar-ci-agent/agent-managed) GitHub Action. |
## Optional
| Variable | Default | Description |
| --------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LUNAR_HUB_INSECURE` | `false` | Set to `true` when connecting to a Hub instance without TLS. |
| `LUNAR_UPDATE_PERIOD` | `15s` | How often the agent polls Hub for configuration updates. |
| `LUNAR_LOG_LEVEL` | `info` | Log verbosity. Set to `debug` for troubleshooting. |
| `LUNAR_GITHUB_HOST` | `github.com` | The GitHub host whose components this agent collects for (the `` in `//` component names). Auto-detected from `GITHUB_SERVER_URL` when the agent runs as a GitHub Actions step (including via the Lunar CI Action), so **GitHub Enterprise Server "just works"** there. Set it explicitly only when the agent can't see `GITHUB_SERVER_URL` — e.g. when wrapping a self-hosted runner's `run.sh` directly — or to override. (Replaces the former `LUNAR_GIT_BASE_URL`.) |
## Advanced
### Docker
These options are for environments where collectors or policies run in Docker containers (e.g. private registries, custom networks, or sidecar Docker daemons).
| Variable | Default | Description |
| ---------------------------- | -------- | -------------------------------------------------------------------------- |
| `LUNAR_DOCKER_REGISTRY_USER` | *(none)* | Username for a private Docker registry containing collector/policy images. |
| `LUNAR_DOCKER_REGISTRY_PASS` | *(none)* | Password for a private Docker registry containing collector/policy images. |
| `LUNAR_DOCKER_NETWORK` | *(none)* | Docker network for script container execution. |
### State Directories
The agent uses several directories for state, caching, and execution. The defaults listed below are the root-user paths. When running as a non-root user, the agent automatically falls back to `$HOME/.lunar/` paths (e.g. `$HOME/.lunar/state` instead of `/var/lib/lunar`), so manual overrides are usually unnecessary. You can still set these variables explicitly if you need non-standard locations.
| Variable | Default | Description |
| ---------------------- | ---------------------------- | ----------------------------------------------------- |
| `LUNAR_STATE_DIR` | `/var/lib/lunar` | Script execution state and embedded runtimes. |
| `LUNAR_GIT_CACHE_DIR` | `/var/cache/lunar/git-repos` | Cached git repository clones. |
| `LUNAR_BUNDLE_DIR` | `/var/tmp/lunar/bundles` | Component JSON bundles for policy evaluation. |
| `LUNAR_SNIPPET_DIR` | `/var/lib/lunar/snippets` | Downloaded script code from Hub. |
| `LUNAR_SCRIPT_LOG_DIR` | `/var/tmp/lunar/scripts` | Script execution logs (uploaded to Hub). |
| `LUNAR_BIN_DIR` | `/usr/lib/lunar` | Embedded runtime binaries. |
| `LUNAR_LOCK_DIR` | `/run/lock/lunar` | Installation lock files to prevent parallel installs. |
# Buildkite
Run Lunar on Buildkite — trace builds with a Buildkite agent command hook and deliver build status to Lunar Hub with a Notification Service webhook.
Lunar instruments Buildkite with two pieces:
1. A Buildkite agent **`command` hook** (`command` is Buildkite's agent-hook type) that wraps each command with Lunar tracing, so collectors run and their data is attributed to your components.
2. A Buildkite **Notification Service webhook** to Lunar Hub, so Lunar Hub knows a build ran and CI-dependent policies wait for it instead of finalizing early.
{% hint style="info" %}
Lunar listens to **two** webhooks that drive different things: your **source-control (SCM)** webhook carries source events (push / pull request) and owns component identity, while the **Buildkite** webhook reports that a build ran so CI-dependent policies wait for it. Buildkite is the CI layer; your SCM is the source host — Buildkite tracing works against the source host your components are already registered with.
{% endhint %}
## Setup
### Step 1 — Agent command hook (tracing)
On your Buildkite agent, add a `command` hook (in the agent's `hooks/` directory) that exports the Lunar configuration and runs `lunar ci-tracer run` to trace the build's command:
```bash
# hooks/command
set -e
export LUNAR_CI_TYPE=buildkite
export LUNAR_RUN_CMD="bash -c \"$BUILDKITE_COMMAND\""
export LUNAR_HUB_HOST=hub.example.com
export LUNAR_HUB_TOKEN="$LUNAR_HUB_TOKEN"
lunar ci-tracer run
```
The `lunar` CLI installs the CI tracer on first use and caches it, so no separate agent binary needs to be installed on the runner. Source-control credentials (used for changed-file inference) are fetched from Lunar Hub, so no GitHub token is needed on the runner.
The Hub host and ports resolve in order: explicit `LUNAR_HUB_*` env vars, then the `hub:` block of a `lunar-config.yml` the runner can read, then a default of `443` for both gRPC and HTTP. Set `LUNAR_HUB_GRPC_PORT` / `LUNAR_HUB_HTTP_PORT` only for a Hub on non-default ports that isn't declared in a manifest. See the [Configuration Reference](/install/lunar-ci-agent/agent-config) for the full set of `LUNAR_*` variables.
### Step 2 — Notification Service webhook (build status)
Without the webhook, Lunar Hub never learns a Buildkite build happened, so CI-dependent policies would finalize before the build's data lands. In Buildkite, go to **Organization Settings → Notification Services → Add → Webhook** (the service is org-level, not per-pipeline) and configure it so Lunar Hub records each build:
* **URL**: `https:///webhooks/buildkite`
* **Token**: set a shared token and configure Lunar Hub with `HUB_BUILDKITE_WEBHOOK_TOKEN` to the same value. Lunar Hub verifies the `X-Buildkite-Token` header on every request; an unset token rejects all requests.
* **Events**: `build.scheduled`, `build.running`, `build.finished`.
{% hint style="warning" %}
The webhook endpoint must be reachable from Buildkite's servers, so it's exposed to the public internet — the same posture as your SCM webhook endpoint. Keep it behind TLS and rely on the shared `X-Buildkite-Token` for authentication; Lunar Hub rejects every request whose token doesn't match.
{% endhint %}
Lunar Hub creates a workflow-run record per build, associates it with the build's commit (and pull request, for PR builds), and re-evaluates CI-dependent policies when a build finishes.
## Component attribution
Lunar reads the standard `BUILDKITE_*` environment to attribute collected data to components. In a monorepo, set one of the following in your pipeline so a build maps to the right subdirectory component (see [Components](/configuration/lunar-config/components)):
* `LUNAR_COMPONENT` — name the component(s) explicitly (comma-separated).
* `ciPipelines` on the component — matches the Buildkite **pipeline name**.
* `LUNAR_COMPONENT_INFER=true` — infer from changed paths (PR builds) or the working directory.
## Scope and limitations
* **Command-level** collection is supported (`ci-before/after-command` hooks). Job- and step-level scopes are not yet collected by Lunar.
* **Changed-path** component inference resolves for **pull-request** builds; push builds fall back to working-directory inference (Buildkite provides no prior-commit SHA to diff against).
* **One CI provider per repo** — the first Buildkite build marks the repo as Buildkite-driven, and any other CI provider's doneness probe then skips it. Running two CI providers against the same repo isn't supported.
# Systemd
Run Lunar as a systemd service on Linux hosts with a sample unit file for reliable startup, restarts, and environment configuration.
Systemd is a system and service manager for Linux that provides a standardized way to define and control how services start, stop, and behave on boot.
For Lunar, systemd may be used to ensure that the application is reliably managed, automatically started at boot, and cleanly shut down or reloaded when needed.
Here's a simple systemd unit file that will run `lunar` in a resilient way.
{% code title="lunar.service" %}
```ini
[Unit]
Description=Lunar CI Agent
After=network.target
[Service]
Type=simple
WorkingDirectory=/home/ubuntu
ExecStart=/usr/local/bin/lunar ci-tracer run
EnvironmentFile=/etc/lunar.env
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
```
{% endcode %}
# Sync Config GitHub Action
Use the Lunar sync-config GitHub Action to push your config repo to Lunar Hub on every push.
The [`earthly/lunar-actions/sync-config`](https://github.com/earthly/lunar-actions/tree/main/sync-config) action pushes the latest config (manifest + snippets) from your config repo into Lunar Hub. Run it on every push to your config repo's primary branch so the hub stays in sync.
{% hint style="info" %}
**First time setting up a config repo?** Fork [`earthly/lunar-config-template`](https://github.com/earthly/lunar-config-template) — it ships with this workflow pre-wired so you only need to set the `LUNAR_HUB_TOKEN` secret and push.
{% endhint %}
## How it works
`sync-config` is a thin wrapper around the [`lunar hub pull`](/docs/lunar-cli#lunar-hub-pull) CLI command. The action's inputs map 1:1 to the equivalent CLI flags — see the [CLI reference](/docs/lunar-cli) for the full semantics of each.
## Example
```yaml
name: Sync Lunar Config
on:
push:
branches: [main]
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: earthly/lunar-actions/sync-config@main
with:
manifest-url: github://my-org/my-config-repo@main
hub-token: ${{ secrets.LUNAR_HUB_TOKEN }}
hub-host: hub.example.com
lunar-version: v2.5.0
rerun-code-collectors: "true"
```
## Inputs
| Input | Required | Default | CLI equivalent |
| ----------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `manifest-url` | yes | — | `` positional argument (`github:///@`) |
| `hub-token` | yes | — | `LUNAR_HUB_TOKEN` env var |
| `hub-host` | yes | — | `LUNAR_HUB_HOST` env var |
| `lunar-version` | yes | — | Selects the [`lunar-dist`](https://github.com/earthly/lunar-dist/tags) release to download |
| `hub-grpc-port` | no | `443` | `LUNAR_HUB_GRPC_PORT` env var |
| `hub-http-port` | no | `443` | `LUNAR_HUB_HTTP_PORT` env var |
| `rerun-code-collectors` | no | `false` | `--rerun-code-collectors` / `-l` |
| `include-pr-commits` | no | `false` | `--include-pr-commits` |
| `pr-max-age-days` | no | `5` | `--pr-max-age-days` |
| `rerun-catalogers` | no | `false` | `--rerun-catalogers` / `-t` (requires lunar `v1.1.2+` — see [`lunar hub pull`](/docs/lunar-cli#lunar-hub-pull)) |
| `log-level` | no | `debug` | `LUNAR_LOG_LEVEL` env var |
{% hint style="info" %}
By default, pulling the config does **not** rerun catalogers or code collectors. Set `rerun-catalogers: "true"` or `rerun-code-collectors: "true"` to opt in. Per-component catalogers (`component-repo`, `component-cron`) are unaffected by these flags and continue to run on their own hooks.
{% endhint %}
## Versioning
Pin to `@main` for the latest, or to a release tag for stability. The `lunar-version` input selects the CLI version that gets downloaded; check the [`lunar-dist` releases](https://github.com/earthly/lunar-dist/tags) for the latest stable tag.
# AI Skills
Install AI agent skills for Claude Code, Codex, Cursor, and 50+ other agents to help build Lunar collectors, policies, and SQL queries.
The [earthly/skills](https://github.com/earthly/skills) repository provides AI agent skills for working with Lunar. These skills enable AI assistants to help you build custom plugins, edit your `lunar-config.yml`, and query Lunar's data model.
## Available Skills
| Skill | Description |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| [lunar-collector](https://github.com/earthly/skills/tree/main/skills/lunar-collector) | Create Lunar collector plugins (Bash scripts) that gather SDLC metadata |
| [lunar-cataloger](https://github.com/earthly/skills/tree/main/skills/lunar-cataloger) | Create Lunar cataloger plugins (Bash scripts) that build the software catalog from external systems or repo signals |
| [lunar-policy](https://github.com/earthly/skills/tree/main/skills/lunar-policy) | Create Lunar policy plugins (Python scripts) that enforce engineering standards |
| [lunar-config](https://github.com/earthly/skills/tree/main/skills/lunar-config) | Edit `lunar-config.yml` — wire together components, domains, collectors, policies, catalogers, and initiatives |
| [lunar-sql](https://github.com/earthly/skills/tree/main/skills/lunar-sql) | Craft SQL queries against Lunar's data model (components, checks, policies, domains, PRs) |
## Installation
Install with the [`skills`](https://github.com/vercel-labs/skills) CLI:
```bash
# Install all Lunar skills globally
npx skills add earthly/skills -g
# Or install a specific skill globally
npx skills add earthly/skills -g --skill lunar-policy
```
The CLI auto-detects which coding agents you have installed (Claude Code, Codex, Cursor, and 50+ more) and copies the skills to the right location. See the [`skills` CLI docs](https://github.com/vercel-labs/skills) for more commands like `list`, `update`, and `remove`.
Drop `-g` to install into the current project's `.claude/skills/` (or equivalent) instead — useful if you want to commit the skills into a shared team repo.
## Usage
These skills are designed to be used with AI agents that support the Claude/Codex skill format. Each skill contains:
* `SKILL.md` - Main instructions and quick-start guide
* `references/` - Curated documentation for the AI to consult as needed
Once installed, your AI assistant will automatically detect and use these skills when you ask it to build a Lunar plugin, edit your config, or query the SQL API.
## Related Resources
* [Bash SDK](/plugin-sdks/bash-sdk) - Manual reference for building collectors and catalogers
* [Python SDK](/plugin-sdks/python-sdk) - Manual reference for building policies
* [lunar-config.yml](/configuration/lunar-config) - Manual reference for the configuration file
* [SQL API](/sql-api/sql-api) - Manual reference for querying Lunar data
* [lunar-lib Repository](https://github.com/earthly/lunar-lib) - Reference collectors, catalogers, and policies
# Learn the basics
Walk through your first Lunar setup — populating components, defining policies, and running checks against your repositories.
This guide will help you understand the basic concepts of Lunar and get started with monitoring your engineering practices.
## Prerequisites
Before you begin, make sure you have:
1. Installed Lunar following the [installation guide](/install)
2. Access to your code repositories
3. Basic understanding of your CI/CD pipeline setup
## Basic Concepts
Lunar operates on a few key concepts:
1. **Components**: These are your software projects (services, libraries, repositories)
2. **Collectors**: These gather information about your components
3. **Policies**: These define rules and standards for your components
4. **Checks**: These are the results of policy evaluations
## Your First Lunar Setup
{% stepper %}
{% step %}
## Populate your Lunar configuration
Start by creating a `lunar-config.yml` file in your project root:
{% code title="lunar-config.yml" %}
```yaml
version: 0
hub:
host:
grpcPort:
httpPort:
# Use the official Lunar image for running scripts in containers
default_image: earthly/lunar-scripts:1.0.0
domains:
team1:
description: Main organization domain
components:
github.com/my-org/my-service:
owner: jane@example.com
domain: team1
collectors:
- name: readme-lines
runBash: |-
if [ -f ./README.md ]; then
lunar collect -j \
"repo.readme_exists" true \
"repo.readme_num_lines" "$(wc -l < ./README.md)"
else
lunar collect -j "repo.readme_exists" false
fi
hook:
type: code
policies: []
```
{% endcode %}
The `default_image` setting runs all collectors and policies inside Docker containers using the official `earthly/lunar-scripts` image. This image includes Python, Bash, the `lunar` CLI, and the `lunar-policy` package pre-installed. For more details on image configuration, see [Images](/configuration/lunar-config/images).
You will need to replace `github.com/my-org/my-service` with a real repository you want to monitor.
{% hint style="info" %}
Lunar can also auto-discover components from external systems like GitHub, Backstage, and other sources using catalogers. See the [catalogers documentation](/configuration/lunar-config/catalogers) for details on setting up automated component discovery. For now, this example will focus on manually declared components.
{% endhint %}
Commit this code to a new repository called `lunar`. To apply this configuration, run the following command:
```bash
lunar hub pull github://my-org/lunar@main
```
You should be able to see the new domain, the new component, and its component JSON being populated in the Lunar UI.
{% endstep %}
{% step %}
## Define your first policy
Add a policy to check your component:
{% code title="lunar-config.yml" %}
```yaml
policies:
- name: readme
description: "README.md standards"
on: ["domain:team1"]
runPython: |-
from lunar_policy import Check
with Check("readme-exists", "Repository should have a README.md file") as c:
c.assert_true(c.get_value(".repo.readme_exists"), "README.md file not found")
```
{% endcode %}
Since we're using the official `earthly/lunar-scripts` image (via `default_image`), the [Lunar Policy SDK](/plugin-sdks/python-sdk/policy) is already pre-installed—no `requirements.txt` needed.
Commit the code, and apply the new configuration:
```bash
lunar hub pull github://my-org/lunar@main
```
You should be able to see the new policy, and the checks being populated for this component in the Lunar UI.
Congratulations! You've just set up your first Lunar collector and policy.
{% endstep %}
{% endstepper %}
## See also
1. Learn more about [key concepts](/docs/key-concepts)
2. Explore [configuration options](/configuration/lunar-config)
3. Browse [200+ pre-built guardrails](https://earthly.dev/lunar/guardrails/) and [50+ integrations](https://earthly.dev/lunar/integrations/) instead of writing everything from scratch
4. Install [AI skills](/install/skills) for Claude Code, Codex, or Cursor to help build collectors and policies
# Key concepts
Overview of Lunar's core concepts — domains, components, collectors, catalogers, policies, and checks — and how they fit together.
This page describes the most important concepts in Lunar.
At a high-level, your software is organized into components (services or libraries), which often map to code repositories, or subdirectories in monorepos. The engineering processes of each software component in your system is instrumented by collectors. The collectors gather the information into a component JSON. Policies are then defined to create guardrails around your engineering practices. The policies are evaluated against the component JSON and create checks that have a pass or fail outcome.
## Domains
Domains are used to group related components together. Domains are hierarchical and can contain other domains.
Domains are useful to model complex inter-related systems, like multi-service applications, or hierarchical teams in large organizations.
## Components
Components are the building blocks of Lunar. They represent the entities that Lunar monitors. Components are independent pieces of software, such as microservices, or libraries.
Components usually correspond to git repositories, but they may also correspond to subdirectories in a monorepo.
## Component JSON
The Component JSON is an object that contains collected SDLC (software development lifecycle) metadata about a component. Collectors associated with a component contribute to the component JSON metadata via "metadata deltas". Together, all these deltas form a complete picture of the component in a merged JSON representation.
Examples of information that can be collected include:
* Project configuration information
* Project ownership information
* Code access control and branch protection configuration
* Detailed build and test status, including coverage reports
* Security scan results
* Software bill of materials (SBOM)
* Software composition analysis (SCA) results
* Infrastructure information
* Production deliverables and their metadata
For more information about the component JSON, see the [Component JSON](/docs/component-json) page.
## Collectors
Collectors are SDLC (software development lifecycle) instrumentation configurations. They are used to collect live information from the SDLC to associate with individual components.
Collectors are of different **types** that vary depending on the **hook** used. They can be based on code, cron schedules, or CI/CD hooks.
Once a hook is triggered, the collector **executes its custom logic**, which collects data from the SDLC. The data is later on merged to form the component metadata JSON.
Collectors may execute in different **contexts**, depending on the type - for example, in the context of a CI pipeline, or standalone in an ephemeral runner reacting to code changes. The Lunar CI Agent and the Lunar Runner are some of the pieces of the Lunar framework that facilitate the triggering and executions of collectors in such contexts.
Lunar ships with [50+ pre-built integrations](https://earthly.dev/lunar/integrations/) for tools like GitHub, Kubernetes, Docker, Codecov, Snyk, and more. To read more about how to configure collectors, see the [Collectors](/configuration/lunar-config/collectors) page.
### Earthly Lunar CI Agent
The Earthly Lunar CI Agent allows you to trigger and execute collectors related to CI/CD pipelines running on a CI runner. The agent is installed on the self-hosted runner of the CI (e.g. GitHub Actions, GitLab CI, Jenkins, Buildkite) and is responsible for instrumenting the pipelines executing on that host and running arbitrary logic defined by relevant collectors.
Installation on managed CI runners is also possible, although it requires additional setup in each project via the definition of the CI pipelines (typically the YAML definition). Earthly Lunar comes out of the box with policies to verify that the agent is installed properly in such situations.
The Lunar CI Agent is able to instrument individual processes executing within CI pipelines and is able to surgically inject custom logic safely in a way that does not interfere with the CI pipeline's normal execution. Special hooks are defined to trigger collectors to execute in the context of specific processes, no matter how deep in the process tree hierarchy these appear.
### Earthly Lunar Runner
The Earthly Lunar Runner is a standalone ephemeral runner that can be used to execute code-based or cron-based collectors.
You can think of the Lunar Runner as "global CI" where the logic is defined centrally via the Lunar configuration, and not specified within each project's CI pipeline definition. This allows a central platform team to collect information about the entire organization's codebases, running arbitrary logic, and using arbitrary scanners, tools, and scripts, without needing to modify each project's CI pipeline or needing to request permission from individual app teams.
## Policies
Policies are used to define the rules that Lunar uses to evaluate the health of components. Policies receive the component metadata as input and return checks. The checks can then be reported to a scorecarding system or monitored via the Lunar UI.
Some policies may help provide immediate feedback to developers via the PR status. In such a situation, Lunar typically shows up as a commit status check entry in the PR (similarly to how a CI might report status in a PR), showing the health of the component based on the policies.
Similarly, policies can also be used to block deployments based on the health of the component. This is useful to prevent deploying components that do not meet certain engineering standards of the organization.
Lunar includes [200+ pre-built guardrails](https://earthly.dev/lunar/guardrails/) covering testing, security, compliance, and operational readiness. For more information on how to configure policies, see the [Policies](/configuration/lunar-config/policies) page.
## Checks
Checks are the results of evaluating a policy against a component. You can think of Lunar checks as individual line item policies that appear in the final scorecard of a component.
Checks might have different outcomes, such as:
* `pass` - the policy check passes successfully
* `fail` - the policy check is failing
* `pending` - the data required by the policy check is still pending (e.g. a collector has not finished executing yet)
* `skipped` - the policy check was skipped
## Catalogers
Catalogers are used to synchronize component and/or domain data from external systems, such as other code repositories, databases, REST APIs, or IDPs, such as Backstage. Browse the [available integrations](https://earthly.dev/lunar/integrations/) for pre-built catalogers.
To read more about how to configure catalogers, see the [Catalogers](/configuration/lunar-config/catalogers) page.
## Catalog JSON
The Catalog JSON is an object that contains the component and domain data collected by the catalogers.
To read more about the Catalog JSON, see the [Catalog JSON](/docs/catalog-json) page.
# Component JSON
How the Component JSON aggregates SDLC metadata deltas from collectors into a single object that policies evaluate against.
* Type: `JSON`
The Component JSON is a JSON object that contains SDLC metadata associated with a component. The JSON object is formed by collecting metadata deltas via the different collectors.
The Component JSON is meant to represent the point-in-time state of a component. The JSON object is stored in the database and is used to evaluate the health of the component via policies.
The structure of the component JSON is arbitrary. The JSON object acts as an interface layer between the collectors and the policies. It can have any structure, as needed to convey the information used by the policies, or to track the state of a certain metric or characteristic over time for a given component or set of components.
To view the component JSON for a given component, you can use the `lunar component get-json` command:
```bash
lunar component get-json github.com/my-org/my-repo
```
To read more about how to configure the collectors that contribute deltas to the component JSON, see the [collectors](/configuration/lunar-config/collectors) page.
To read more about how to query the component JSONs via the SQL API see the [components view](/sql-api/views/components) page.
# Catalog JSON
Structure and precedence rules for the Catalog JSON, which merges domains and components from catalogers, lunar.yml, and lunar-config.yml.
* Type: `JSON`
* Form:
```json
{
"domains": {
"": {
"description": "",
"owner": "",
"meta": { // 🚧 Coming Soon
"": "",
...
}
},
...
},
"components": {
"": {
"owner": "",
"domain": "",
"branch": "",
"description": "",
"paths": ["", "", ...],
"tags": ["", "", ...],
"ciPipelines": ["", "", ...],
"meta": { // 🚧 Coming Soon
"": "",
...
}
},
...
}
}
```
The Catalog JSON is a JSON object that contains information about the domains and components.
The Catalog JSON, unlike the Component JSON, has a pre-defined structure. The semantics of the fields are defined in the [domains](/configuration/lunar-config/domains) and [components](/configuration/lunar-config/components) pages. The same fields used to configure domains and components in `lunar-config.yml` are used to define the structure of the Catalog JSON.
The JSON object is formed by collecting information from the catalogers, and then merging that information with any data from `lunar.yml` and `lunar-config.yml`. The precedence in which the information is used is as follows:
1. The information from `lunar-config.yml` in the `domains` and `components` section.
2. The information from `lunar.yml` in each component directory. 🚧 Coming Soon
3. The information from the catalogers, where the **last-defined cataloger takes precedence**.
So, for example, if a cataloger emits a component with the same name as a component defined in `lunar-config.yml`, the fields would be combined, and any fields that exist in both would be overridden by the `lunar-config.yml` values.
If you would like to inspect the Catalog JSON, you can do so by running the following command:
```bash
lunar cataloger get-json
```
If you would like to execute the catalogers in development mode, and see the Catalog JSON that would be generated, you can do so by running the following command (needs to be run in the root of the Lunar configuration repository):
```bash
lunar cataloger dev --output-json
```
# Lunar CLI Reference
Complete reference for every Lunar CLI command, subcommand, flag, and environment variable across collectors, catalogers, policies, and Hub operations.
This document provides a comprehensive reference for all available options and commands in the Lunar CLI.
## Global options
### `--config-dir `, `LUNAR_CONFIG_DIR=`
* Type: `string`
* Optional
* Default: `.`
The path to the directory containing `lunar-config.yml`. This path is relative to the current working directory.
### `--hub-host `, `LUNAR_HUB_HOST=`
* Type: `string`
* Optional
Override the URL of the Lunar Hub host name. This setting is inferred from the Lunar config if not specified.
### `--hub-grpc-port `, `LUNAR_HUB_GRPC_PORT=`
* Type: `integer`
* Optional
Override the GRPC port of the Lunar Hub. This setting is inferred from the Lunar config if not specified.
### `--hub-http-port `, `LUNAR_HUB_HTTP_PORT=`
* Type: `integer`
* Optional
Override the HTTP port of the Lunar Hub. This setting is inferred from the Lunar config if not specified.
### `--hub-insecure`, `LUNAR_HUB_INSECURE=true`
* Type: `boolean`
* Optional
If true, use insecure HTTP connections to the Hub server.
### `--no-hub`, `LUNAR_NO_HUB=true`
* Type: `boolean`
* Optional
Skip Hub interactions for dev commands (`lunar collector dev` and `lunar policy dev`). When enabled, the commands will run without connecting to Lunar Hub. Note that `--component-json` is required for `lunar policy dev` when this option is enabled, and `LUNAR_GITHUB_TOKEN` must be set if GitHub access is needed.
### `LUNAR_HUB_TOKEN`
* Type: `string`
* Required for commands that interact with the Hub server
The Lunar Hub token to use for authentication.
## Licence Commands
Inspect a Lunar licence JWT and extract artefacts for cluster bootstrap. These commands run **locally** — they verify the licence against a trust list embedded in the `lunar` binary, so they work before a Hub exists (the canonical bootstrap case).
### Shared options
#### `--licence-file `, `LUNAR_LICENCE_FILE=`
* Type: `string`
* Required (or set the env var)
Path to the licence JWT on disk. All `lunar licence` subcommands accept this flag, or read `LUNAR_LICENCE_FILE` if it's unset.
### `lunar licence verify`
* Form:
```bash
lunar licence verify --licence-file
```
Verify the licence signature against the trust list embedded in this binary and print a customer-facing summary: tenant, expiry, and whether the licence carries a GHCR image-pull credential. Credentials are never printed — use `lunar licence registry-token` if you need the credential itself for manual `docker login`.
Example output:
```
Licence valid for tenant: acme-corp
Expires: 2027-12-31 (in 587 days)
GHCR pull credential: configured — run `lunar licence pull-secret` to provision
```
### `lunar licence pull-secret`
* Form:
```bash
lunar licence pull-secret --licence-file --namespace [--name ] [--out ]
```
Emit a Kubernetes `imagePullSecret` (type `kubernetes.io/dockerconfigjson`) that authenticates the cluster against `ghcr.io` using the credential carried in the licence. Pipe to `kubectl apply -f -`, commit to GitOps, whatever fits.
Errors if the licence does not carry a GHCR pull credential.
#### `--namespace ` | `-n`
* Type: `string`
* Required
Kubernetes namespace for the Secret.
#### `--name `
* Type: `string`
* Optional
* Default: `regcred`
Kubernetes Secret name. The Hub chart's `imagePullSecrets` reference defaults to `regcred`.
#### `--out ` | `-o`
* Type: `string`
* Optional
Write the manifest to a file instead of stdout. The file is created with mode `0600` because it contains a sensitive credential.
#### Examples
```bash
# Provision the pull secret in the lunar namespace, applied to the cluster directly.
lunar licence pull-secret \
--licence-file=path/to/hub-licence.jwt \
--namespace=lunar | kubectl apply -f -
# Same, but for the snippet pods namespace.
lunar licence pull-secret \
--licence-file=path/to/hub-licence.jwt \
--namespace=lunar-scripts | kubectl apply -f -
# Write the manifest to disk for GitOps.
lunar licence pull-secret \
--licence-file=path/to/hub-licence.jwt \
--namespace=lunar \
--out=regcred.yaml
```
### `lunar licence registry-token`
* Form:
```bash
lunar licence registry-token --licence-file
```
Print the raw GHCR pull credential from the licence to stdout, suitable for piping into `docker login --password-stdin`. Errors if the licence does not carry one.
Example:
```bash
lunar licence registry-token --licence-file=path/to/hub-licence.jwt | \
docker login ghcr.io -u earthly-bot --password-stdin
```
## Config Commands
### `lunar config schema`
* Form:
```bash
lunar config schema
```
Print the JSON Schema (draft-07 format) for `lunar-config.yml` to stdout, generated from the same manifest definition the Hub uses. Redirect it into your config repo for editor autocomplete and inline structural feedback:
```bash
lunar config schema > lunar-config.schema.json
```
The schema is a structural aid only (it can't resolve `uses:` plugins). For authoritative pre-merge validation, use [`lunar hub pull --dry-run`](#lunar-hub-pull). See [Validating your config](/configuration/lunar-config/validation).
### `lunar hub pull`
* Form:
```bash
lunar hub pull [--dry-run] [--rerun-code-collectors|-l] [--include-pr-commits] [--pr-max-age-days ] [--rerun-catalogers|-t]
```
The `lunar hub pull` command is used to instruct Lunar Hub to pull the latest configuration from a given repository.
For GitHub Actions workflows, the [`sync-config` action](/install/github-actions) is a thin wrapper around this command and exposes the same flags as inputs.
{% hint style="warning" %}
Using `--rerun-code-collectors` or `--rerun-catalogers` can trigger a large amount of work in Lunar Hub, especially across many components or PRs. Expect a backlog and elevated load while the reruns process.
{% endhint %}
#### ``
* Type: `string`
* Form: `github:///@`
* Required
The repository to pull configuration from. This should be the main repository containing your lunar configuration files.
**Examples:**
* `github://acme-corp/lunar@main`
* `github://acme-corp/lunar@de4adbeef`
#### `--dry-run`
* Type: `boolean`
* Optional
Validate the configuration and exit **without** applying it. The dry run performs the Hub's own load-and-validate steps against the same code — clone the config, load `lunar-config.yml` + `lunar-config.d/` fragments, resolve every `uses:` plugin, validate the whole manifest, and resolve each unpinned component's default branch — then stops before persisting. It does not install per-snippet dependencies, so that one step could still fail on a real pull; see [Validating your config](/configuration/lunar-config/validation) for the details.
It needs **no Hub connection**, which makes it suitable as a pre-merge CI check. It does need GitHub access to resolve `uses:` plugins (set `LUNAR_GITHUB_TOKEN`, or configure the Hub as an auth source). Exits non-zero on any validation error. See [Validating your config](/configuration/lunar-config/validation) for a CI example.
#### `--rerun-code-collectors` | `-l`
* Type: `boolean`
* Optional
Rerun affected code collectors after applying the configuration.
#### `--include-pr-commits`
* Type: `boolean`
* Optional
Include PR commits when rerunning code collectors.
#### `--pr-max-age-days `
* Type: `integer`
* Optional
* Default: `5`
Ignore PR commits older than this maximum number of days.
#### `--rerun-catalogers` | `-t`
* Type: `boolean`
* Optional
* Default: `false`
Rerun global catalogers after pulling the manifest. Catalogers are skipped by default — pulling a manifest no longer triggers them automatically. Per-component catalogers (`component-repo`, `component-cron`) are unaffected and continue to run on their own hooks.
### `lunar hub run-code-collectors`
* Form:
```bash
lunar hub run-code-collectors [--pr-max-age-days ] [--include-pr-commits]
```
The `lunar hub run-code-collectors` command instructs Lunar Hub to rerun code collectors.
{% hint style="warning" %}
This command can trigger a large amount of work in Lunar Hub. It reruns code collectors across all components — and across recent PR commits when `--include-pr-commits` is set — which can produce a significant backlog and elevated load.
{% endhint %}
#### `--pr-max-age-days `
* Type: `integer`
* Optional
* Default: `5`
Ignore PR commits older than this maximum number of days.
#### `--include-pr-commits`
* Type: `boolean`
* Optional
Include PR commits when running code collectors.
### `lunar hub get-logs`
* Form:
```bash
lunar hub get-logs [--namespace ] [--output ] [--tail ]
```
The `lunar hub get-logs` command retrieves logs from Lunar Hub.
#### `--namespace ` | `-n`
* Type: `string`
* Optional
The Kubernetes namespace to retrieve logs from.
#### `--output ` | `-o`
* Type: `string`
* Optional
Output format for the logs.
#### `--tail `
* Type: `integer`
* Optional
Number of lines to show from the end of the logs.
## Domain Commands
### `lunar domain ls`
{% hint style="info" %}
**Coming Soon** — This feature is not yet available.
{% endhint %}
* Form:
```bash
lunar domain ls
```
The `lunar domain ls` command is used to list all domains.
## Component Commands
### `lunar component ls`
{% hint style="info" %}
**Coming Soon** — This feature is not yet available.
{% endhint %}
* Form:
```bash
lunar component ls
```
The `lunar component ls` command is used to list all components.
### `lunar component get-json`
* Form:
```bash
lunar component get-json [--git-sha ] [--pr ] [component-name]
```
The `lunar component get-json` command is used to retrieve the component JSON for a specified component.
#### `[component-name]`
* Type: `string`
The name of the component to retrieve the JSON for. If not provided, falls back to the `LUNAR_COMPONENT_ID` environment variable.
#### `--git-sha `
* Type: `string`
* Optional
The specific git SHA to retrieve the component JSON for. If not specified, the latest component JSON will be retrieved.
#### `--pr `
* Type: `integer`
* Optional
The PR number to retrieve the component JSON for. If not specified, and no git SHA is provided, the component JSON for the primary branch will be retrieved. This is ignored if `--git-sha` is specified.
#### `--pretty` | `-p`
* Type: `boolean`
* Optional
Pretty-print the JSON output.
Example:
```bash
lunar component get-json github.com/my-org/my-repo
```
## Cataloger Commands
`lunar cataloger` manages catalogers from outside. This is distinct from `lunar catalog`, which is the SDK command catalogers use *inside* their own scripts to emit catalog entries.
### `lunar cataloger get-json`
* Form:
```bash
lunar cataloger get-json [--cataloger ] [--component ] [--ts ] [--pretty]
```
The `lunar cataloger get-json` command retrieves the catalog JSON from Lunar Hub. By default it returns the latest merged catalog snapshot (the same JSON that all catalogers contribute to). Use `--cataloger` to fetch a single cataloger's most recent contribution (its delta), `--component` to scope a per-component cataloger to one component, and `--ts` to fetch a historical snapshot.
#### `--cataloger `
* Type: `string`
* Optional
Name of the cataloger whose delta should be returned. If omitted, the merged catalog snapshot is returned. The cataloger is resolved by exact name in the current manifest; an unknown name returns an error.
Whether `--component` is allowed depends on the cataloger's hooks:
* A **global** cataloger (only `cron` / `repo` hooks) returns a single delta. Passing `--component` is rejected.
* A **per-component** cataloger (any `component-cron` / `component-repo` hook) stores one delta per component. `--component` is required; omitting it is rejected with a "per-component scoped" error.
#### `--component `
* Type: `string`
* Optional
Component to scope the lookup to (e.g. `github.com/my-org/my-repo`). Only valid together with `--cataloger`, and only for per-component catalogers — required for those, rejected for purely global ones. Returns the delta that cataloger emitted for the named component.
#### `--ts `
* Type: `string`
* Optional
Return the row whose `created_at` is at or immediately before this timestamp. If omitted, the latest row is returned. The command exits with an error if no row exists at or before the timestamp.
Accepted formats (parsed in this order):
* Date only: `2026-05-01` (interpreted as `2026-05-01T00:00:00Z`)
* Date + time without timezone: `2026-05-01T12:34:56` (interpreted as UTC)
* Full RFC3339: `2026-05-01T12:34:56Z` or `2026-05-01T12:34:56-07:00`
#### `--pretty` | `-p`
* Type: `boolean`
* Optional
Pretty-print the JSON output.
Examples:
```bash
# Latest merged catalog snapshot
lunar cataloger get-json --pretty
# A global cataloger's most recent delta
lunar cataloger get-json --cataloger sbom --pretty
# A per-component cataloger's delta for one component, as of a date
lunar cataloger get-json --cataloger sbom --component github.com/my-org/my-repo --ts 2026-05-01 --pretty
```
### `lunar cataloger run`
* Form:
```bash
lunar cataloger run [--cataloger ] [--component ] [--output-json]
```
The `lunar cataloger run` command triggers cataloger execution in Lunar Hub. The CLI enqueues the matching catalogers, then polls every 10 seconds and prints `queued / success / error` counters until every job is in a terminal state. With no flags, it runs every cataloger in the current manifest. Use `--cataloger` and/or `--component` to narrow the scope.
#### `--cataloger `
* Type: `string`
* Optional
Run only the named cataloger (exact match or dotted-plugin prefix like `myplugin`). If omitted, every cataloger in the manifest participates. When the named cataloger has only global hooks, combining it with `--component` is rejected. When the named cataloger has per-component hooks and `--component` is omitted, it fans out to every component in the manifest.
#### `--component `
* Type: `string`
* Optional
Scope per-component hooks (`component-repo` / `component-cron`) to this single component. When omitted, those hooks fan out across every component in the manifest. Global hooks (`cron` / `repo`) are unaffected.
#### `--output-json`
* Type: `boolean`
* Optional
After the polling loop completes, fetch and print the merged catalog JSON. If no catalog row exists yet (fresh manifest with no completed catalogers), prints `(no catalog yet)` to stderr and exits with the same code as if `--output-json` were not set.
Failures: for any job that ends in the `error` bucket, the CLI prints a one-line summary including a deep link to the Grafana run-details dashboard (if Hub is configured with `HUB_GRAFANA_URL_BASE`). When no snippet\_run is found for a job (rare — worker crashed before recording the run), the link is replaced with `(no run record; check hub logs)`.
Example:
```bash
lunar cataloger run --cataloger sbom --component github.com/my-org/my-repo --output-json
```
### `lunar cataloger dev`
* Form:
```bash
lunar cataloger dev [cataloger-name] \
[--component | --component-dir ] \
[--config ] \
[--git-sha ] \
[--script ] [--script-lang ] \
[--use-system-runtime] [--no-cache] [--verbose] \
[--secrets ] \
[--output-json]
```
{% hint style="warning" %}
Catalogers can be highly environment-dependent. Be mindful of "works on my machine" types of issues.
{% endhint %}
The `lunar cataloger dev` command runs catalogers locally on the user's machine without applying changes to the catalog. It mirrors `lunar collector dev` for catalogers: the cataloger snippet is fetched from the configured manifest, executed under the configured runtime (Python / Node / Bash, or Docker when the snippet has an image), and its output is printed. No data is written to Lunar Hub.
#### `[cataloger-name]`
* Type: `string`
* Optional
Cataloger name (or dotted plugin name like `myplugin.sync`) to execute. If omitted, every cataloger applicable to the resolved scope is run.
#### `--component `
* Type: `string`
* Optional
Look the component up in the resolved manifest. Required when running a per-component cataloger. Mutually exclusive with `--component-dir`.
#### `--component-dir `
* Type: `string`
* Optional
Treat the given local directory as the component checkout (no clone). Mutually exclusive with `--component` and `--config`.
#### `--config `
* Type: `string`
* Optional
Remote configuration repository to load the manifest from (e.g. `github.com/org/repo` or `github://org/repo@branch`). Mutually exclusive with `--component-dir`.
#### `--git-sha `
* Type: `string`
* Optional
Pin the component checkout to this SHA on the component's primary branch. Only meaningful for per-component catalogers. Defaults to the tip of the primary branch.
{% hint style="info" %}
Unlike `lunar collector dev`, there is no `--pr` flag — catalogers run on pushes to main, not on PR commits.
{% endhint %}
#### `--script `
* Type: `string`
* Optional
Override the cataloger's `main` script with a local file path. Combine with `--script-lang` to control the runtime used.
#### `--script-lang `
* Type: `string`
* Optional
* Default: `bash`
Language for `--script` (`bash` / `python` / `node`).
#### `--use-system-runtime`
* Type: `boolean`
* Optional
Use the host's system Python / Node / Bash instead of the bundled Lunar runtimes. Defaults to `true` on non-Linux-amd64 hosts.
#### `--no-cache`
* Type: `boolean`
* Optional
Delete cacheable temporary files before running. Use this to force a clean run when troubleshooting.
#### `--verbose`
* Type: `boolean`
* Optional
Stream the cataloger's engine stdout / stderr to the terminal as it runs.
#### `--secrets `
* Type: `string`
* Optional
Supplemental secrets injected into the cataloger's environment, parsed as comma-separated `key=value` pairs.
#### `--output-json`
* Type: `boolean`
* Optional
Print the merged Catalog JSON the user would see if these catalogers ran in Hub (manifest base + cataloger deltas + manifest overrides), in the same shape as [Catalog JSON](/docs/catalog-json). Without this flag, each cataloger's raw emitted JSON is printed under a per-cataloger header.
Example:
```bash
lunar cataloger dev sbom --component github.com/my-org/my-repo --verbose
```
## Collector Commands
### `lunar collector run`
{% hint style="info" %}
**Coming Soon** — This feature is not yet available.
{% endhint %}
* Form:
```bash
lunar collector run [--output-json] [--pr ] \
[--git-sha ] [--only-code] [--only-cron] \
[--collector ] [--pr-max-age-days ]
```
The `lunar collector run` command is used to rerun code and cron collectors for a given component. This command triggers execution in the cloud via Lunar Hub.
#### ``
* Type: `string`
The name of the component to rerun collectors for.
#### `--pr `
* Type: `integer`
* Optional
The PR number to rerun collectors for. If not specified, collectors will be run for the component's primary branch.
#### `--git-sha `
* Type: `string`
* Optional
The specific git SHA to rerun collectors for. If specified, this takes precedence over `--pr`.
#### `--only-code`
Run only code collectors.
#### `--only-cron`
Run only cron collectors.
#### `--collector `
* Type: `string`
* Optional
* Repeatable
Run only the specified collector. This flag can be repeated to run multiple specific collectors.
#### `--pr-max-age-days `
* Type: `integer`
* Optional
* Default: `5`
Ignore PR commits older than this maximum number of days.
#### `--output-json`
Output the results in JSON format.
Example:
```bash
# Rerun all collectors for all components for all PRs, limitting to 1 day old PRs
lunar collector run --pr-max-age-days 1
# Rerun collectors for a component (primary branch)
lunar collector run github.com/my-org/my-repo
# Rerun collectors for a specific PR
lunar collector run --pr 123 github.com/my-org/my-repo
# Rerun collectors for a specific git SHA
lunar collector run --git-sha abc123 github.com/my-org/my-repo
# Run only code collectors
lunar collector run --only-code github.com/my-org/my-repo
# Run only a specific collector
lunar collector run --collector collector-name github.com/my-org/my-repo
```
### `lunar collector dev`
* Name Form:
```bash
lunar collector dev [--pr ] [--git-sha ] \
[--component | --component-dir ] \
[--fake-ci-cmd ] \
```
* Script Form:
```bash
lunar collector dev \
[--pr ] [--git-sha ] \
[--component | --component-dir ] \
[--fake-ci-cmd ] \
--script
```
{% hint style="warning" %}
Collectors can be highly environment-dependent. Be mindful of "works on my machine" types of issues.
{% endhint %}
The `lunar collector dev` command is used to run a collector for a given component in development mode without applying changes. This command executes locally on the user's machine and outputs the resulting component JSON.
#### ``
* Type: `string`
* Required in Name Form
#### `--script `
* Type: `string`
* Required in Script Form
#### `--component `
* Type: `string`
The name of the component to run collectors for. If not provided, falls back to the `LUNAR_COMPONENT_ID` environment variable. Mutually exclusive with `--component-dir`.
#### `--component-dir `
* Type: `string`
Local directory containing the component to run collectors for. The directory must be a git repository. The component name is derived from the git remote URL. Mutually exclusive with `--component`.
#### `--pr `
* Type: `integer`
* Optional
The PR number to run collectors for. If not specified, collectors will be run for the component's primary branch.
#### `--git-sha `
* Type: `string`
* Optional
The specific git SHA to run collectors for. If specified, this takes precedence over `--pr`.
#### ``
* Type: `string`
* Optional
The name of the collector to run. If not specified, all collectors will be run.
The path to a bash collector script file to run in development mode.
#### `--fake-ci-cmd `
* Type: `string`
* Optional
A command that the CI would have executed, that would cause lunar instrumentation to trigger an event for. This command is not actually executed, it is merely used to test collector triggering logic (e.g. would the collector trigger regex match the command line). This option is used for testing CI collectors locally without requiring an actual CI pipeline execution.
#### `--config `
* Type: `string`
* Optional
Remote config repository to use.
#### `--use-system-runtime`
* Type: `boolean`
* Optional
Use the system runtime instead of a containerized environment.
#### `--no-cache`
* Type: `boolean`
* Optional
Disable caching.
#### `--verbose`
* Type: `boolean`
* Optional
Enable verbose output.
#### `--merge`
* Type: `boolean`
* Optional
Merge the collected data into the existing component JSON.
#### `--secrets`
* Type: `boolean`
* Optional
Fetch and inject secrets into the collector execution environment.
#### Examples
```bash
# Run collectors in development mode for a component (primary branch)
lunar collector dev --component github.com/my-org/my-repo
# Run collectors in development mode for a specific PR
lunar collector dev --component github.com/my-org/my-repo --pr 123
# Run a specific collector
lunar collector dev --component github.com/my-org/my-repo collector-name
# Run a specific collector script file
lunar collector dev --component github.com/my-org/my-repo --script ./path/to/collector.sh
# Test a CI collector with a fake CI command
lunar collector dev --component github.com/my-org/my-repo --fake-ci-cmd "npm test" ci-collector-name
# Run collectors against a local directory
lunar collector dev --component-dir ./my-local-repo collector-name
# Run collectors against a local directory with a specific git SHA
lunar collector dev --component-dir ./my-local-repo --git-sha abc123 collector-name
```
#### Credentials
What credentials `lunar collector dev` needs depends on how you name the component:
* **`--component-dir `** runs against a checkout you already have. It performs only local git operations (no clone), so it needs **no Hub and no GitHub token**. This is the way to smoke-test a collector against a local component with no credentials — pair it with `--no-hub` to skip Hub entirely, and `--script` to run a single script without resolving the manifest.
* **`--component `** must resolve the component's default branch and clone it, so it needs **either a configured Hub or `LUNAR_GITHUB_TOKEN`**. Without one, the command errors and points you at `--component-dir`.
## Policy Commands
### `lunar policy ls`
{% hint style="info" %}
**Coming Soon** — This feature is not yet available.
{% endhint %}
* Form:
```bash
lunar policy ls
```
The `lunar policy ls` command is used to list all policies.
### `lunar policy check ls`
{% hint style="info" %}
**Coming Soon** — This feature is not yet available.
{% endhint %}
* Form:
```bash
lunar policy check ls
```
The `lunar policy check ls` command is used to list all checks.
### `lunar policy run`
{% hint style="info" %}
**Coming Soon** — This feature is not yet available.
{% endhint %}
* Form:
```bash
lunar policy run [--output-json] [--pr ] \
[--git-sha ] [--policy ] \
[--initiative ]
```
The `lunar policy run` command is used to rerun all policies for a given component. This command triggers execution in the cloud via Lunar Hub.
#### ``
* Type: `string`
The name of the component to rerun policies for.
#### `--pr `
* Type: `integer`
* Optional
The PR number to rerun policies for. If not specified, policies will be run for the component's primary branch.
#### `--git-sha `
* Type: `string`
* Optional
The specific git SHA to rerun policies for. If specified, this takes precedence over `--pr`.
#### `--policy `
* Type: `string`
* Optional
* Repeatable
Run only the specified policy. This flag can be repeated to run multiple specific policies.
#### `--initiative `
* Type: `string`
* Optional
* Repeatable
Run only policies under the specified initiative. This flag can be repeated to run policies under multiple initiatives.
#### `--output-json`
Output the results in JSON format.
Example:
```bash
# Rerun policies for a component (primary branch)
lunar policy run github.com/my-org/my-repo
# Rerun policies for a specific PR
lunar policy run --pr 123 github.com/my-org/my-repo
# Rerun policies for a specific git SHA
lunar policy run --git-sha abc123 github.com/my-org/my-repo
# Run only a specific policy
lunar policy run --policy policy-name github.com/my-org/my-repo
# Run policies under a specific initiative
lunar policy run --initiative initiative-name github.com/my-org/my-repo
```
### `lunar policy dev`
* Name Form:
```bash
lunar policy dev [--component ] [--component-json ] \
[--pr ] [--git-sha ] \
```
* Script Form:
```bash
lunar policy dev [--component ] [--component-json ] \
[--pr ] [--git-sha ] \
--script
```
{% hint style="warning" %}
Policies can be highly environment-dependent. Be mindful of "works on my machine" types of issues.
{% endhint %}
The `lunar policy dev` command is used to run a policy against a component for local testing purposes. This command executes locally on the user's machine and outputs the check results in JSON format.
#### ``
* Type: `string`
* Required in Name Form
#### `--script `
* Type: `string`
* Required in Script Form
#### `--component `
* Type: `string`
The name of the component to run the policy against. If not provided, falls back to the `LUNAR_COMPONENT_ID` environment variable.
#### `--component-json `
* Type: `string`
The path to the component JSON file or `-` to read from stdin.
#### `--pr `
* Type: `integer`
* Optional
The PR number to run the policy against. If not specified, the policy will be run against the component's primary branch.
#### `--git-sha `
* Type: `string`
* Optional
The specific git SHA to run the policy against. If specified, this takes precedence over `--pr`.
#### `--with `
* Type: `string`
* Optional
Arguments passed to the policy script.
#### `--script-lang `
* Type: `string`
* Optional
* Default: `python`
The script programming language.
#### `--output `
* Type: `string`
* Optional
* Values: `json`, `list`
Output format for the policy results.
#### `--config `
* Type: `string`
* Optional
Remote config repository to use.
#### `--use-system-runtime`
* Type: `boolean`
* Optional
Use the system runtime instead of a containerized environment.
#### `--no-cache`
* Type: `boolean`
* Optional
Disable caching.
#### `--verbose`
* Type: `boolean`
* Optional
Enable verbose output.
#### `--secrets`
* Type: `boolean`
* Optional
Fetch and inject secrets into the policy execution environment.
#### Example
```bash
# Run policy with component JSON from file
lunar policy dev --component-json path/to/component.json --script ./path/to/policy.py
# Run policy by specifying component directly
lunar policy dev --component github.com/my-org/my-repo --script ./path/to/policy.py
# Run policy with component JSON from stdin
lunar component get-json --git-sha ... github.com/my-org/my-repo | \
lunar policy dev --component-json - --script ./path/to/policy.py
# Run specific policy from config
lunar policy dev --component github.com/my-org/my-repo my-policy
# Run policy for a specific PR
lunar policy dev --component github.com/my-org/my-repo --pr 123 --script ./path/to/policy.py
```
### `lunar policy ok-release`
* Form:
```bash
lunar policy ok-release
lunar policy ok-release # uses LUNAR_COMPONENT_ID and GITHUB_SHA
```
The `lunar policy ok-release` command is used to check if a component at a specific git SHA passes its release policies.
Either both positional arguments must be provided, or neither. When no arguments are given, both `LUNAR_COMPONENT_ID` and `GITHUB_SHA` environment variables must be set.
#### ``
* Type: `string`
The name of the component to check. Falls back to the `LUNAR_COMPONENT_ID` environment variable when no arguments are given.
#### ``
* Type: `string`
The git SHA to check. Falls back to the `GITHUB_SHA` environment variable when no arguments are given.
#### `--poll-interval `
* Type: `duration`
* Optional
* Default: `10s`
How often to poll for results.
#### `--timeout `
* Type: `duration`
* Optional
* Default: `10m`
Maximum time to wait for results before timing out.
#### `--workflow-id `
* Type: `string`
* Optional
The CI workflow ID to associate with the check.
#### `--pr `
* Type: `integer`
* Optional
The PR number to check policies for.
### `lunar policy ok-pr`
* Form:
```bash
lunar policy ok-pr
lunar policy ok-pr # uses LUNAR_COMPONENT_ID and GITHUB_SHA
```
The `lunar policy ok-pr` command is used to check if a component at a specific git SHA passes its PR policies.
Either both positional arguments must be provided, or neither. When no arguments are given, both `LUNAR_COMPONENT_ID` and `GITHUB_SHA` environment variables must be set.
#### ``
* Type: `string`
The name of the component to check. Falls back to the `LUNAR_COMPONENT_ID` environment variable when no arguments are given.
#### ``
* Type: `string`
The git SHA to check. Falls back to the `GITHUB_SHA` environment variable when no arguments are given.
#### `--poll-interval `
* Type: `duration`
* Optional
* Default: `10s`
How often to poll for results.
#### `--timeout `
* Type: `duration`
* Optional
* Default: `10m`
Maximum time to wait for results before timing out.
#### `--workflow-id `
* Type: `string`
* Optional
The CI workflow ID to associate with the check.
#### `--pr `
* Type: `integer`
* Optional
The PR number to check policies for.
## SDK Commands
### `lunar catalog`
Saves catalog-related information from within a cataloger.
For detailed documentation on the `lunar catalog` command and all its options, see the [Cataloger Bash SDK](/plugin-sdks/bash-sdk/cataloger) page.
### `lunar collect`
Collects SDLC metadata into a component's JSON. Pass `--component` and `--sha` to collect against a specific component and commit from anywhere.
For detailed documentation on the `lunar collect` command and all its options, see the [Collector Bash SDK](/plugin-sdks/bash-sdk/collector) page.
## SQL Commands
### `lunar sql connection-string`
* Form:
```bash
lunar sql connection-string
```
The `lunar sql connection-string` command returns the PostgreSQL connection string that can be used with any PostgreSQL client. The access is **read-only** and restricted to only the views described in the [SQL API](/sql-api/sql-api) documentation.
Example:
```bash
# Get the connection string
lunar sql connection-string
# Connect using psql (interactive)
psql $(lunar sql connection-string)
# Export checks data as CSV
psql $(lunar sql connection-string) -c "COPY (
SELECT *
FROM checks
WHERE component_id = 'github.com/my-org/my-repo'
AND status = 'fail'
) TO STDOUT WITH CSV HEADER" > failed_checks.csv
# Export component data as JSON
psql $(lunar sql connection-string) -c "
SELECT json_agg(row_to_json(c))
FROM (
SELECT *
FROM components
WHERE tags @> '{\"team\":\"ui\"}'
) c" > platform_components.json
# Make decisions based on check results
psql $(lunar sql connection-string) -t -c "
SELECT COUNT(*)
FROM checks c
JOIN components comp ON c.component_id = comp.component_id
WHERE comp.domain = 'payments'
AND c.status = 'fail'
AND c.enforcement IN ('block-pr-and-release', 'block-release')" | \
grep -q "^0$" || \
(echo "Release blocking checks are failing in payments domain!" && exit 1)
```
For more examples of the SQL API in action, see the [SQL API](/sql-api/sql-api) documentation.
### `lunar secret set`
```bash
lunar secret set [value]
```
Set a secret that will be available to collectors, policies, or catalogers as `LUNAR_SECRET_`.
If `value` is omitted, it is read from stdin (recommended for sensitive values to avoid shell history exposure).
Secrets are encrypted at rest using AES-256-GCM. The Hub must have `HUB_SECRETS_ENCRYPTION_KEY` configured.
#### Options
* `--scope ` — Secret scope: `collector` (default), `policy`, or `cataloger`.
#### Examples
```bash
# Set a collector secret (value as argument)
lunar secret set GH_TOKEN ghp_abc123
# Set a secret from stdin (recommended)
echo "ghp_abc123" | lunar secret set GH_TOKEN
# Set a policy secret
lunar secret set --scope policy JIRA_API_KEY my-api-key
```
### `lunar secret delete`
```bash
lunar secret delete
```
Delete a previously configured secret.
#### Options
* `--scope ` — Secret scope: `collector` (default), `policy`, or `cataloger`.
#### Examples
```bash
lunar secret delete GH_TOKEN
lunar secret delete --scope policy JIRA_API_KEY
```
### `lunar secret list`
```bash
lunar secret list
```
List the names of configured secrets for a given scope. Values are never displayed.
#### Options
* `--scope ` — Secret scope: `collector` (default), `policy`, or `cataloger`.
#### Examples
```bash
# List collector secrets
lunar secret list
# List policy secrets
lunar secret list --scope policy
```
## Utility Commands
### `lunar clear-cache`
* Form:
```bash
lunar clear-cache
```
The `lunar clear-cache` command deletes Git and installation file caches used by Lunar. This can be useful to resolve issues caused by stale cached data.
### `lunar version`
* Form:
```bash
lunar version
```
The `lunar version` command prints the Lunar CLI version and commit SHA.
# lunar-config.yml
Reference for lunar-config.yml — the central configuration file defining hub connection, catalogers, domains, components, collectors, initiatives, and policies.
* `lunar-config.yml`
* Type: YAML file
* Form:
```yaml
version: 0
default_image:
default_image_ci_collectors:
default_image_non_ci_collectors:
default_image_policies:
default_image_catalogers:
hub:
host:
grpcPort:
httpPort:
insecure:
catalogers:
-
-
- ...
domains:
:
:
...
components:
:
:
...
collectors:
-
-
- ...
initiatives:
-
-
- ...
policies:
-
-
- ...
```
The file `lunar-config.yml` is used to configure the behavior of Lunar.
{% hint style="info" %}
It is recommended that you create a new code repository for all Lunar configuration and place this file in the root of it.
{% endhint %}
At a high-level, the file contains information about how the Lunar primitives are configured, ranging from how information is collected from the SDLC via collectors, to how components are organized into domains, and how the health of components is evaluated via policies.
## Splitting the configuration
A single `lunar-config.yml` works well and is the typical setup. If you'd prefer to spread a larger configuration across several files — for example, one per team — you can: any `*.yml` / `*.yaml` files placed in a `lunar-config.d/` directory next to `lunar-config.yml` are merged into it, in lexical filename order.
```
lunar-config.yml # version, hub, default images
lunar-config.d/
collectors.yml
team-frontend.yml
team-backend.yml
```
`lunar-config.yml` stays the entry point and holds the singleton fields (`version`, `hub`, `default_image*`); each fragment contributes additional sections. List sections (`collectors`, `policies`, …) are concatenated; map sections (`domains`, `components`) are unioned by key, and a key defined in more than one place is an error rather than a silent override.
## `version`
* `lunar-config.yml -> version`
* Type: `string`
* Required
The version field is used to specify the version of the configuration file. The current version is `0`.
## Default Images
* `lunar-config.yml -> default_image*`
* Optional
These fields configure the default Docker images used to run collectors, policies, and catalogers. When set, scripts will run inside containers instead of natively on the host.
A common configuration is:
{% code title="lunar-config.yml" %}
```yaml
default_image: earthly/lunar-scripts:1.0.0
default_image_ci_collectors: native
```
{% endcode %}
This runs most scripts in containers while keeping CI collectors native for direct access to CI environments.
For detailed documentation on default images, image resolution order, and the official `earthly/lunar-scripts` image, see [Images](/configuration/lunar-config/images).
## `hub`
* `lunar-config.yml -> hub`
* Type: `object`
* Required
The `hub` object contains configuration for the Lunar Hub server.
### `host`
* `lunar-config.yml -> hub.host`
* Type: `string`
* Required
The host field is used to specify the host of the Lunar Hub server.
### `grpcPort`
* `lunar-config.yml -> hub.grpcPort`
* Type: `integer`
* Required
The grpcPort field is used to specify the port of the Lunar Hub server for GRPC connections.
### `httpPort`
* `lunar-config.yml -> hub.httpPort`
* Type: `integer`
* Required
The httpPort field is used to specify the port of the Lunar Hub server for HTTP connections.
### `insecure`
* `lunar-config.yml -> hub.insecure`
* Type: `boolean`
* Optional
* Default: `false`
The insecure field is used to specify whether to use insecure HTTP connections to the Lunar Hub server.
## `catalogers`
* `lunar-config.yml -> catalogers`
* Type: `array`
* Optional
Catalogers are used to synchronize software catalog information (such as domains, and components) with external systems.
For information on how to configure catalogers, see [catalogers](/configuration/lunar-config/catalogers).
## `domains`
* `lunar-config.yml -> domains`
* Type: `object`
* Optional
Domains are used to group related components together. Domains are hierarchical and can contain other domains.
For information on how to configure domains, see [domains](/configuration/lunar-config/domains).
## `components`
* `lunar-config.yml -> components`
* Type: `object`
* Optional
Components are the units of code that Lunar monitors. A component can represent either a code repository, or a subdirectory in the case of a monorepo.
Components are associated with domains and can have tags. Through the tagging system, components are associated with collectors, and policies.
For information on how to configure components, see [components](/configuration/lunar-config/components).
## `collectors`
* `lunar-config.yml -> collectors`
* Type: `array`
* Required
Collectors are used to collect live information from various sources to associate with individual components.
For information on how to configure collectors, see [collectors](/configuration/lunar-config/collectors).
## `initiatives`
* `lunar-config.yml -> initiatives`
* Type: `array`
* Optional
Initiatives are used to group components together. Initiatives are associated with domains and can have tags.
For information on how to configure initiatives, see [initiatives](/configuration/lunar-config/initiatives).
## `policies`
* `lunar-config.yml -> policies`
* Type: `array`
* Required
Policies are used to define the rules that Lunar uses to evaluate the health of components. Policies are associated with domains and can be inherited by child domains.
For information on how to configure policies, see [policies](/configuration/lunar-config/policies).
# About images
Configure default container images for collectors, policies, and catalogers in lunar-config.yml, with override precedence rules.
Lunar supports running collectors, policies, and catalogers inside Docker containers. This provides isolation, reproducibility, and simplifies dependency management. Default images can be configured at multiple levels, with more specific settings overriding more general ones.
## Image Resolution Order
The image used to run a script is determined in the following order (first match wins):
1. **Script-level `image`** - Set directly on the collector, policy, or cataloger
2. **Plugin-level default** - Set in `lunar-collector.yml`, `lunar-policy.yml`, or `lunar-cataloger.yml`
3. **Global default** - Set in `lunar-config.yml`
4. **Implicit default** - `native` (no container)
## Global Default Images
Configure default images in `lunar-config.yml`:
{% code title="lunar-config.yml" %}
```yaml
version: 0
default_image: my-custom-image:alpine-1.2.3
default_image_ci_collectors: native
default_image_non_ci_collectors: my-image:v1.0
default_image_policies: another-image:latest
default_image_catalogers: yet-another-image:v2.0
# ... rest of configuration
```
{% endcode %}
### `default_image`
* `lunar-config.yml -> default_image`
* Type: `string`
* Optional
* Default: `native`
The global default image to use for all collectors, policies, and catalogers. This is overridden by the more specific `default_image_*` settings.
### `default_image_ci_collectors`
* `lunar-config.yml -> default_image_ci_collectors`
* Type: `string`
* Optional
* Default: value of `default_image`
The default image for CI collectors (collectors with hooks of type `ci-before-command`, `ci-after-command`, `ci-before-job`, `ci-after-job`). It is common to set this to `native` since CI collectors often need direct access to the CI environment.
### `default_image_non_ci_collectors`
* `lunar-config.yml -> default_image_non_ci_collectors`
* Type: `string`
* Optional
* Default: value of `default_image`
The default image for non-CI collectors (collectors with hooks of type `code`, `cron`).
### `default_image_policies`
* `lunar-config.yml -> default_image_policies`
* Type: `string`
* Optional
* Default: value of `default_image`
The default image for all policies.
### `default_image_catalogers`
* `lunar-config.yml -> default_image_catalogers`
* Type: `string`
* Optional
* Default: value of `default_image`
The default image for all catalogers.
## Plugin-Level Default Images
Plugins can define their own default images that override the global settings. This is useful when a plugin requires specific dependencies that are pre-installed in a custom image.
In `lunar-collector.yml`, `lunar-policy.yml`, or `lunar-cataloger.yml`:
```yaml
version: 0
name: my-plugin
description: A plugin with custom image defaults
default_image: my-org/my-plugin-image:v1.0
default_image_ci_collectors: native
default_image_non_ci_collectors: my-org/my-plugin-image:v1.0
default_image_policies: my-org/my-plugin-image:v1.0
default_image_catalogers: my-org/my-plugin-image:v1.0
# ... rest of plugin configuration
```
The same settings are available as at the global level. Plugin-level defaults override global defaults but are overridden by script-level `image` settings.
## Script-Level Image
Each individual collector, policy, or cataloger can specify its own `image` to override all defaults:
{% code title="lunar-config.yml" %}
```yaml
collectors:
- runBash: lunar collect .file-count "$(find . | wc -l)"
image: earthly/lunar-scripts:1.0.0
hook:
type: code
on: [my-tag]
```
{% endcode %}
## The `native` Value
The special value `native` explicitly opts out of containerized execution. When `image: native` is set, the script runs directly on the host system using the native runtime (Python, Bash, etc.).
This is useful when:
* A default image has been configured, but a specific script needs to run natively
* CI collectors need direct access to the CI environment
* The script needs access to host-specific resources
## Common Configuration Pattern
A common configuration is to use containers for most scripts but run CI collectors natively:
{% code title="lunar-config.yml" %}
```yaml
default_image: earthly/lunar-scripts:1.0.0
default_image_ci_collectors: native
```
{% endcode %}
This configuration:
* Runs all policies in containers
* Runs all catalogers in containers
* Runs non-CI collectors (code, cron, repo hooks) in containers
* Runs CI collectors natively for direct access to CI environment variables and tools
## Official Image: `earthly/lunar-scripts`
Lunar provides an official Docker image `earthly/lunar-scripts` that includes:
* Alpine Linux (or `-debian` variant for tools requiring glibc)
* Python 3 with venv
* Bash
* The `lunar-policy` Python package
* The `lunar` CLI
* Common tools: `jq`, `yq`, `curl`, `parallel`, `wget`
### Dependency Handling
The official `earthly/lunar-scripts` image automatically executes any `requirements.txt` and/or `install.sh` files it finds in the plugin directory as part of its entrypoint. This is a convenience feature to help you get up and running quickly during development.
**For production use, we recommend baking all dependencies directly into your image.** This approach provides:
* Faster startup times (no runtime installation)
* Reproducible builds
* Better caching and smaller attack surface
* Elimination of network dependencies at runtime
### Recommended Approach: Custom Image Inheriting from Official
The recommended approach is to create a custom Dockerfile that inherits from the official `earthly/lunar-scripts` image and installs your dependencies at build time:
{% code title="Dockerfile" %}
```dockerfile
FROM earthly/lunar-scripts:1.0.0
# Install system dependencies (if needed)
RUN apt-get update && apt-get install -y jq curl && rm -rf /var/lib/apt/lists/*
# Copy and install Python dependencies
COPY requirements.txt /tmp/requirements.txt
RUN pip install --no-cache-dir -r /tmp/requirements.txt && rm /tmp/requirements.txt
# Copy and run install script (if needed)
COPY install.sh /tmp/install.sh
RUN /tmp/install.sh && rm /tmp/install.sh
```
{% endcode %}
This pattern gives you all the benefits of the official image (Python, Bash, `lunar` CLI, `lunar-policy` package) while ensuring your dependencies are baked in for production use.
## Image Entrypoint Contract
Lunar executes snippets by passing two arguments to the image's entrypoint:
```
```
| Argument | Description | Example |
| -------- | ------------------------------------- | ------------------- |
| `$1` | The snippet language | `python`, `bash` |
| `$2` | Absolute path to the main script file | `/app/exec/main.py` |
The entrypoint is responsible for invoking the correct language runtime on the given script. The official `earthly/lunar-scripts` image ships an entrypoint at `/app/entrypoint.sh` that handles this automatically.
### Requirements for Custom Images
If you build a custom image, it must meet these requirements:
1. **Entrypoint at `/app/entrypoint.sh`** that accepts `(language, script_path)` as `$1` and `$2`. The simplest implementation:
```bash
#!/bin/bash
set -e
exec "$1" "$2"
```
2. **Language runtime on `PATH`** — the binary matching the snippet's language must be available:
| Language | Required binary |
| -------- | --------------- |
| Python | `python` |
| Bash | `bash` |
{% hint style="info" %}
Many base images ship `python3` without a `python` symlink. Ensure `python` resolves correctly (e.g., `RUN ln -sf /usr/bin/python3 /usr/bin/python`). The official `earthly/lunar-scripts` image handles this automatically.
{% endhint %}
**The recommended approach is to inherit from the official image**, which satisfies both requirements out of the box:
{% code title="Dockerfile" %}
```dockerfile
FROM earthly/lunar-scripts:1.0.0
# Add your dependencies — the entrypoint and runtimes are already set up.
RUN pip install --no-cache-dir my-package
```
{% endcode %}
### How Execution Works
Both the Docker engine (local development) and the Kubernetes operator use the same entrypoint contract. Lunar passes `[language, script_path]` as arguments to the container, and the image's entrypoint handles dispatching to the correct runtime.
This means a custom image tested locally via the Docker engine will behave identically when deployed to Kubernetes — the entrypoint runs in both environments with the same arguments.
### Mount Points
The following directories are available inside the container in both Docker and Kubernetes execution modes:
| Container Path | Description |
| -------------- | ----------------------------------------------------------------------------- |
| `/app/exec` | Plugin directory — script and plugin files |
| `/app/work` | Working directory — the component's code (for collectors and some catalogers) |
| `/app/lib` | Library directory — bundle data for policies |
The container's working directory is set to `/app/work`, so your scripts can access the component's files using relative paths. The `LUNAR_PLUGIN_ROOT` environment variable is set to `/app/exec`.
## Private Registry Authentication
To pull images from private Docker registries, configure the following environment variables:
* `LUNAR_DOCKER_REGISTRY_USER` - Username for Docker registry authentication
* `LUNAR_DOCKER_REGISTRY_PASS` - Password or token for Docker registry authentication
# catalogers
Define the catalogers section of lunar-config.yml — scripts that synchronize domain and component metadata from external systems.
* `lunar-config.yml -> catalogers`
* Type: `array`
* Form:
```yaml
-
-
- ...
```
Catalogers are used to synchronize software catalog information, such as domains, and components, with external systems.
The catalog information resulting from catalogers is merged in the order in which the catalogers are defined. This means that if two catalogers define the same field (e.g. `owner`) within the same component, the last one will take precedence.
After the cataloger information is merged, the information collected from any [`lunar.yml`](/configuration/lunar-yml) files 🚧 Coming Soon, and any component and domain information from [`lunar-config.yml`](/configuration/lunar-config), is merged to form the final catalog JSON, which is then used by Lunar to form the structure of domains and components internally.
Example catalogers definition:
{% code title="lunar-config.yml" %}
```yaml
catalogers:
- name: GitHub repos
runBash: |-
gh repo list --json | ... | \
lunar catalog --json '.components' -
hook:
type: cron
schedule: "0 2 * * *"
- name: Backstage sync
runBash: |-
curl