# 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 Tracer 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. Decide how you will run it before the next step, because the Git platform setup differs between the two.
* **Self hosted** – you operate the Hub on your own Kubernetes:
* [Overview](/install/lunar-hub/self-hosted/overview) – the lay of the land: services, dependencies, ports.
* [Prerequisites](/install/lunar-hub/self-hosted/prerequisites) – what to have in place before `helm install`.
* [Install walkthrough](/install/lunar-hub/self-hosted/install-walkthrough) – step-by-step from zero to a working Hub.
* [Day-2 operations](/install/lunar-hub/self-hosted/day-2-operations) – upgrades, secret rotation, observability, uninstall.
* [**Lunar Dedicated**](/install/lunar-hub/dedicated) – Earthly provisions, operates, and upgrades a single-tenant install in a dedicated AWS account:
* [Overview](/install/lunar-hub/dedicated/overview) – how it works, how you reach it, and how it handles your data.
* [Setup](/install/lunar-hub/dedicated/setup) – what your side does: the questionnaire, the depositor account, and the secret deposit.
* [PrivateLink to your hub](/install/lunar-hub/dedicated/privatelink-inbound) – the recommended way for your CI and browsers to reach the install, where your CI runs in a network you control.
* [PrivateLink to your systems](/install/lunar-hub/dedicated/privatelink-outbound) – only if Lunar's collectors must reach systems that aren't on the public internet. Longest lead time in onboarding, so start it first.
3. **Git platform** – the credential the Hub reads repositories and posts results with. The Hub will not start without one, so create it before you finish the install above: before `helm install` when self-hosted, or before kickoff on Dedicated.
* [GitHub](/install/git-platforms/github) for a GitHub App on your org, or [GitLab](/install/git-platforms/gitlab) for a group access token per top-level group.
* [Git Platforms](/install/git-platforms) – what differs between the two, if you are choosing or running both.
4. **CI integration** – how Lunar gets build-time data, via the [Lunar CI Tracer](/install/ci-tracer). This step depends on your CI:
* **GitHub Actions** – install the tracer on [self-hosted runners](/install/ci-tracer/github-actions-self-hosted), or use the [action](/install/ci-tracer/github-actions-managed) on GitHub-hosted ones.
* **Buildkite** – an agent hook plus a webhook; see [Buildkite](/install/ci-tracer/buildkite).
* **GitLab CI** – nothing to install; tracing support is [coming soon](/install/ci-tracer/gitlab-ci). Lunar collects from source events instead — see [GitLab](/install/git-platforms/gitlab).
5. **Sync Config** – strongly recommended. Push your config repo to Lunar Hub on every push, via the GitHub Action or a GitLab CI job, so the Hub's copy of your configuration never drifts from what's in git.
* [Set up config sync](/install/lunar-hub/self-hosted/sync-config)
Optional:
* [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 [200+ pre-built guardrails](https://earthly.dev/lunar/guardrails/) and [60+ 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 tracer 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 build for your operating system and CPU from the [releases page](https://github.com/earthly/lunar-dist/releases/latest).
Download the Lunar CLI
{% endstep %}
{% step %}
## Move the binary into place
Create the install directory, make the binary you downloaded executable, and move it there as `lunar`.
{% tabs %}
{% tab title="macOS (Apple Silicon)" %}
```bash
mkdir -p "$HOME/.lunar/bin" && chmod +x lunar-darwin-arm64 && mv ./lunar-darwin-arm64 "$HOME/.lunar/bin/lunar"
```
{% endtab %}
{% tab title="Linux (x86-64)" %}
```bash
mkdir -p "$HOME/.lunar/bin" && chmod +x lunar-linux-amd64 && mv ./lunar-linux-amd64 "$HOME/.lunar/bin/lunar"
```
{% endtab %}
{% tab title="Linux (ARM64)" %}
```bash
mkdir -p "$HOME/.lunar/bin" && chmod +x lunar-linux-arm64 && mv ./lunar-linux-arm64 "$HOME/.lunar/bin/lunar"
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
**On Windows, use WSL2.** Lunar's CLI ships as Linux and macOS builds only, so on Windows you install it inside a WSL2 (Ubuntu) shell and follow the Linux steps above. Docker Desktop already runs on a WSL2 backend, so this is the supported Windows path.
{% endhint %}
If you prefer to install `lunar` to a different directory, set the `LUNAR_BIN_DIR` environment variable to that path (see below) and `mkdir -p` it instead.
{% 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.
# Self hosted
Run Lunar Hub yourself on Kubernetes — the overview, prerequisites, install walkthrough, config sync, and day-2 operations, in the order you need them.
Self hosting means you run Lunar Hub on your own Kubernetes cluster and operate it: you provision its dependencies, run `helm install`, and own upgrades, secret rotation, and backups. If you would rather Earthly did all of that, see [Lunar Dedicated](/install/lunar-hub/dedicated) instead.
{% hint style="info" %}
Lunar Hub is supported on **Kubernetes only**. Bare-metal and Docker installations are not supported.
{% endhint %}
## In order
1. [**Overview**](/install/lunar-hub/self-hosted/overview) — what a Hub deployment is made of: the Hub service, the operator, the transient snippet pods, and the external dependencies they need. Read this first if you want the shape of the system before committing to it.
2. [**Prerequisites**](/install/lunar-hub/self-hosted/prerequisites) — Postgres, S3 buckets, namespaces, DNS, a licence, and your Git platform credentials. Everything that must exist before `helm install`.
3. [**Install walkthrough**](/install/lunar-hub/self-hosted/install-walkthrough) — step by step from zero to a working Hub, including the values file and how to verify the install.
4. [**Sync Config**](/install/lunar-hub/self-hosted/sync-config) — keep the Hub's copy of your configuration current on every push, from a GitHub Action or a GitLab CI job. Strongly recommended: without it you apply config changes by hand.
5. [**Day-2 operations**](/install/lunar-hub/self-hosted/day-2-operations) — upgrades, secret rotation, observability, backup and restore, and uninstall.
## Before you start
Two neighboring sections apply to Dedicated installs as well, so they sit outside this one:
* [**Git Platforms**](/install/git-platforms) covers creating the credential the Hub authenticates with, on GitHub or GitLab. You need it by the prerequisites step.
* [**Lunar CI Tracer**](/install/ci-tracer) covers build-time data, if you want it. The tracer installs on your CI runners rather than in the cluster, so it is independent of the Hub install and can be added later.
# 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/self-hosted/prerequisites).
## 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 credentials for your Git platform — a GitHub App or a GitLab group access token)
### External boundaries
```mermaid
flowchart LR
CLI["Lunar CLI"]
Agent["Lunar CI Tracer"]
Hub["Lunar Hub"]
PG[("PostgreSQL")]
S3[("S3 buckets
logs · resources")]
Git["GitHub or GitLab"]
CLI -- gRPC --> Hub
Agent -- gRPC --> Hub
Git -- webhooks --> Hub
Hub -- SQL --> PG
Hub -- reads/writes --> S3
Hub -- API --> Git
```
#### Hub
This is the central API server. It:
* talks to Postgres, your Git platform, and S3
* serves the gRPC API consumed by the CLI, CI tracers, and the Lunar operator
* receives Git platform 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 Tracer
Instruments your CI runners to report data to the Hub. This is also installed separately. We support [Self-hosted GitHub Actions](/install/ci-tracer/github-actions-self-hosted) and [Managed GitHub Actions](/install/ci-tracer/github-actions-managed) options, plus [Buildkite](/install/ci-tracer/buildkite). GitLab CI tracing is [coming soon](/install/ci-tracer/gitlab-ci) — see [GitLab](/install/git-platforms/gitlab) for how collection works there today.
### 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 your Git platform 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/self-hosted/prerequisites#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/self-hosted/install-walkthrough#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 / GitLab | Hub HTTP ingress | Inbound | Webhook delivery |
| CLI / CI tracers | Hub gRPC ingress | Inbound | API calls (config sync, results) |
| CLI / CI tracers | Hub HTTP ingress | Inbound | Pre-signed log URL fetches |
| Hub | GitHub / GitLab API | Outbound | Read repos, post results, manage webhooks |
| 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 tracers, run pods (sidecar) |
| `8001` | HTTP | Webhook receivers + pre-signed URL redirector for run logs | Your Git platform, Buildkite, CLI, CI tracers, sidecar |
| `8002` | HTTP | Liveness / readiness probes (`GET /health`, `GET /ready`) | Kubelet only |
The HTTP port serves webhook ingestion — `/webhooks/github`, `/webhooks/gitlab`, and `/webhooks/buildkite` — plus `/logs/runs/`, which redirects to pre-signed S3 URLs for log upload and 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/self-hosted/prerequisites) — external dependencies you need in place before `helm install`.
* [Install walkthrough](/install/lunar-hub/self-hosted/install-walkthrough) — 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/self-hosted/install-walkthrough) assumes you have them.
If you want a total picture of what you're about to deploy, read the [overview](/install/lunar-hub/self-hosted/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 your Git platform — github.com, GHES, gitlab.com, or your GitLab 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-connect-your-git-platform) | Git platform admin access | GitHub org admin (or a personal account) to create a GitHub App, and/or GitLab group Maintainer/Owner to create a group access token |
| [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 — your Git platform, 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/self-hosted/day-2-operations#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 — Connect your Git platform
Lunar needs credentials for the Git platform your components live on. At least one is required: the Hub refuses to start with neither configured. Set up both if you run both.
{% hint style="info" %}
Read [Git Platforms](/install/git-platforms) before you start. Most of Lunar behaves identically on GitHub and GitLab; merge gating is one exception.
{% endhint %}
{% tabs %}
{% tab title="GitHub" %}
The Hub authenticates as a **GitHub App** you create and install on your org. The hosted setup tool creates one in a couple of clicks:
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/sharing-github-apps/registering-a-github-app-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.
{% hint style="info" %}
**Need to create the App by hand?** On GitHub Enterprise Server, or when `earthly.dev` is unreachable from your browser, follow [manual setup](/install/git-platforms/github#manual-setup-alternative), which produces the same App. The [permissions and events it is granted](/install/git-platforms/github#permissions) are documented for security review whichever flow you use.
{% endhint %}
Capture these four before continuing:
| What | Source |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Owner (the GitHub org or user the App is installed on, e.g. `earthly`) | The `` in the install URL |
| App ID (numeric, e.g. `3635822`) | Setup tool result page, or the App settings page |
| Installation ID (numeric) | The trailing number in the URL after install: `https://github.com/organizations//settings/installations/` |
| PEM private key | Downloaded when the key was generated. GitHub shows it once, so save it now |
They become `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.*`) in [install Step 4](/install/lunar-hub/self-hosted/install-walkthrough#git-platform-credentials). All four are required together; a partial App configuration is rejected at startup.
Fronting several orgs from one Hub takes a different shape. See [multiple organizations](/install/git-platforms/github#multiple-organizations).
{% endtab %}
{% tab title="GitLab" %}
GitLab has no App model, so the Hub authenticates with a **service account token**: one for the whole instance on self-managed, or one per top-level group on GitLab.com, each covering every subgroup and project beneath it. [GitLab → Create the token](/install/git-platforms/gitlab#create-the-token) walks through creating it, and through the one choice that has consequences: which account it belongs to.
Capture these before continuing:
| What | Detail |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| Access token | `api` scope, `Maintainer` or `Owner` role in every group Lunar should serve |
| Group path | Only for a group service account: the top-level group it belongs to, e.g. `acme`. An instance service account's token needs none |
| Host | `gitlab.com`, or your instance hostname if self-managed |
They become one `HUB_GITLAB_TOKENS` entry in [install Step 4](/install/lunar-hub/self-hosted/install-walkthrough#git-platform-credentials). Serving several top-level groups from one Hub? See [multiple groups](/install/git-platforms/gitlab#multiple-groups).
{% hint style="warning" %}
**Self-managed GitLab must be listed by host.** Lunar decides whether a host is GitLab from this configuration, so note your instance hostname now. An omitted host is treated as GitHub, and every operation against it then fails confusingly. `gitlab.com` is recognized without configuration.
{% endhint %}
{% endtab %}
{% endtabs %}
## 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 (GitHub only) | `private-key` — the PEM from Step 5 |
| `lunar-gitlab-token` | You (GitLab only) | `token` — the group access token from Step 5, mounted as a file |
| `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/self-hosted/install-walkthrough#pulling-images-from-ghcr) from your licence JWT |
| `-auth-token` | Chart (auto-generated) | Shared bearer token for the CLI and CI tracers |
| `-github-webhook` | Chart (auto-generated) | Webhook signing secret for GitHub — the Hub registers it automatically when it creates per-repo webhooks. Override it per App with a `webhook_secret` in `HUB_GITHUB_APPS` |
| `-gitlab-webhook` | Chart (auto-generated) | The same, for GitLab project hooks. Override it per group with a `webhook_secret` in `HUB_GITLAB_TOKENS` |
| `-grafana-admin` | Chart (auto-generated) | Grafana admin username and password — **only when the chart runs Grafana for you** ([Option A](/install/lunar-hub/self-hosted/install-walkthrough#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/self-hosted/install-walkthrough#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/self-hosted/install-walkthrough#grafana).
{% hint style="info" %}
**Your licence also covers the CI tracer.** The credential the chart uses to pull Lunar's container images — derived from your licence with [`lunar licence pull-secret`](/install/lunar-hub/self-hosted/install-walkthrough#pulling-images-from-ghcr) for the `regcred` secret above — is also what the Hub uses to fetch the CI tracer binary for your runners. You don't need a separate credential for the CI tracer.
If your licence doesn't include CI tracer distribution, the Lunar CLI reports a clear error the first time a runner tries to download the tracer. If you plan to use the CI tracer, 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/self-hosted/install-walkthrough#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`.
Policy result posting has its own per-Hub-replica cap, `HUB_MAX_WORKERS_POLICY_POST` (default `20`; `0` means unlimited). Set it through `hub.extraEnv` when you need more posting capacity. Posting previously shared `HUB_MAX_WORKERS_POLICY`; after upgrading, a custom value for that setting continues to control policy execution but does not raise the posting cap. Review both settings during upgrade, and monitor the `policy_post` queue backlog and oldest job age. Each repository permits one active posting invocation across replicas, while different repositories can post concurrently.
Repository reconciliation has a separate per-Hub-replica cap, `HUB_MAX_WORKERS_REPO_SYNC` (default `5`; `0` means unlimited). This needs to be set through `hub.extraEnv`:
```yaml
hub:
extraEnv:
- name: HUB_MAX_WORKERS_REPO_SYNC
value: "1"
```
Lowering the cap spreads GitHub and GitLab API traffic over more time but does not reduce total request volume. Watch the `repo_sync` queue backlog and oldest available job age after lowering it; sustained growth means the cap is below the incoming work rate.
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/self-hosted/install-walkthrough) — step-by-step from zero to a working Hub.
* [Chart README](https://github.com/earthly/charts/blob/main/README.md) — complete `values.yaml` reference.
# Install Walkthrough
This walkthrough takes you from zero to a working Lunar Hub. It assumes you've worked through the [prerequisites](/install/lunar-hub/self-hosted/prerequisites), 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/self-hosted/prerequisites). 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/self-hosted/prerequisites#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/self-hosted/prerequisites#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/self-hosted/prerequisites#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
* Your Git platform credential: the GitHub App PEM, or the GitLab group access token, from [prereqs Step 5](/install/lunar-hub/self-hosted/prerequisites#step-5-connect-your-git-platform)
* A signed Hub licence JWT (from your Earthly contact)
Other secrets, like the Hub auth token, the webhook signing secrets, and the 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=''
```
**Git platform credential** — create the one that matches your platform, or both if you run both:
{% tabs %}
{% tab title="GitHub" %}
Base64-encode the App's 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 %}
{% endtab %}
{% tab title="GitLab" %}
The Hub reads the group access token from a mounted file, so it goes in as plain text with no base64 step:
```bash
kubectl -n lunar create secret generic lunar-gitlab-token \
--from-literal=token=''
```
Step 4 mounts this secret at the `token_path` you declare in `HUB_GITLAB_TOKENS`.
{% endtab %}
{% endtabs %}
**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. Its `hub.github` block assumes GitHub; [Git platform credentials](#git-platform-credentials) below covers what to change on GitLab.
```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.21.2"
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.21.2"
initImage:
tag: "3.21.2"
sidecarImage:
tag: "3.21.2"
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.
### Git platform credentials
Serving both platforms from one Hub is supported: configure both, and each repository is routed by its host.
{% tabs %}
{% tab title="GitHub" %}
The `hub.github.app` block in the sample above is the whole configuration. Its `id`, `installId`, and `owner` come from [prereqs Step 5](/install/lunar-hub/self-hosted/prerequisites#step-5-connect-your-git-platform); the private key comes from the `lunar-github-app` secret created in Step 3. All four are required together; a partial App configuration is rejected at startup.
On **GitHub Enterprise Server**, also point the Hub at your instance:
```yaml
hub:
github:
baseUrl: https://github.example.com
```
Fronting several GitHub orgs from one Hub takes a different shape. See [GitHub → multiple organizations](/install/git-platforms/github#multiple-organizations).
{% endtab %}
{% tab title="GitLab" %}
The chart has dedicated values for the GitHub App (`hub.github.app.*`) but not yet for GitLab, so GitLab credentials go in through the generic passthroughs: the environment variable via `hub.extraEnv`, and the token file via a mounted secret.
```yaml
hub:
extraEnv:
# ... alongside AWS_REGION from the sample above
- name: HUB_GITLAB_TOKENS
value: '[{"group":"acme","host":"gitlab.com","token_path":"/secrets/gitlab/token"}]'
volumeMounts:
- name: gitlab-token
mountPath: /secrets/gitlab
readOnly: true
volumes:
- name: gitlab-token
secret:
secretName: lunar-gitlab-token
```
One entry per token; `token_path` must match the `mountPath` above. `group` binds the token to that group and its subtree, which is what a GitLab.com group service account needs; leave it out for an instance service account on self-managed, and the token serves every group the account is a member of. The webhook signing secret is not in there: the chart generates it, the same as it does for GitHub. [GitLab → Hub configuration](/install/git-platforms/gitlab#hub-configuration-self-hosted) has the full field reference and the multi-group form.
{% hint style="warning" %}
**Keep the `hub.github` block even on a GitLab-only install.** The Hub itself needs only one Git platform configured, but the chart does not yet know that: its template guard requires the GitHub App values and aborts the render with `hub.github.app.id is required (numeric, non-zero)` when they are absent. Until the chart gains dedicated GitLab values, a chart install has to carry a GitHub App configuration alongside `HUB_GITLAB_TOKENS`.
{% endhint %}
{% endtab %}
{% endtabs %}
### 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/self-hosted/prerequisites#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/self-hosted/prerequisites#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/self-hosted/prerequisites#step-5-connect-your-git-platform). |
| `no forge configured` | Neither GitHub App credentials nor `HUB_GITLAB_TOKENS` are set. At least one Git platform is required. See [prerequisites step 5](/install/lunar-hub/self-hosted/prerequisites#step-5-connect-your-git-platform). |
| `read HUB_GITLAB_TOKENS ... token_path` | The GitLab token file isn't where the config says it is. Confirm `token_path` matches the `mountPath` of the volume you mounted the `lunar-gitlab-token` secret at. |
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/self-hosted/prerequisites#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:
{% tabs %}
{% tab title="GitHub" %}
```bash
curl -sS -o /dev/null -w "%{http_code}\n" https://lunar.example.com/webhooks/github
```
{% endtab %}
{% tab title="GitLab" %}
```bash
curl -sS -o /dev/null -w "%{http_code}\n" https://lunar.example.com/webhooks/gitlab
```
{% endtab %}
{% endtabs %}
Expected: `405`. The endpoints accept only `POST`, and the method check runs before any signature validation, so a plain `GET` like this is rejected with `405 Method Not Allowed`. That still proves the route reaches the Hub. `404` or `502` probably means the HTTP Ingress isn't reaching the Hub, so 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. This exercises the full path: CLI → Hub → your Git platform → repo fetch → Hub stores config. As a side effect, the Hub registers a webhook on every repository referenced in the config.
{% tabs %}
{% tab title="GitHub" %}
```bash
lunar hub pull github://your-org/your-config-repo@main
```
Verify the webhook on any repository in the config: repo → **Settings → Webhooks**, pointing at `https://lunar.example.com/webhooks/github`.
{% endtab %}
{% tab title="GitLab" %}
```bash
lunar hub pull gitlab://gitlab.com/your-group/your-config-repo@main
```
The host is required in the URL, even for gitlab.com.
Verify the webhook on any project in the config: project → **Settings → Webhooks**, pointing at `https://lunar.example.com/webhooks/gitlab`.
{% endtab %}
{% endtabs %}
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/self-hosted/day-2-operations#other-secrets) for rotation.
## Next steps
* [Install the Lunar CLI](/install/cli) on your workstation.
* [Install the Lunar CI Tracer](/install/ci-tracer/github-actions-self-hosted) on your CI runners.
* [Day-2 operations](/install/lunar-hub/self-hosted/day-2-operations) — upgrades, secret rotation, observability, uninstall.
# Sync Config
Keep Lunar Hub's copy of your config repo current on every push — with the sync-config GitHub Action, or a GitLab CI job.
Lunar Hub keeps its own copy of your configuration (the manifest plus your snippets), and it needs refreshing whenever your config repository changes. Both options below wrap the same command, [`lunar hub pull`](/docs/lunar-cli#lunar-hub-pull), so the CLI reference is the source of truth for the flags. Run the one that matches where your config repository lives, on every push to its default branch.
## GitHub Actions
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.
{% 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 %}
The action's inputs map 1:1 to the equivalent CLI flags — see the [CLI reference](/docs/lunar-cli#lunar-hub-pull) 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.
## GitLab CI
There is no published GitLab CI component or template — you write a short job that runs the same `lunar hub pull` on every push to the config repository's default branch:
{% code title=".gitlab-ci.yml" %}
```yaml
sync-lunar-config:
image: ubuntu:24.04
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
variables:
LUNAR_HUB_HOST: lunar.example.com
LUNAR_HUB_GRPC_PORT: "443"
LUNAR_HUB_HTTP_PORT: "443"
before_script:
- apt-get update && apt-get install -y --no-install-recommends curl ca-certificates
- curl -fsSL -o /usr/local/bin/lunar
"https://github.com/earthly/lunar-dist/releases/latest/download/lunar-linux-amd64"
- chmod +x /usr/local/bin/lunar
script:
- lunar hub pull "gitlab://gitlab.com/$CI_PROJECT_PATH@$CI_COMMIT_BRANCH"
```
{% endcode %}
Set `LUNAR_HUB_TOKEN` as a **masked CI/CD variable** on the project or group (**Settings → CI/CD → Variables**), not in the file.
{% hint style="info" %}
The manifest URL must include the host, even for gitlab.com: `gitlab://gitlab.com/group/project@branch`. GitLab namespaces can contain dots, so Lunar cannot tell a host-less first segment apart from a group name.
For nested subgroups, `$CI_PROJECT_PATH` already expands to the full path (`group/subgroup/project`), so the same line works unchanged.
{% endhint %}
### Useful flags
`lunar hub pull` accepts several options that change what happens after the config lands. The full list is in the [CLI reference](/docs/lunar-cli#lunar-hub-pull); the ones most often wanted in this job:
| Flag | Effect |
| ------------------------- | --------------------------------------------------------------- |
| `--rerun-code-collectors` | Re-run affected code collectors after the pull. Off by default. |
| `--rerun-catalogers` | Re-run global catalogers after the pull. Off by default. |
| `--dry-run` | Validate without applying, and without contacting the Hub. |
### Validating config on merge requests
`--dry-run` needs no Hub connection, which makes it a good merge-request check. It does need to reach GitLab to resolve any `uses:` plugins:
{% code title=".gitlab-ci.yml" %}
```yaml
validate-lunar-config:
image: ubuntu:24.04
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
variables:
LUNAR_GITLAB_TOKEN: $LUNAR_GITLAB_TOKEN
script:
- lunar hub pull --dry-run "gitlab://gitlab.com/$CI_PROJECT_PATH@$CI_COMMIT_SHA"
```
{% endcode %}
The token needs read access to the config repository and to any repositories its plugins come from. See [Validating your config](/configuration/lunar-config/validation).
# 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 tracers 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 tracer'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.
### Git platform credentials
Both are read once at boot, so a rolling restart is always required after updating the secret.
{% tabs %}
{% tab title="GitHub" %}
**GitHub App private key (`lunar-github-app`).** GitHub allows multiple active keys per App, so this rotates 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 (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`.
4. **Verify** webhooks still deliver (GitHub → any repo → **Settings → Webhooks → Recent Deliveries**).
5. **Delete the old key** in GitHub.
{% endtab %}
{% tab title="GitLab" %}
**Group access token (`lunar-gitlab-token`).** Revoking the old token takes effect immediately, so revoke it last:
1. **Create the replacement token** in GitLab (group → **Settings → Access tokens**), with the same scope and role as the original.
2. **Update the secret in place:**
```bash
kubectl -n lunar create secret generic lunar-gitlab-token \
--from-literal=token='' \
--dry-run=client -o yaml | kubectl apply -f -
```
3. **Roll the Hub** — `kubectl -n lunar rollout restart deployment/lunar-hub`.
4. **Revoke the old token** in GitLab.
{% hint style="warning" %}
GitLab access tokens expire on a fixed date and nothing renews them. When one lapses, Lunar silently stops posting results and reacting to webhooks for that group. Put the expiry date in a calendar and rotate ahead of it.
{% endhint %}
{% endtab %}
{% endtabs %}
### Webhook secrets
The chart generates one of these per platform.
{% hint style="warning" %}
**Rotating a webhook secret costs you deliveries, on both platforms.** A hook carries the secret it was created with, so every repository that already has one starts failing signature validation the moment Lunar Hub restarts on the new value.
On **GitHub** the fleet repairs itself from there, a repository at a time as each reports the problem, at up to 3,600 an hour — often a working day or less, though GitHub's own rate limiting can stretch it. On **GitLab** there is no self-heal at all, and the window is not free: failing deliveries get the hook [auto-disabled](#webhook-health), permanently after 40 consecutive failures.
{% endhint %}
Start the same way on both platforms:
1. **Replace the secret and restart.** Until Lunar Hub restarts it keeps validating against the old value, and it also stamps the old value onto any hook it creates.
2. **Repair the hooks.** GitHub does this on its own; on GitLab you delete each hook so Lunar recreates it. See the tab for your platform.
3. **Confirm deliveries are succeeding again** before considering the rotation done — see [Webhook health](#webhook-health).
{% tabs %}
{% tab title="GitHub" %}
```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
```
Nothing else to do. A rejected delivery is how Lunar Hub finds out a hook is stale: it recognizes the signature failure, checks that the hook is one it installed, and re-stamps the current secret onto it. That repository's deliveries succeed from then on.
Repairs run one at a time, a second apart — the gap GitHub asks for between modifying requests. At best that is 3,600 repositories an hour, so under an hour for a 1,000-repository install and around eight for 30,000.
Treat those as a floor on the time, not an estimate of it. GitHub also caps content-generating requests at 500 an hour and does not say whether editing a webhook counts as one. If it does, a rotation spends that hour's allowance in about eight minutes and then waits — Lunar backs off when GitHub says so and resumes when the window reopens, so a large fleet can take considerably longer than the arithmetic suggests. Watch **Recent Deliveries** rather than a stopwatch.
Two things follow from repairing on demand rather than sweeping the fleet:
* **A repository loses deliveries until its repair runs** — not only the one that reports the problem. GitHub does not retry, so anything that arrives in that gap never reaches Lunar. Replay them from **Settings → Webhooks → Recent Deliveries → Redeliver**, within GitHub's three-day window.
* **A quiet repository stays stale until it next sees activity**, since nothing reports the problem for it. It repairs on its first delivery afterwards.
`HUB_WEBHOOK_HEAL_MIN_INTERVAL` sets the spacing. Shortening it means going faster than GitHub asks you to, and that allowance is the same one Lunar spends posting commit statuses and PR comments — content-creation limits count the web interface, the REST API and GraphQL together — so a rotation in a hurry can delay the results your team is waiting on. On a large fleet, rotate outside your busiest hours instead. Setting it to `0` turns self-healing off, which leaves the manual procedure below.
{% hint style="info" %}
**Repairing by hand instead.** With `HUB_WEBHOOK_HEAL_MIN_INTERVAL=0`, delete Lunar's hook on each repository through the GitHub API — it is the one whose URL points at your Hub's `/webhooks/github` path. Lunar recreates it on that repository's next sync, which the freshness record gates: at worst `HUB_WEBHOOK_FRESHNESS` (12h by default) after the delete.
{% endhint %}
To rotate a per-app `webhook_secret` in `HUB_GITHUB_APPS` — which takes the place of the chart secret for that App's webhooks — edit that value instead of deleting the chart secret, then `helm upgrade` and restart. Repair is automatic in the same way, scoped to that App's repositories. Doing this one App at a time keeps each blast radius to a single App.
{% endtab %}
{% tab title="GitLab" %}
```bash
kubectl -n lunar delete secret lunar-gitlab-webhook
helm upgrade lunar earthly/lunar -n lunar -f values.yaml
kubectl -n lunar rollout restart deployment/lunar-hub
```
GitLab has no equivalent self-heal, so the hooks have to be deleted by hand. Lunar's hook on a project is the one whose URL points at your Hub's `/webhooks/gitlab` path. Delete it and Lunar recreates it on that project's next sync, carrying the new secret — but the freshness record gates that, so budget up to `HUB_WEBHOOK_FRESHNESS` (12h by default) per project before the replacement appears.
Do not leave projects sitting on the old secret while you wait. GitLab disables a hook after four consecutive failures and **permanently after forty**, and Lunar's automatic re-enable will not help while the secret is still wrong — it re-enables the hook, the next delivery fails, and the count keeps climbing. Delete and recreate promptly rather than waiting out the sync.
To rotate a per-group `webhook_secret` in `HUB_GITLAB_TOKENS`, edit that value instead of deleting the chart secret, then `helm upgrade` and restart. Doing this one group at a time keeps each blast radius to a single group.
{% endtab %}
{% endtabs %}
### 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/self-hosted/install-walkthrough#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 ''
```
## Webhook health
Lunar registers a webhook on every tracked repo and re-verifies it periodically, repairing a hook that exists but has stopped delivering:
* **GitLab** auto-disables a hook after 4 consecutive delivery failures (self-heals after a backoff) and **permanently after 40** — which a sustained problem, like a wrongly configured webhook secret or a weeks-long Hub outage, will eventually reach. Lunar detects the disabled state and re-enables the hook by sending a test request.
* **GitHub** never disables a hook for failing, but a repo admin can untick **Active** in the repo's webhook settings. Lunar detects the inactive hook and switches it back on. A hook left on an old [webhook secret](#webhook-secrets) is repaired separately, off the failed delivery itself rather than the re-sync.
Repair happens automatically on the periodic re-sync, at worst one freshness window (`HUB_WEBHOOK_FRESHNESS`, default 12h) plus one sync pass after the hook went dead. It only sticks if the underlying cause is fixed: a GitLab hook whose deliveries keep failing (e.g. a still-wrong webhook secret) will just be disabled again. Events that fired while the hook was dead are not replayed; neither Git platform redelivers them.
## 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/self-hosted/install-walkthrough#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 %}
## Operating the GitLab merge gate
If you run [the merge gate](/install/git-platforms/gitlab#merge-gate) on GitLab Ultimate, two of its properties are operational rather than install-time:
* **It is fail-closed.** A Hub outage leaves gated merge requests blocked. That is the correct default for a compliance control, but it means a Lunar incident becomes a merge freeze.
* **The lever is on the GitLab side.** To unblock merges during an incident, a project Owner disables **Status checks must succeed** in the project's merge-request settings. Lunar re-enables it on the next sync, so this buys time rather than being an opt-out. A project that should be permanently ungated belongs out of Lunar's configuration instead.
Individual blocked merge requests do not need an incident response. An authorized engineer can comment [`/lunar bypass: `](/docs/pr-comments) on the merge request, which is recorded and applies to that commit only.
## 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 your Git platform credential (the GitHub App PEM or the GitLab group access token), 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-gitlab-token`, `lunar-hub-licence`).
* **Anything Lunar provisioned on your GitLab projects** — webhooks, the `Earthly Lunar` status check, and the **Status checks must succeed** setting. Uninstalling the Hub does not undo them, and with the Hub gone nothing answers the status check, so gated merge requests stay blocked. Before uninstalling, disable that setting on the affected projects.
* Chart-managed secrets (`-auth-token`, `-github-webhook`, `-gitlab-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-gitlab-token \
lunar-hub-licence \
lunar-auth-token lunar-github-webhook lunar-gitlab-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
# - Revoke the GitLab group access token, and remove the status check and
# "Status checks must succeed" setting from any gated projects
```
## 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 for you — the overview, what your team does to bring one up, and the private paths in and out of it.
Lunar Dedicated is a fully managed, single-tenant Lunar install. Earthly provisions it in an AWS account dedicated to you and owns the whole lifecycle: upgrades, patching, monitoring, backup and restore. If you would rather run the Hub on your own Kubernetes, see [Self hosted](/install/lunar-hub/self-hosted) instead.
{% hint style="info" %}
Earthly runs the infrastructure; you keep custody of your data and your credentials. The CLI and CI tracer are installed and configured exactly as they are on a self-hosted Hub.
{% endhint %}
## In order
1. [**Overview**](/install/lunar-hub/dedicated/overview) — how a Dedicated install is put together, the ways you can reach it, what Earthly needs from you, and how it handles your data and secrets. Read this first, and hand it to your security reviewer.
2. [**Setup**](/install/lunar-hub/dedicated/setup) — everything your side does, in order: the questionnaire, your depositor account, your Git platform credential, and the secret deposit. This is the page to work from.
3. [**PrivateLink to Your Hub**](/install/lunar-hub/dedicated/privatelink-inbound) — the recommended way for your CI runners, CLI users, and browsers to reach the install, and skippable only if your CI runs on shared hosted runners. Your side creates one interface endpoint and two DNS records. Settle how your Git platform will deliver webhooks early on, because that part can carry a lead time you don't control.
4. [**PrivateLink to Your Internal Systems**](/install/lunar-hub/dedicated/privatelink-outbound) — only if something your install must reach isn't on the public internet: a self-managed Git platform, or a collector target such as an internal registry, ticketing system, or API. It comes last in this list, but start it first. It needs a DNS change and an AWS domain-ownership check on your side, which makes it the longest-lead-time item in onboarding. You can forward the page to your networking team on its own.
## Before you start
Two neighboring sections apply to Dedicated installs as well, so they sit outside this one:
* [**Git Platforms**](/install/git-platforms) covers creating the credential Lunar authenticates with, on GitHub or GitLab. You create it and you [deposit it yourself](/install/lunar-hub/dedicated/setup#step-4-deposit-your-secrets), so it never passes through Earthly. The Hub-configuration sections of those pages are for self-hosted installs only.
* [**Lunar CI Tracer**](/install/ci-tracer) covers build-time data, if you want it. The tracer installs on your CI runners rather than in your install, so it is independent of onboarding and can be added at any point afterwards.
Still deciding whether Dedicated is the right fit? The [Overview](/install/lunar-hub/dedicated/overview) covers the trade-offs, or [book a demo](https://earthly.dev/book-demo/) and Earthly will walk your team through the model.
# Overview
How a Lunar Dedicated install works — a single-tenant install that Earthly provisions, operates, and upgrades end-to-end in a dedicated AWS account, reachable over private networking or the internet.
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 you reach it over private networking or, where your CI can't, over the internet. It's for teams that want Lunar's guardrails without running the [Hub](/install/lunar-hub/self-hosted/overview) themselves.
This page explains how it works, who it fits, and what Earthly needs from you to stand one up. [Setup](/install/lunar-hub/dedicated/setup) is the hands-on companion covering what your team actually does.
{% hint style="info" %}
Lunar Dedicated is a managed offering, distinct from the self-hosted [Lunar Hub](/install/lunar-hub/self-hosted/overview). With Dedicated, Earthly runs the infrastructure; with the self-hosted Hub, you do. The CLI and CI tracer are installed and configured the same way in both.
{% endhint %}
## How it works
```mermaid
flowchart LR
Git["GitHub / GitLab"]
subgraph Earthly["Earthly (management account)"]
Mgmt["Deploy and operate tooling"]
end
subgraph Dedicated["Your dedicated AWS account"]
Hub["Lunar Hub"]
WH["Webhook listener"]
Data[("Postgres · S3 · secrets")]
Hub --> Data
end
subgraph You["Your network"]
CI["CI runners · Lunar CLI"]
end
Mgmt -- "assume-role (IAM)" --> Dedicated
CI -- "internet or PrivateLink —
you choose" --> Hub
Git -- "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.
* **You choose how the hub is reached.** Over the internet on your own hostname, behind TLS and token authentication, or privately over [PrivateLink](/install/lunar-hub/dedicated/privatelink-inbound). Joining the two networks directly (peering / Transit Gateway) is [coming soon](#how-you-connect). Whether the webhook listener stays public depends on where your Git platform lives: a cloud-hosted one delivers from the internet, while a platform in your own network can deliver privately.
* **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 |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Reachable CI** | The Lunar CLI and [CI tracer](/install/ci-tracer/github-actions-self-hosted) must run somewhere that can reach the hub. With internet access that's anywhere, including GitHub-hosted runners; with private access it means self-hosted runners in your network, or runners with VPN/PrivateLink access. On GitLab there is no tracer to place ([tracing is coming soon](/install/ci-tracer/gitlab-ci)), but the CLI still needs that reachability. |
| **A network to connect from** (private access only) | An AWS VPC that can reach a PrivateLink endpoint. Not needed if you reach the hub over the internet. |
| **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. |
| **Git platform credentials** | On GitHub, a [GitHub App](/install/git-platforms/github) you create and install on the org(s) and repositories Lunar should monitor. On GitLab, a [group access token](/install/git-platforms/gitlab#authentication) per top-level group. If your instance is self-managed and not reachable from the public internet, Lunar also needs a [private path to it](/install/lunar-hub/dedicated/privatelink-outbound). |
{% hint style="info" %}
**Coming soon.** Joining your network to the install directly (VPC peering or Transit Gateway), connecting privately with no existing AWS footprint (site-to-site VPN), and multi-region 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/self-hosted/overview) is a better fit. [Book a demo](https://earthly.dev/book-demo/) to work with us.
{% endhint %}
## How you connect
Two ways to reach your hub are available today, with a third on the way. PrivateLink is the one Earthly recommends wherever your CI can use it; the deciding factor is usually where your CI runs.
| | **Internet** | **PrivateLink** | **Joined network** (peering / Transit Gateway) |
| -------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------- |
| Availability | Available now | Available now | **Coming soon** |
| What it is | The hub on your own hostname, behind TLS and token authentication | A private one-way "door" from your network to the hub | Your network and the install's network are routed together |
| Reaching the hub | From anywhere, including GitHub-hosted runners | Through one private endpoint you create | Over the joined network, at a private address |
| Address coordination | None | None (address ranges can overlap freely) | Address ranges must not overlap |
| Your setup effort | None | Create one endpoint and two DNS records | Accept the join and add routes (usually your networking team) |
| Best when | Your CI runs on shared hosted runners, which can't reach a private endpoint | **Recommended.** Your CI runs in a VPC you control | You already run a Transit Gateway |
{% hint style="info" %}
Your install reaches outwards as well as inwards. The Hub calls your Git platform to read repositories, register webhooks, and post results; collectors, catalogers, and policies run *inside* your install and reach the systems they gather data from. For a dedicated customer any of those may be internal: a self-managed GitHub Enterprise Server or GitLab instance, registries, ticketing, internal APIs. That's why connectivity is two-way, and why onboarding asks where your CI runs and what your install needs to reach.
{% endhint %}
The two directions are set up independently, and you may need only one of them:
* **Reaching the hub**: how your CI runners, CLI users, and browsers get to your install. Choose from the options above. Over the internet there's nothing for you to do; PrivateLink needs one interface endpoint and two DNS records from you, covered in [PrivateLink to Your Hub](/install/lunar-hub/dedicated/privatelink-inbound).
* **Lunar reaching your internal systems**: needed if anything your install must reach sits off the public internet, such as a self-managed Git platform or an internal registry, ticketing system, or API. You publish each target as a PrivateLink endpoint service; see [PrivateLink to Your Internal Systems](/install/lunar-hub/dedicated/privatelink-outbound). **This one has a long lead time, so start it first.**
## What Earthly needs from you
These answers shape your install:
| What | Why |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Region** | Where the install (and your data) lives |
| **Hub access** | Internet or PrivateLink, and where your CI runs. Say so if you would rather join networks directly, so Earthly can tell you where that sits on the roadmap |
| **Internal targets** | Whether anything Lunar must reach sits off the public internet (a self-managed Git platform, or collector targets like internal registries, ticketing, or APIs), and if so, how many distinct hostnames. Drives [PrivateLink to Your Internal Systems](/install/lunar-hub/dedicated/privatelink-outbound), the longest-lead-time item in onboarding |
| **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 |
| **Git platform** | Which one, and where it lives: for [GitHub](/install/git-platforms/github), the App ID and installation ID plus the org(s)/repos it's installed on; for [GitLab](/install/git-platforms/gitlab), the top-level group(s) and, if self-managed, your instance hostname. The credential itself you [deposit](/install/lunar-hub/dedicated/setup#step-4-deposit-your-secrets) |
| **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** (if required) | Whether your security review requires a web-application firewall in front of a public webhook listener. It isn't part of the standard install, so raise it and Earthly will scope it with you |
## 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
Summarized here; [Setup](/install/lunar-hub/dedicated/setup) has the commands and is the page to work from.
1. **Send your** [**questionnaire answers**](#what-earthly-needs-from-you)**.** Earthly replies with your coordinates packet (tenant, region, dedicated account ID, deposit role ARN, deposit ExternalId, and your webhook URL) and starts building.
2. **Start** [**private access to your internal systems**](/install/lunar-hub/dedicated/privatelink-outbound), if your Git platform or any collector target isn't on the public internet. Longest lead time in onboarding, so start it first.
3. [**Nominate your depositor account**](/install/lunar-hub/dedicated/setup#step-2-identify-your-depositor-account): the AWS account you'll deposit secrets from (there's a path for teams without one).
4. [**Set up your Git platform**](/install/lunar-hub/dedicated/setup#step-3-set-up-your-git-platform) and send Earthly the identifiers: on GitHub the App ID, installation ID, and org; on GitLab the top-level group(s) and your instance hostname if you're self-managed.
5. [**Deposit your secrets**](/install/lunar-hub/dedicated/setup#step-4-deposit-your-secrets): a \~30-minute terminal task once the packet and the credential exist. Secrets are written **directly into your dedicated account's** secret store through a write-only role, never through Earthly's systems.
6. [**Go live**](/install/lunar-hub/dedicated/setup#go-live): Earthly verifies the install end-to-end and hands over your access token, plus a Grafana login if your install is reachable over the internet; you load workload secrets, finish DNS if you delegated a subdomain, and create your inbound endpoint if you chose PrivateLink.
None of this needs a meeting; most teams have all of it ready before their first call with Earthly.
## 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 rolling hub restart).
* **A monthly infra window** for node patches, add-on updates, and the occasional infrastructure upgrade.
Every Dedicated install runs the hub redundantly, so routine upgrades roll through without taking the service down; expect at most a brief interruption as connections move. Planned windows are excluded from the uptime clock. Critical security patches and forced version deprecations can land out-of-window, with notice.
**On GitLab, one recurring task stays with you.** Group access tokens carry a fixed expiry, and there is no overlap period where old and new both work. Create the replacement in GitLab and [deposit it](/install/lunar-hub/dedicated/setup#step-4-deposit-your-secrets) ahead of the expiry date, using the same command as at setup, then revoke the old one. See [expiry and rotation](/install/git-platforms/gitlab#expiry-and-rotation). If a token lapses, Lunar stops posting results and stops reacting to webhooks for that group. GitHub App credentials do not expire this way.
## 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, with no other workloads.
* **Data residency.** 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, and Earthly never holds them.** You [deposit](/install/lunar-hub/dedicated/setup#step-4-deposit-your-secrets) your Git platform credential (the GitHub App private key, or the GitLab group access token) into your install's own secret drop over a write-only role, and your workload secrets (API keys) go straight to your hub via the CLI. Neither passes through Earthly's central systems, and both live encrypted inside your install.
* **Full audit visibility.** Every action Earthly's roles take is recorded in AWS CloudTrail.
* **Defined data lifecycle.** Retention windows for queue history, catalog history, and the Hub's working files are set for your install; see [Data Retention](/configuration/hub-configuration/data-retention) for what each window covers and what it does not. 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/self-hosted/overview) is a better fit; [book a demo](https://earthly.dev/book-demo/).
{% hint style="warning" %}
**Custody is audited.** 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/self-hosted/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
* Hub access over the internet, or privately via PrivateLink
* A redundant hub, so planned upgrades roll through without downtime
* A single region per install
* Full lifecycle management: provisioning, upgrades, patching, monitoring, backup/restore, and clean offboarding
## Next steps
[Setup](/install/lunar-hub/dedicated/setup) is where your team picks it up: the questionnaire, your depositor account, your Git platform credential, and the secret deposit.
If anything Lunar must reach sits off the public internet, such as a self-managed Git platform or a collector target, start [PrivateLink to Your Internal Systems](/install/lunar-hub/dedicated/privatelink-outbound) in parallel. It's the longest-lead-time item in onboarding.
Earthly is also glad to walk through the model live, answer your security team's questions, and map out what onboarding looks like for your environment.
Book a demo
# Setup
What your team does to bring up a Lunar Dedicated install, covering connectivity, the depositor account, your Git platform credential, and the secret deposit.
Earthly provisions and operates your entire install. This page is everything your side does, in order, with the reasoning behind each step.
Read the [Overview](/install/lunar-hub/dedicated/overview) first if you want the model, the security posture, and what the service includes. This page is the hands-on companion.
## Your steps at a glance
| Step | Who does it | When |
| ----------------------------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------- |
| [Questionnaire answers](#first-the-questionnaire) | Whoever owns the rollout | First (everything else keys off them) |
| [1. Private connectivity](#step-1-private-connectivity-if-you-need-it) | Your AWS/network team | **Start immediately**; this one can have lead time |
| [2. Identify your depositor account](#step-2-identify-your-depositor-account) | Your AWS admin | Any time before the deposit |
| [3. Set up your Git platform](#step-3-set-up-your-git-platform) | Your GitHub org admin, or GitLab group owner | Any time before the deposit |
| [4. Deposit your secrets](#step-4-deposit-your-secrets) | Either, from a terminal | Last (needs the packet and the credential) |
Steps 2 and 3 are quick and independent. **Step 1 is the one that determines your timeline.** It involves DNS changes on your side, plus an AWS domain-ownership check or a request to your Git platform vendor depending on which direction you need, so start it the day you send your answers even though it's needed last.
Earthly builds the install in parallel. The only early input it needs from you is your depositor account ID ([step 2](#step-2-identify-your-depositor-account)).
## First, the questionnaire
Your answers to the [onboarding questionnaire](/install/lunar-hub/dedicated/overview#what-earthly-needs-from-you) parameterize the install: region, hub access, internal targets, DNS, sizing, maintenance windows, contacts. Send them to Earthly whenever they're settled; nothing waits on a meeting.
Earthly replies with your **coordinates packet**: tenant name, region, dedicated account ID, deposit role ARN, deposit ExternalId, and your webhook URL. Several steps below need values from it.
## Step 1 — Private connectivity, if you need it
Traffic crosses between your network and the install in both directions, and each direction is its own piece of setup. You may need one, both, or neither.
| Direction | You need it when | What you build |
| -------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------- |
| [Lunar reaching your systems](#lunar-reaching-your-internal-systems) | something Lunar must reach isn't on the public internet | an endpoint service in front of each system |
| [Reaching the hub](#your-ci-and-browsers-reaching-the-hub) | your CI runs in a VPC you control (recommended) | one interface endpoint and two DNS records |
Both are AWS PrivateLink, and both are your networking team's work. Each has a page written to be forwarded on its own. Work out which apply the day you send your questionnaire answers, because either can carry lead time you don't control. That's why this is step 1 even though nothing needs it until the end.
### Lunar reaching your internal systems
The Hub calls your Git platform to read repositories, register webhooks, and post results. Collectors, catalogers, and policies run *inside* your install and reach the systems they gather data from, such as registries, ticketing, and internal APIs. If any of those targets isn't reachable from the public internet, Lunar needs a private path to it.
**This includes your Git platform itself.** A self-managed GitHub Enterprise Server or GitLab instance that only resolves inside your network is one of these targets, and an easy one to overlook: the Hub needs the private path before any collector does.
**Start here if that applies to you:** [**PrivateLink to Your Internal Systems**](/install/lunar-hub/dedicated/privatelink-outbound)**.** It covers publishing your internal service as an AWS PrivateLink endpoint service, allowlisting Earthly's dedicated account, and associating a verified DNS name so Lunar reaches your service by its real hostname with working TLS.
{% hint style="warning" %}
**This can take time.** The AWS work is straightforward, but it includes publishing a DNS record and waiting for AWS to verify domain ownership, which means a DNS change on your side (and potentially your change-management process). If DNS changes queue behind a change window, that wait alone can add days. Start this in parallel *first*, even though it isn't needed until the end.
{% endhint %}
Not sure it applies? The [Do you need this?](/install/lunar-hub/dedicated/privatelink-outbound#do-you-need-this) questions at the top of that page take two minutes and can rule the work out entirely: public targets need nothing, and an internet-facing target can often just allowlist the install's single outbound IP.
### Your CI and browsers reaching the hub
Earthly recommends publishing the install privately, so your CI runners, CLI users, and browsers reach it from your own VPC with nothing exposed to the internet. The alternative is a public hostname behind TLS and token authentication, which needs nothing from you and is the only option when your CI runs on shared hosted runners.
**Start here if that applies to you:** [**PrivateLink to Your Hub**](/install/lunar-hub/dedicated/privatelink-inbound)**.** It covers creating the interface endpoint, the two DNS records that point your install's hostnames at it, and reaching the UI from laptops rather than just from CI.
{% hint style="warning" %}
**Settle the webhook path first.** Your Git platform delivers webhooks to the hub, and it isn't on your runner network, so the endpoint your CI uses won't carry that traffic. A platform inside your own network can deliver through an endpoint of its own, and a cloud-hosted one delivers from the internet, which means that one listener stays public. A vendor-managed single-tenant platform is the case to start early: the private connection is something you request from your vendor, on a timeline you don't control.
{% endhint %}
Not sure it applies? The [Do you need this?](/install/lunar-hub/dedicated/privatelink-inbound#do-you-need-this) questions at the top of that page will settle it, and the deciding factor is usually where your CI runs: self-hosted runners in AWS are the natural fit, while shared hosted runners can't use a private endpoint at all.
## Step 2 — Identify your depositor account
During setup, your secrets (your Git platform credential, the encryption key, and the webhook secret) are written **directly into your dedicated account's** secret store, never through Earthly's systems. They're deposited by assuming a **write-only deposit role** in the dedicated account. Earthly creates that role while provisioning your account, with your depositor principal baked into its trust policy. The trust policy is fixed at that point, which is why your account ID is the one input Earthly needs early.
**Send Earthly the 12-digit ID of the AWS account you will deposit from.** Earthly trusts that account principal (`arn:aws:iam:::root`) plus a deposit-specific ExternalId (included in your coordinates packet).
That does **not** grant everyone in the account access; your IAM administrator still chooses which role or user may call `sts:AssumeRole`. Attach this caller-side policy to the role, user, or permission set your team will use:
```json
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam:::role/-secret-deposit"
}]
}
```
The exact deposit-role ARN for the `Resource` line is also in your coordinates packet. It's fine to prepare the policy with a placeholder and tighten it when the packet arrives.
Notes that save a support round-trip:
* Trusting the account's `:root` ARN is **not** logging in as the AWS root user. The root user cannot assume roles; use a normal IAM or SSO principal.
* Earthly does not trust a specific SSO-generated role ARN, so recreating a permission set does not silently break the deposit trust. Your caller-side policy remains the gate.
* If an SCP or permission boundary blocks cross-account `sts:AssumeRole`, your AWS administrator must allow this one deposit-role ARN.
{% hint style="info" %}
**No AWS account?** Tell Earthly along with your questionnaire answers. When you're ready to deposit, Earthly will mint **one-hour temporary credentials** for the write-only deposit role and deliver them over a secure channel.
{% endhint %}
## Step 3 — Set up your Git platform
Lunar authenticates to your Git platform with a credential that **you** create, on the groups, orgs, and repos it should monitor. Earthly never holds org-admin access, and never handles the credential itself.
[Git Platforms](/install/git-platforms) covers what differs between the two platforms. The Hub-configuration sections of those pages are for self-hosted installs only, since Earthly configures the Hub for you.
{% tabs %}
{% tab title="GitHub" %}
Create a GitHub App and install it on your org.
* Use the [hosted setup tool](https://earthly.dev/lunar/github-app-setup/), or [create it by hand](/install/git-platforms/github#manual-setup-alternative) on GitHub Enterprise Server, or if your security review needs every permission spelled out first. The [permissions it is granted](/install/git-platforms/github#permissions) are listed for that review.
* Set the **webhook URL** from your coordinates packet (`https://hub../webhooks/github`). It's fine that the install isn't live yet.
* Download the App's **private key** (`.pem`). It's deposited in step 4; it never goes to Earthly, in any channel.
* Leave the App's **"Webhook secret" field empty.** Lunar registers and secures its own repository webhooks from inside your install; the App-level webhook carries no traffic.
**Send Earthly:** the App ID, the installation ID, and the org(s) it's installed on. Those are identifiers, not secrets.
{% endtab %}
{% tab title="GitLab" %}
Create a [service account and token](/install/git-platforms/gitlab#create-the-token). On a self-managed or Dedicated instance, one **instance service account** made a Maintainer of every top-level group Lunar should serve gives you a single token for everything. On GitLab.com, create a **group service account** and token on each top-level group instead.
* Give the token the `api` scope and the `Maintainer` or `Owner` role.
* Pick an expiry and set a calendar reminder for it now. GitLab tokens expire on a fixed date, with no overlap period. See [Rotations and changes](#rotations-and-changes).
* Copy the token when GitLab shows it; it is displayed once. It's deposited in step 4 and never goes to Earthly.
* **There is no webhook URL to set, and no webhook secret to paste back.** Lunar registers a webhook on each project itself and generates the signing secret inside your install, so unlike GitHub there's nothing to configure on the GitLab side.
**Send Earthly:** your instance hostname if you're self-managed, and for group tokens the top-level group path each one covers. Those are identifiers, not secrets.
{% hint style="warning" %}
**Self-managed instances must be declared.** Lunar decides whether a host is GitLab from configuration, so if you don't tell Earthly your instance hostname it will be treated as GitHub and every operation against it fails in confusing ways. `gitlab.com` needs no declaration.
{% endhint %}
{% endtab %}
{% endtabs %}
## Step 4 — Deposit your secrets
Run this from a terminal once you have your coordinates packet and your Git platform credential. Expect about 30 minutes end to end. You'll need the **tenant name, region, deposit role ARN, and deposit ExternalId** from the packet. Earthly is glad to join a call if you need help.
{% hint style="info" %}
The deposit ExternalId unlocks only the write-only deposit role. It is not Earthly's deploy ExternalId, and it grants nothing else.
{% endhint %}
Use an AWS profile for a principal carrying the caller-side policy from step 2:
{% tabs %}
{% tab title="GitHub" %}
```bash
AWS_PROFILE= lunar setup bootstrap \
--tenant --region \
--github-app-pem \
--deposit-role-arn \
--external-id
```
{% endtab %}
{% tab title="GitLab" %}
Write the token to a file first, so it never lands in your shell history:
For an **instance service account** token (self-managed or Dedicated), one run covers the whole instance:
```bash
AWS_PROFILE= lunar setup bootstrap \
--tenant --region \
--gitlab-host \
--gitlab-token \
--deposit-role-arn \
--external-id
```
For **group access tokens** (GitLab.com), name the group instead and **repeat once per top-level group** — Lunar keys these tokens by group, so each one is deposited under its own group path:
```bash
AWS_PROFILE= lunar setup bootstrap \
--tenant --region \
--gitlab-group \
--gitlab-token \
--deposit-role-arn \
--external-id
```
Beyond naming the deposit, your instance hostname is configuration, not a secret. Earthly applies it from the identifiers you sent in [step 3](#step-3-set-up-your-git-platform).
{% endtab %}
{% endtabs %}
If Earthly issued one-hour temporary credentials instead (the no-AWS-account path), export the three values in your shell and drop the last two flags; the credentials already *are* the deposit role:
```bash
export AWS_ACCESS_KEY_ID=… AWS_SECRET_ACCESS_KEY=… AWS_SESSION_TOKEN=…
lunar setup bootstrap \
--tenant --region \
--github-app-pem
```
What the command does:
* Generates the **encryption key** and **webhook secret** inside this flow and deposits them write-once. Neither is ever printed — the install consumes them directly.
* Deposits the Git platform credential you supplied: the GitHub App PEM, or the GitLab token.
* Verifies each write from the write response. The deposit role is **write-only by design**: it cannot read the secrets back, and the setup flow never returns them to Earthly.
* Leaves nothing to paste back on either platform: Lunar registers repository and project webhooks itself and manages their signing secrets inside your install.
**If you get** `AccessDenied`, in order of likelihood:
1. Your caller doesn't have `sts:AssumeRole` on the deposit-role ARN.
2. Deposit ExternalId typo; it must match the packet exactly.
3. An SCP or permission boundary in your org blocks `sts:AssumeRole` to accounts outside your organization. Loop in whoever owns your SCPs.
4. On the no-AWS-account path: the one-hour credentials expired. Ask Earthly to mint a fresh set; it takes seconds.
## Go live
Earthly completes the install, verifies it end-to-end, and hands you the **hub access token** over a secure channel. Treat it like a root credential. On an internet-reachable install you also get a **Grafana login**; on a private install the UI has no login and is read-only to anyone who can reach your endpoint.
Then, on your side:
**Load your workload secrets**: the API keys your catalogers, collectors, and policies need. These go straight to your hub via the CLI, never through Earthly's systems:
```bash
lunar secret set DATADOG_API_KEY --scope collector # value read from stdin
```
**Finish DNS, if you delegated a subdomain.** Add the NS records Earthly provides to hand off the zone. Earthly then manages every record and the TLS certificate under it.
**Complete your hub-access step, if you chose PrivateLink.** Create the inbound endpoint and coordinate with Earthly, usually via your networking team. Over the internet there's nothing to do.
**Confirm private connectivity, if you set it up in step 1.** Earthly runs a verification pass from a real Lunar workload (hostname resolution, TLS with hostname verification, an authenticated application request) and only points your install at the internal hostname once all of it passes.
## Rotations and changes
**GitHub App PEM.** Re-run [step 4](#step-4-deposit-your-secrets) with the new file. The encryption key and webhook secret will not rotate, but the PEM will.
**GitLab token.** GitLab tokens carry a fixed expiry, and there is no overlap period where old and new both work, so replacing one is a cutover rather than a rollover. Create the replacement in GitLab, re-run [step 4](#step-4-deposit-your-secrets) with it ahead of the expiry date, then revoke the old one. See [expiry and rotation](/install/git-platforms/gitlab#expiry-and-rotation).
{% hint style="warning" %}
If a GitLab token lapses, Lunar stops posting results and stops reacting to webhooks for the groups it served. Because the token is read at startup, nothing fails loudly to tell you. Set the calendar reminder when you create the token, not later.
{% endhint %}
If you used the AWS-less fallback, contact Earthly before any credential rotation; fresh one-hour credentials are minted for the re-run and nothing else changes.
**Adding or removing an internal target.** Publish the new endpoint service following [PrivateLink to Your Internal Systems](/install/lunar-hub/dedicated/privatelink-outbound) and send Earthly the same six values. Earthly makes a small, reviewed change on its side, with no downtime for your install.
# PrivateLink to Your Hub
Reach your Lunar Dedicated hub over a private AWS PrivateLink path from your own VPC, by creating one interface endpoint and two DNS records.
Your CI runners, CLI users, and browsers all need to reach your Lunar Dedicated install, and PrivateLink is the recommended way to let them. The hub API and the UI answer only inside the networks you connect to them, and nothing is published to the internet. The alternative, a public hostname behind TLS and token authentication, is there for teams whose CI runs on shared hosted runners and so cannot reach a private endpoint.
This page is the setup guide for that path. It's written for whoever runs your AWS networking. You can forward it on its own.
{% hint style="info" %}
This page covers reaching the hub **in**. Lunar reaching **out** to your internal systems (a self-managed Git platform, an internal registry or API) is a separate, independent setup, covered in [PrivateLink to Your Internal Systems](/install/lunar-hub/dedicated/privatelink-outbound). Many installs need both.
{% endhint %}
## Do you need this?
Three questions to decide.
**1. Does your CI run in a network you control?** PrivateLink reaches your install from a VPC, so self-hosted runners in AWS are the natural fit. Shared hosted runners (github.com's, gitlab.com's) aren't in your VPC and can't use the endpoint, so an install that serves those still needs the internet route for whatever they call.
**2. How will your Git platform deliver webhooks?** Your Git platform calls the hub every time someone pushes, and it isn't on your runner network, so the endpoint you're about to create won't carry its traffic. This is the part most likely to have lead time, so settle it first: see [Decide the webhook path](#decide-the-webhook-path).
**3. How will developers reach the UI?** The UI is Grafana, on your install's apex hostname, and a private install resolves only inside the VPCs you connect to it. If your developers already work behind a VPN, Direct Connect, or Transit Gateway that reaches the VPC, PrivateLink covers them once you add DNS forwarding and a route ([step 5](#step-5-reach-the-install-from-elsewhere)). If they don't, you would have to build that path first, and an install on the internet, where Grafana sits behind a login, may be the better trade.
## How it works
Earthly publishes your install as an **endpoint service**. You create a matching **interface endpoint** in your VPC, plus two DNS records so your install's normal hostnames resolve to it.
```mermaid
flowchart LR
subgraph Customer["Your AWS account"]
CI["CI runners · CLI users
browsers"]
EP["Interface VPC endpoint
(you create)"]
CI --> EP
end
subgraph Dedicated["Lunar Dedicated account (Earthly-managed)"]
ES["Endpoint service
(Earthly creates)"]
LB["Internal proxies"]
HUB["Lunar Hub · Grafana"]
ES --> LB --> HUB
end
EP -- "AWS PrivateLink (one-way, you initiate)" --> ES
```
Three properties are worth knowing up front, because they answer most security-review questions:
* **The connection is one-way.** Your side initiates every session. Nothing in the install can initiate a connection back into your VPC.
* **Neither side learns the other's addresses.** PrivateLink does not join the networks, add routes, or expose either CIDR range. Overlapping address ranges are fine.
* **You reach only the service Earthly publishes.** Not the VPC it lives in, not anything else in Earthly's account.
You own and pay for the endpoint, the hosted zone, and any resolver infrastructure in [step 5](#step-5-reach-the-install-from-elsewhere).
{% hint style="warning" %}
**PrivateLink is not authentication.** It controls which AWS account may *create* an endpoint; it does not identify individual workloads or requests. The hub API still requires its bearer token.
**The UI has no login on a private install.** Grafana is read-only to anyone who can reach the endpoint, so the endpoint's security group is what limits who sees it. Scope it to the systems and people you intend, and treat reaching the endpoint as equivalent to being able to read the UI.
Lunar Dedicated does not support mutual TLS today.
{% endhint %}
## Checklist
If you've consumed endpoint services before, this is all you need. The [Prefer Terraform?](#prefer-terraform) section has the resource definitions.
1. Decide the [webhook path](#decide-the-webhook-path). Most likely to have lead time, so start it first.
2. Interface endpoint against Earthly's service name, in subnets whose **zone IDs** Earthly supports.
3. **Private DNS disabled** on that endpoint. Leaving it on fails endpoint creation.
4. Endpoint security group: inbound TCP **443** from your systems.
5. Private hosted zone for your install's domain, associated with that VPC.
6. Two **alias A records** in it, apex and wildcard, both targeting the endpoint's **regional** DNS name.
7. [Confirm it works](#confirm-it-works) and tell Earthly when you're good to go.
## What you need from Earthly first
Earthly builds its side first, so you'll receive these before you start:
| Value | Example |
| ----------------------------------- | --------------------------------------------------------- |
| **Region** | `us-east-2` |
| **Endpoint service name** | `com.amazonaws.vpce.us-east-2.vpce-svc-0123456789abcdef0` |
| **Supported availability zone IDs** | `use2-az1`, `use2-az2` |
| **Your install's domain** | `you.dedicated.earthly.dev` |
| **Hub hostname** | `hub.you.dedicated.earthly.dev` |
| **Port** | TCP 443 |
Lunar Dedicated supports same-region endpoints only, so build everything here in the install's region.
Earthly also allowlists your AWS account beforehand, so your endpoint connects without an approval step. If your security team would rather Earthly allowlist one specific IAM role, send its ARN. It must be **pathless**, because AWS rejects principal ARNs containing a path on endpoint services.
## Four names that look alike
Four names come up below. Three of them are `vpce` strings that are easy to mix up, and the fourth is what your CI actually calls.
| Name | Looks like | Used for |
| ------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Endpoint service name** | `com.amazonaws.vpce.us-east-2.vpce-svc-0123456789abcdef0` | Earthly gives you this; it's the input when you create the endpoint |
| **Endpoint ID** | `vpce-0123456789abcdef0` | your endpoint, once created |
| **Endpoint regional DNS name** | `vpce-0123456789abcdef0-a1b2c3d4.vpce-svc-0123456789abcdef0.us-east-2.vpce.amazonaws.com` | the target your DNS records alias to |
| **Your install's hostnames** | `you.dedicated.earthly.dev`, `hub.you.dedicated.earthly.dev` | what your CI and browsers actually call |
## Decide the webhook path
Your Git platform delivers webhooks to the hub. Without them, pushes don't trigger anything and pull/merge-request status checks never post. Your Git platform isn't on your runner network, so **the endpoint you're about to create won't carry that traffic.**
Which case applies depends on where your platform runs:
* **A cloud-hosted Git platform** (github.com, gitlab.com, etc.) delivers from the public internet and can't use PrivateLink. Earthly can leave *just* the webhook listener on the internet while everything else stays private. Webhooks are authenticated by a signed secret shared with the platform.
* **A self-managed Git platform in your own network** can usually reach the hub through the same endpoint, or through a second one in whichever VPC it runs in. The steps are the same either way.
* **A managed single-tenant Git platform** runs in your vendor's account. Some vendors offer an outbound private connection to a customer-published endpoint service; if yours does, request it and send Earthly the principal it gives you. **This is usually a support ticket with a lead time you don't control**, so raise it as soon as you have the endpoint service name. It runs in parallel with everything else here.
## Step 1 — Create the interface endpoint
In your runner VPC: **VPC → Endpoints → Create endpoint → Other endpoint services**, paste Earthly's service name, verify it, then choose subnets.
**Subnets must be in the zone IDs Earthly listed.** AWS maps zone *names* like `us-east-2a` to different physical zones in different accounts, so a name means nothing across an account boundary:
```bash
aws ec2 describe-availability-zones \
--query 'AvailabilityZones[].[ZoneName,ZoneId]' --output table
```
Use two of the supported zones for redundancy; one is enough if that's all you have. If none of your subnets land in a supported zone, talk to Earthly before creating anything, because either side may need to add a subnet in a shared zone.
This constrains **placement only**: workloads anywhere in the VPC reach the endpoint across zones by ordinary VPC routing.
Attach a security group allowing inbound **TCP 443** from your runners.
## Step 2 — Turn private DNS off
Leave **Enable DNS name** unchecked (`private_dns_enabled = false` in Terraform).
Some tools default it on, and endpoint creation then fails with:
```
Private DNS can't be enabled because the service ... does not provide a private DNS name.
```
Enabling it asks AWS to resolve a hostname the *provider* has verified, and Earthly deliberately publishes none. Handling DNS on your side is what lets a single endpoint serve every hostname your install has today or gains later.
## Step 3 — Create the private hosted zone
Create a **private hosted zone** named after your install's domain (`you.dedicated.earthly.dev`), associated with the VPC holding the endpoint. That zone is dedicated to this install, so shadowing all of it is safe.
Add **two alias A records** with the same target. You need both, because a wildcard doesn't match its own apex:
| Record | Serves |
| ----------------------------- | -------------------------- |
| `you.dedicated.earthly.dev` | the Grafana UI |
| `*.you.dedicated.earthly.dev` | `hub.` and everything else |
**The alias target is your endpoint's regional DNS name**, the third row of [Four names that look alike](#four-names-that-look-alike). Find it on the endpoint's **Details** tab under **DNS names**, or:
```bash
aws ec2 describe-vpc-endpoints --vpc-endpoint-ids vpce-0123456789abcdef0 \
--query 'VpcEndpoints[0].DnsEntries' --output table
```
{% hint style="warning" %}
**Two ways to get the target wrong.**
Pick the **regional** entry, not one of the per-zone variants ending `...-us-east-2a...`. A zonal target pins all your traffic to one availability zone.
And alias to the **endpoint**, not to the hostname you're creating the record for, and not to Earthly's endpoint *service* name.
{% endhint %}
Use alias records rather than CNAMEs, because a CNAME isn't valid at a zone apex.
## Step 4 — Point your CI at the hub
Nothing about Lunar's configuration changes for a private install:
```bash
LUNAR_HUB_HOST=hub.you.dedicated.earthly.dev
LUNAR_HUB_TOKEN=...
```
The gRPC API and the HTTP endpoints share port 443, so only one port ever needs to be open. Authentication is the same bearer token you'd use over the internet.
## Step 5 — Reach the install from elsewhere
**Another VPC**: repeat steps 1 to 3 in it. Each VPC gets its own endpoint and its own copy of the two records; the hostnames stay the same everywhere.
**Laptops on the corporate network** need two separate things, and it's easy to do only the first:
1. **DNS**: forward `you.dedicated.earthly.dev` into the VPC, typically via a Route 53 Resolver inbound endpoint plus a conditional forwarder on your corporate resolvers.
2. **Network**: a route from the corporate network to the endpoint's addresses (VPN, Direct Connect, or Transit Gateway), and the endpoint's security group must allow that source.
Resolver forwarding only makes the name resolve. Do the first without the second and the browser gets the right address with no way to reach it.
## Prefer Terraform?
Steps 1 to 3 are five resources:
```hcl
resource "aws_security_group" "lunar_hub" {
name = "lunar-hub-endpoint"
vpc_id = var.vpc_id
}
resource "aws_vpc_security_group_ingress_rule" "lunar_hub_tls" {
security_group_id = aws_security_group.lunar_hub.id
ip_protocol = "tcp"
from_port = 443
to_port = 443
cidr_ipv4 = var.runner_cidr # or referenced_security_group_id
}
resource "aws_vpc_endpoint" "lunar_hub" {
vpc_id = var.vpc_id
vpc_endpoint_type = "Interface"
service_name = "com.amazonaws.vpce.us-east-2.vpce-svc-0123456789abcdef0"
subnet_ids = var.subnet_ids # subnets in the zone IDs Earthly supports
security_group_ids = [aws_security_group.lunar_hub.id]
# Required: Earthly publishes no verified private DNS name. See step 2.
private_dns_enabled = false
}
resource "aws_route53_zone" "lunar" {
name = "you.dedicated.earthly.dev"
vpc {
vpc_id = var.vpc_id
}
}
resource "aws_route53_record" "lunar" {
for_each = toset(["you.dedicated.earthly.dev", "*.you.dedicated.earthly.dev"])
zone_id = aws_route53_zone.lunar.zone_id
name = each.value
type = "A"
alias {
name = aws_vpc_endpoint.lunar_hub.dns_entry[0].dns_name
zone_id = aws_vpc_endpoint.lunar_hub.dns_entry[0].hosted_zone_id
evaluate_target_health = false
}
}
```
{% hint style="warning" %}
**AWS doesn't document the order of `dns_entry`,** so `[0]` being the regional entry is a convention rather than a guarantee. Output it and check the value has no availability zone in it before relying on this in production.
{% endhint %}
## Confirm it works
From a host inside the VPC:
```bash
getent hosts hub.you.dedicated.earthly.dev
curl -sS https://you.dedicated.earthly.dev/api/health
```
The first should return the endpoint's **private** addresses; public addresses mean your hosted zone isn't answering and traffic would be leaving your network. The second should return JSON.
{% hint style="info" %}
**An endpoint reaching `available` proves less than it sounds.** It means the PrivateLink connection was established, not that DNS is right and not that anything behind it works. The two commands above are the real check.
{% endhint %}
Then tell Earthly three things, so the install can be verified end to end from both sides:
* **Your endpoint ID**, so Earthly can confirm the connection is accepted and healthy rather than pending or rejected.
* **Which zone IDs you placed it in**, which is what Earthly checks against if connectivity works from some subnets but not others.
* **Which webhook case applies**, plus any principal to allowlist for a vendor-managed connection.
## Troubleshooting
**Endpoint creation fails on private DNS.** `Private DNS can't be enabled because the service ... does not provide a private DNS name` means the flag is on. See [step 2](#step-2-turn-private-dns-off).
**Endpoint creation fails on availability zones.** Your subnets aren't in a zone the service supports. Compare zone **IDs**, not names.
**Endpoint creation is rejected outright.** Your account isn't allowlisted, or a different one is. An unlisted account can't see the service at all, so the failure never reaches Earthly's side. Confirm the account ID.
**The endpoint sits in `pendingAcceptance`.** Earthly's service accepts allowlisted connections automatically, so tell Earthly rather than waiting.
**Hostnames don't resolve, or resolve to public addresses.** The hosted zone isn't associated with the VPC you're testing from, or the records are missing. Test from inside that VPC; laptops need [step 5](#step-5-reach-the-install-from-elsewhere).
**Hostnames resolve but connections hang.** Check the endpoint's security group allows TCP 443 from the client.
**Only the apex works, or only `hub.` works.** Only one of the two records exists, and both are needed.
**Traffic works from one availability zone only.** The alias targets a zonal endpoint DNS name rather than the regional one. See [step 3](#step-3-create-the-private-hosted-zone).
**A deeper hostname resolves but fails TLS.** DNS wildcards match at any depth, so `a.b.you.dedicated.earthly.dev` resolves via your wildcard record, but the install's certificate only covers one level. Lunar only ever uses single-label names like `hub.`, so this only appears if something is calling a name Lunar doesn't publish.
**Everything works except webhooks.** Your Git platform reaches the hub by a different path from your runners. See [Decide the webhook path](#decide-the-webhook-path).
# PrivateLink to Your Systems
Give your Lunar Dedicated install a private path to internal systems (an internal Git server, registry, or API) by publishing them as an AWS PrivateLink endpoint service.
A Lunar Dedicated install reaches outwards to the systems it works with. It calls your **Git platform** to read repositories and post results, and its collectors, catalogers, and policies reach whatever they gather data from, such as registries, ticketing systems, and internal APIs. When one of those isn't reachable from the public internet, Lunar needs a private path to it.
This page is the setup guide for that path. It's written for whoever runs your AWS networking. You can forward it on its own.
{% hint style="info" %}
This page covers Lunar reaching **out** to your systems. Reaching the Lunar hub **in** from your CI and browsers is a separate, independent setup, covered in [PrivateLink to Your Hub](/install/lunar-hub/dedicated/privatelink-inbound), which is the recommended way to do it. See the [Overview](/install/lunar-hub/dedicated/overview#how-you-connect) for the alternatives.
{% endhint %}
{% hint style="warning" %}
**A self-managed Git platform needs both directions.** If your GitHub Enterprise Server or GitLab instance only resolves inside your network, it is a target for this page: Lunar has to reach it to read repositories and post results. Separately, your instance has to deliver **webhooks** to the hub, which this page does not cover. If it can reach the internet, it delivers to your install's public webhook listener; if it cannot, it needs a private path in — see [Decide the webhook path](/install/lunar-hub/dedicated/privatelink-inbound#decide-the-webhook-path).
{% endhint %}
## Do you need this?
Each of these can rule the work out, so answer them before you build anything.
**1. Is the target actually unreachable from the internet?** Your Lunar install has a single, stable outbound IP address. If your service is internet-facing and you can allowlist one IP, that's far less work than everything below. Ask Earthly for the address.
**2. Can you publish TXT records on a publicly-resolvable domain?** AWS requires proof of domain ownership before it will attach a hostname to an endpoint service. Verification is scoped to the *parent* domain, so a name under `example.com` works for any subdomain. If your internal hostname sits under a suffix you can't prove ownership of (something like `.corp` or `.internal` with no public zone), tell Earthly, because there's a fallback for that case (Earthly overrides DNS inside the install instead) and it changes what you build here.
**3. Can the service present a publicly-trusted TLS certificate?** Lunar connects with hostname verification on, so the certificate must be valid for the hostname in question 2 *and* trusted by Lunar's workloads.
If you control the public zone from question 2, you can almost certainly get a public certificate for this name: DNS-01 validation only needs a TXT record, so the name never has to resolve publicly. Terminating TLS at the load balancer with an ACM certificate works the same way.
If the service can only present a certificate from your **internal** CA, tell Earthly. We'll need your CA's root and intermediate **certificates** (the public ones, never a private key) to add to the trust store Lunar's workloads use. Flag it too if your CA's revocation endpoints (CRL or OCSP) are only reachable inside your network, since Lunar won't be able to reach them.
**4. How many distinct hostnames does Lunar need to reach?** Not systems; **hostnames**. Remember to count your Git platform if it's self-managed and internal. An endpoint service can carry exactly one private DNS name, though that name may be a wildcard (`*.internal.example.com`). Three hostnames means three endpoint services, a gateway doing path-based routing under a single hostname, or a wildcard name in front of a gateway that routes by hostname.
## How it works
You publish your internal service as an **endpoint service**. Earthly creates a matching **interface endpoint** inside the Lunar install's VPC. Lunar then reaches your service by its normal hostname, over a private AWS path.
```mermaid
flowchart LR
subgraph Dedicated["Lunar Dedicated account (Earthly-managed)"]
W["Lunar Hub · collector
and policy workloads"]
EP["Interface VPC endpoint
(Earthly creates)"]
W --> EP
end
subgraph Customer["Your AWS account"]
ES["Endpoint service
(you create)"]
NLB["Internal Network Load Balancer
(you create)"]
SVC["Your internal service"]
ES --> NLB --> SVC
end
EP -- "AWS PrivateLink — one-way, Lunar initiates" --> ES
```
Three properties are worth knowing up front, because they answer most security-review questions:
* **The connection is one-way.** Lunar initiates every session. Nothing in your account can initiate a connection back through it.
* **Neither side learns the other's addresses.** PrivateLink does not join the networks, add routes, or expose either CIDR range. Overlapping address ranges are fine.
* **Lunar can reach only the service you publish.** Not the VPC it lives in, not anything else in your account.
{% hint style="warning" %}
**PrivateLink is not authentication.** It's a private network path, nothing more. TLS and your service's normal credentials remain fully in force, exactly as if Lunar were calling over the internet.
{% endhint %}
## Checklist
If you've published endpoint services before, this is all you need. The [Prefer Terraform?](#prefer-terraform) section has the resource definition.
1. Internal NLB in front of the service, targets healthy.
2. Endpoint service backed by that NLB.
3. Allowed principal: `arn:aws:iam:::root` (Earthly provides the ID).
4. Acceptance: **automatic**. See [step 4](#step-4-choose-automatic-or-manual-acceptance) before choosing manual; it requires extra steps.
5. Private DNS name: your service's real TLS hostname. Publish the TXT record, wait for `verified`.
6. Send Earthly the values in [What to send back](#step-6-what-to-send-back).
Three details that are easy to miss:
* **Each endpoint service gets its own TXT verification name and value**, so an already-verified domain does not carry over from another service.
* The private DNS name must be the hostname on your service's TLS certificate, or Lunar's requests will fail hostname verification. If that certificate comes from an internal CA rather than a public one, Earthly needs your CA certificates too.
* **Availability zones must be exchanged as zone IDs, not zone names** (see [step 6](#step-6-what-to-send-back)).
## What you need from Earthly first
You need two values from Earthly. The **region** is fixed per install and agreed up front; whoever forwarded you this page will have it. Everything you build here must be in the same region as the install.
The other is the **dedicated account ID**, used for the allowed principal in [step 3](#step-3-allow-earthlys-dedicated-account). It's needed at just that one step, so if you don't have it yet, start building anyway and slot it in when it arrives.
## Step 1 — Put the service behind an internal Network Load Balancer
An endpoint service can only be backed by a Network Load Balancer, so the service needs one in front of it.
* Scheme: **internal**. PrivateLink reaches an internal NLB fine, and an internet-facing one would expose the service publicly, defeating the point.
* Add a TCP listener on the port Lunar will use: **443** unless you tell Earthly otherwise.
* Register your service as a target and **confirm the targets are healthy** before continuing.
An unhealthy target group produces a connection that looks fine on both sides and still refuses traffic. The endpoint will happily reach `Available` with a completely broken backend.
Note the availability zones your NLB is in, as **zone IDs** (`euw2-az1`) rather than zone names (`eu-west-2a`), because names don't mean the same thing in Earthly's account. Endpoint services are only reachable in the zones their load balancer covers, and Earthly's endpoint has to land in a zone you support. You'll send these in [step 6](#step-6-what-to-send-back).
## Step 2 — Create the endpoint service
In the AWS console, go to **VPC → Endpoint services → Create endpoint service**. Not the load balancer screens; this is its own top-level resource.
* Load balancer type: **Network**
* Select the NLB from step 1
* **Require acceptance for endpoint**: the console asks now; automatic acceptance (box unchecked) is recommended
{% hint style="warning" %}
Requiring manual acceptance delays the connection and forces a two-step setup on Earthly's side, so read [step 4](#step-4-choose-automatic-or-manual-acceptance) before checking that box.
{% endhint %}
AWS generates a service name that looks like:
```
com.amazonaws.vpce..vpce-svc-0123456789abcdef0
```
That string is the value Earthly actually uses to connect. Keep it.
## Step 3 — Allow Earthly's dedicated account
On the endpoint service, open **Allow principals** and add:
```
arn:aws:iam:::root
```
This permits principals in that one account to *request* a connection to this one service. It grants no IAM credentials, no assumable role, and no access to anything else in your account. A request from any other account is rejected by AWS before it ever appears in your console.
{% hint style="warning" %}
**You may see a second, similar-looking ARN during Lunar onboarding.** Setting up the install also involves an IAM role that *your* side assumes to deposit secrets. That role trusts your account and uses role assumption with an ExternalId (covered in [Setup](/install/lunar-hub/dedicated/setup#step-2-identify-your-depositor-account)). This allowlist entry is not that: it involves no role assumption at all, only permission to request a PrivateLink connection.
{% endhint %}
## Step 4 — Choose automatic or manual acceptance
**Automatic acceptance is strongly recommended.** Earthly's endpoint connects as soon as it's created, and private DNS is configured in the same step. Your access control is the allowlist from step 3, which you've already set; automatic acceptance widens nothing.
**Manual acceptance** adds a human approval for each connection. Someone on your side approves it at **VPC → Endpoint services → your service → Endpoint connections**, selects the endpoint ID Earthly sends, and chooses **Accept endpoint connection request**. The CLI equivalent is `aws ec2 accept-vpc-endpoint-connections`. It's a single approval, with nothing to configure.
{% hint style="warning" %}
**Manual acceptance costs more than one click.** AWS will not enable private DNS on an endpoint whose connection hasn't been accepted yet. So setup on Earthly's side happens in two steps: create the endpoint, wait for your approval, then make a second change to turn on private DNS. Until that second change lands, your hostname doesn't resolve inside the install.
Choose manual only if your process genuinely requires a named approver per connection. If it does, tell Earthly at [step 6](#step-6-what-to-send-back) so the second step is planned rather than discovered.
{% endhint %}
## Step 5 — Associate and verify the private DNS name
This step is what lets Lunar call your service by its real hostname, with working TLS. Skipping it means Lunar can only reach an AWS-generated hostname that your certificate won't match.
**5a. Associate the name.** On the endpoint service, set **private DNS name** to your service's canonical hostname: the name on its TLS certificate, for example `service.internal.example.com`.
Use a fully-qualified name. A bare single-label name (just `gitlab`) will not work.
**5b. Publish the verification record.** AWS returns a TXT record name and value. Find them under **Domain verification name** and **Domain verification value** on the service's **Details** tab, or:
```bash
aws ec2 describe-vpc-endpoint-service-configurations \
--service-ids vpce-svc-0123456789abcdef0 \
--query 'ServiceConfigurations[*].PrivateDnsNameConfiguration'
```
Create that TXT record in the **public** DNS zone for the domain:
| Name | Type | Value |
| ------------------------------- | ---- | ----------------------- |
| `_a1b2c3d4e5f6g7h8.example.com` | TXT | `vpce:AbCdEf0123456789` |
{% hint style="info" %}
**An already-verified domain does not carry over.** Each endpoint service gets its own verification name and value, so if you've published private DNS names for other services on this domain you still need a new TXT record for this one.
{% endhint %}
**5c. Wait for verification.** Check **Domain verification status** on the Details tab. If it stays pending, use **Actions → Verify domain ownership for private DNS name** to retry. DNS changes can take up to 48 hours to propagate, though it's usually much faster.
**Do not tell Earthly you're ready until the status reads `verified`.** Earthly's endpoint is created with private DNS enabled, and that request is rejected against a service whose name isn't verified yet.
## Prefer Terraform?
Steps 2–5 are one resource. This is the recommended minimal shape if your networking is Terraform-managed:
```hcl
resource "aws_vpc_endpoint_service" "lunar" {
acceptance_required = false
network_load_balancer_arns = [aws_lb.internal.arn]
private_dns_name = "service.internal.example.com"
allowed_principals = [
"arn:aws:iam:::root",
]
}
```
The TXT record from step 5 is still published separately, through your DNS provider or an `aws_route53_record` if the zone lives in Route53.
## Step 6 — What to send back
Send Earthly these six values:
| Value | Example |
| ----------------------------------- | --------------------------------------------------------- |
| **Endpoint service name** | `com.amazonaws.vpce.eu-west-2.vpce-svc-0123456789abcdef0` |
| **Verified private DNS name** | `service.internal.example.com` |
| **TCP port** | `443` |
| **Region** | `eu-west-2` |
| **Acceptance** | automatic, or manual |
| **Supported availability zone IDs** | `euw2-az1`, `euw2-az2` |
If you flagged an internal CA in question 3, include your CA certificates as well. Earthly needs nothing further to create its side of the connection.
{% hint style="warning" %}
**Send zone IDs, not zone names.** AWS maps zone *names* like `eu-west-2a` to different physical zones in different accounts, so a name is meaningless across an account boundary. Zone **IDs** like `euw2-az1` are stable everywhere. Get them with:
```bash
aws ec2 describe-availability-zones \
--query 'AvailabilityZones[].[ZoneName,ZoneId]' --output table
```
Send the IDs for the zones your load balancer covers.
{% endhint %}
## What happens next
From your six values, Earthly creates the interface endpoint, plus a security group that allows only the port you specified, and only from Lunar's workloads.
If you chose manual acceptance, Earthly sends you the endpoint ID at this point and waits for your approval, then makes a second change to enable private DNS.
An endpoint reaching `Available` proves less than it sounds: it means the PrivateLink connection was established, not that anything behind it works. So Earthly checks two things from a real Lunar workload:
* **The hostname resolves to the endpoint's private addresses.** This is what proves traffic is taking the private path, rather than resolving to a public address and quietly bypassing the endpoint.
* **TLS completes with hostname verification enabled.** A successful handshake exercises the whole path, so it also confirms your load balancer targets are healthy and your certificate covers the name.
Earthly then runs a collection against your service and confirms the data lands. It's the same end-to-end check every install gets, private or not.
## How DNS resolves
Worth understanding if you're reviewing this, because nothing about it is visible in your account.
When Earthly creates the interface endpoint, AWS reads the verified private DNS name from your endpoint service and creates a hidden, AWS-managed private hosted zone associated with the Lunar VPC. That zone maps your hostname to the endpoint's network interfaces.
The consequence is split-horizon resolution: inside the Lunar install, `service.internal.example.com` resolves to the private endpoint. Everywhere else in the world, it resolves however it always did. Lunar's configuration contains an ordinary hostname and an ordinary HTTPS URL; nothing in Lunar knows PrivateLink is involved.
{% hint style="warning" %}
**Don't remove the TXT record afterwards.** If domain verification later lapses, AWS denies *new* connection requests while existing connections keep working. The install carries on fine and the problem surfaces only when the endpoint is next recreated, potentially months later during an unrelated maintenance window.
{% endhint %}
## Troubleshooting
**Earthly's endpoint is stuck in `PendingAcceptance`.** Manual acceptance is enabled and nobody has approved the connection. Approve it under **Endpoint connections** on your service.
**Earthly reports the connection request failed outright.** Usually, the allowed principal is incorrect. Check the account ID in step 3 matches the one Earthly gave you exactly. An unlisted account can't see the service at all, so the failure happens on Earthly's side and never reaches your console.
**Endpoint creation fails with a private DNS error.** An error saying private DNS requires an accepted connection means manual acceptance is on. Approve the pending connection; Earthly completes the second step. See [step 4](#step-4-choose-automatic-or-manual-acceptance).
**Endpoint creation fails on availability zones.** Earthly's endpoint has to be placed in zones your service supports. Send the zone **IDs** from step 6 (zone names don't translate across accounts) and Earthly will constrain placement.
**The endpoint is `Available` but requests fail or hang.** Check your NLB target group health first. Endpoint state reflects the PrivateLink connection, not your backend.
**Requests connect but TLS fails.** The hostname Lunar is calling isn't covered by your certificate's subject alternative names. The private DNS name in step 5 must be a name the certificate actually presents.
**Domain verification won't complete.** Check whether your DNS provider allows underscores in record names; if not, you can omit the AWS-supplied prefix and use the bare domain. Also check that your provider hasn't appended the domain a second time, or lowercased the value; AWS matches it exactly.
# Git Platforms
What Lunar supports on GitHub and GitLab — identity, webhooks, policy results, merge gating, and CI — and where the setup instructions for each Git platform live.
Lunar integrates with **GitHub** (github.com and GitHub Enterprise Server) and **GitLab** (gitlab.com and self-managed instances). One Hub can serve both at once, and each repository is routed by its host.
Most of Lunar works identically on either Git platform: components, domains, collectors, policies, catalogers, the SQL API, and the Grafana dashboards behave the same on both. The differences are concentrated in a few places, and this page is the summary — read it before planning an install so nothing on the list below is a surprise later.
Creating the credential is platform-specific, and lives on each platform's page:
* [**GitHub**](/install/git-platforms/github) — create the GitHub App the Hub authenticates as.
* [**GitLab**](/install/git-platforms/gitlab) — create the service account and its token, and set up the merge gate on Ultimate.
Everything after that is the ordinary install: [Self hosted](/install/lunar-hub/self-hosted) or [Dedicated](/install/lunar-hub/dedicated), each of which calls out the GitHub and GitLab variants inline where they diverge.
## Capability summary
| Capability | GitHub | GitLab |
| ------------------------------ | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Repository identity | `github.com/org/repo` | `gitlab.com/group/project`, including nested subgroups |
| Credentials | [GitHub App](/install/git-platforms/github) | [Service account token](/install/git-platforms/gitlab) |
| Webhook ingestion | Push, pull request, workflow run, PR comments | Push, merge request, MR comments |
| Webhook registration | Automatic, per repository | Automatic, per project |
| Results on pull/merge requests | Check run + PR comment | Commit status (GitLab Free/Premium) or external status check (GitLab Ultimate) + MR comment |
| Results on the default branch | Check run + Grafana dashboards | Commit status + Grafana dashboards; project badges |
| Merge gating | [Mark Lunar's check required in branch protection](/install/git-platforms/github#blocking-merges) | [Provisioned automatically on Ultimate](/install/git-platforms/gitlab#merge-gate); on Free and Premium, enable **Pipelines must succeed** yourself |
| Comment-driven bypass | [`/lunar bypass:` on the PR](/docs/pr-comments) | [`/lunar bypass:` on the MR](/docs/pr-comments), on every tier |
| Config sync | [GitHub Action](/install/lunar-hub/self-hosted/sync-config#github-actions) or CLI | [`.gitlab-ci.yml` job](/install/lunar-hub/self-hosted/sync-config#gitlab-ci) running the CLI |
Which CI systems Lunar traces is a separate question from which Git platform you are on — see [Lunar CI Tracer](/install/ci-tracer).
## What the differences mean in practice
### Merge gating depends on your GitLab tier
On GitHub, Lunar posts a check run and you decide whether to make it required in branch protection. See [blocking merges](/install/git-platforms/github#blocking-merges). A blocked pull request can be overridden with a [`/lunar bypass:` comment](/docs/pr-comments).
On GitLab **Ultimate**, Lunar blocks merge requests whose gating policies do not pass, and provisions the necessary project settings itself — see the [merge gate](/install/git-platforms/gitlab#merge-gate) for what it changes and how to override a block.
On GitLab **Free** and **Premium**, Lunar posts a commit status instead. That can still gate merges, but you turn it on per project with **Pipelines must succeed**, and it gates on the whole pipeline rather than on Lunar as a named requirement. The [`/lunar bypass:` comment](/docs/pr-comments) works here too, against the commit status that setting reads.
### Self-managed hosts must be configured
GitHub Enterprise Server and self-managed GitLab are both supported, but a self-managed GitLab host is only recognized as GitLab if you list it in your credentials configuration. See [GitLab](/install/git-platforms/gitlab).
## Running GitHub and GitLab together
One Hub can serve both. Configure the GitHub App as usual and add `HUB_GITLAB_TOKENS` alongside it; each repository is routed by its host. Neither platform is mandatory to the Hub, which starts as long as at least one is configured.
The Helm chart has not caught up on that last point: its template guard still requires the GitHub App values, so a self-hosted chart install carries a GitHub App configuration even when every component lives on GitLab. See [install Step 4](/install/lunar-hub/self-hosted/install-walkthrough#git-platform-credentials); dedicated `hub.gitlab.*` values are planned.
## Next steps
* [GitHub](/install/git-platforms/github) — GitHub App setup.
* [GitLab](/install/git-platforms/gitlab) — token setup, Hub configuration, and the merge gate.
Then carry the credential into your install:
* [Self hosted](/install/lunar-hub/self-hosted) — [Prerequisites](/install/lunar-hub/self-hosted/prerequisites) and the [install walkthrough](/install/lunar-hub/self-hosted/install-walkthrough).
* [Dedicated](/install/lunar-hub/dedicated) — Earthly configures the Hub; you [deposit the credential](/install/lunar-hub/dedicated/setup#step-4-deposit-your-secrets) into your install.
# GitHub
Set up GitHub for Lunar. Create the GitHub App the Hub authenticates as, review the permissions it holds, serve several organizations from one Hub, and block merges on Lunar's check run.
The Hub authenticates with a **GitHub App** installed on your organization. The App vends short-lived installation tokens, which Lunar uses to read repositories and post results, so no long-lived credential is stored anywhere.
You create the App; Lunar never creates one on your behalf. Either flow below produces the same App.
This page covers the GitHub side only. The install steps that consume it are in [Prerequisites → Step 5](/install/lunar-hub/self-hosted/prerequisites#step-5-connect-your-git-platform) for self-hosted, or the [Dedicated](/install/lunar-hub/dedicated/setup) setup steps.
## Permissions
The App ends up with these permissions however you create it: the setup tool sets them for you, and the [manual flow](#manual-setup-alternative) has you set them by hand. This is the list to hand a security reviewer.
| 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; also covers the role check behind the [bypass comment](/docs/pr-comments#lunar-bypass) |
| `pull_requests` | write | Post PR comments and statuses |
| `repository_hooks` | write | Auto-register per-repo webhooks |
| `organization_hooks` | write | Auto-register organization-level webhooks |
**Events:** `push`, `pull_request`, `workflow_run`, `issue_comment`.
## App creation
### Setup tool (recommended)
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/sharing-github-apps/registering-a-github-app-from-a-manifest) to register the App with the permissions and events above.
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.
### Manual setup (alternative)
{% hint style="info" %}
**Create the App by hand** when the hosted tool can't reach your environment — either of these:
* **GitHub Enterprise Server.** The App has to be created on your own GHES instance.
* **Air-gapped**, or `earthly.dev` is otherwise unreachable from the browser session you would run the tool in.
{% endhint %}
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**). For GHES, create it on your GHES instance instead. 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.
Set the [permissions and events above](#permissions), then fill in the rest:
* **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/self-hosted/prerequisites#step-6-plan-your-kubernetes-secrets).
* **Where can this app be installed?** — "Only on this account."
Then, once the App exists:
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, for the same reason as above.
Whichever flow you used, you now hold four things: the owner, the App ID, the installation ID, and the PEM private key. [Prereqs Step 5](/install/lunar-hub/self-hosted/prerequisites#step-5-connect-your-git-platform) lists where each one comes from. Confirm you have all four, and that the PEM is saved, before moving on.
## Hub configuration (Dedicated)
Nothing to configure: Earthly runs the Hub and configures it for you. Continue at [Dedicated → Deposit your credentials](/install/lunar-hub/dedicated/setup#step-4-deposit-your-secrets), where the PEM goes to your install rather than to Earthly. The self-hosted section below does not apply to you.
## Hub configuration (self-hosted)
Those four values are what the Hub reads. [Install Step 4](/install/lunar-hub/self-hosted/install-walkthrough#git-platform-credentials) has the values block to paste; this is the reference behind it.
| Setting | Chart value | Environment variable | Meaning |
| --------------- | ------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Owner | `hub.github.app.owner` | `HUB_GITHUB_APP_OWNER` | The org or user the App is installed on. Matching is case-insensitive and trimmed. |
| App ID | `hub.github.app.id` | `HUB_GITHUB_APP_ID` | Numeric. Quote it in YAML, or it renders as scientific notation. |
| Installation ID | `hub.github.app.installId` | `HUB_GITHUB_APP_INSTALL_ID` | Numeric, from the install URL. |
| Private key | mounted from `lunar-github-app` | `HUB_GITHUB_APP_PRIVATE_KEY` | The base64-encoded PEM. |
| Base URL | `hub.github.baseUrl` | `HUB_GITHUB_BASE_URL` | GHES only. Your instance's API endpoint. |
| Host | (none) | `HUB_GITHUB_HOST` | Defaults to `github.com`. On GHES set it to your instance hostname, so component names (`/org/repo`) match what your manifests author. |
All four App fields are required together. A partial configuration is rejected at startup.
### Multiple organizations
When one Hub fronts several orgs that each install their own Lunar App, register one entry per owner in `HUB_GITHUB_APPS` instead of the single-App variables:
```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.
### Avoid GitHub rate limiting
GitHub gives every App installation its own REST rate-limit budget, so you can mitigate GitHub rate limits by installing additional Apps. A large organization may need 2–10 Apps to stay within the rate limit.
Create each additional App the same way as the first, through either flow in [App creation](#app-creation).
Register each as another entry in `HUB_GITHUB_APPS` with the same owner, its own `app_id` and `install_id`, and its own PEM:
```bash
export HUB_GITHUB_APPS=$(cat <<'EOF'
[
{"owner": "earthly", "app_id": 123, "private_key_path": "/secrets/github-apps/earthly.pem", "install_id": 100},
{"owner": "earthly", "app_id": 789, "private_key_path": "/secrets/github-apps/earthly-2.pem", "install_id": 300}
]
EOF
)
```
Give each entry a distinct `private_key_path` — the two Apps have different private keys, and pointing both at one file makes the second fail to authenticate.
Lunar Hub spreads **read** traffic evenly across every App registered for an owner. Writes — commit statuses and pull-request comments — always stay on the first App listed for that owner, because GitHub only allows the App that created a check run or comment to update it.
On Kubernetes, set this through `hub.github.apps` and give the second entry a `privateKeyFile` so it reads its own key from the App Secret (chart 3.14.0+):
```yaml
hub:
github:
apps:
- owner: earthly
appId: 123
installId: 100
- owner: earthly
appId: 789
installId: 300
privateKeyFile: earthly-2.pem
```
## Blocking merges
Lunar reports each evaluation as an **`Earthly Lunar` check run** on the commit. On its own the check is informational; it blocks merges when you require it in branch protection: **Settings → Branches → Branch protection rules → Require status checks to pass**, and add `Earthly Lunar` to the required checks. Unlike [GitLab Ultimate's merge gate](/install/git-platforms/gitlab#merge-gate), Lunar does not provision this setting for you. Whether the check is required stays your call, per branch rule.
The check run appears once Lunar has policy results for the commit. While a required check is waiting on data, it remains in progress and reads `N of M required checks pending`.
Only policies at a gating enforcement level participate. See [policies](/configuration/lunar-config/policies).
### Overriding a block
When a pull request is blocked and needs to merge anyway, an authorized engineer comments `/lunar bypass: ` on it; `/lunar bypass rm` takes the override back. The [PR/MR comments reference](/docs/pr-comments) documents both commands and the `maintain`-or-`admin` bar they require. A [`lunar policy bypass-pr`](/docs/lunar-cli#lunar-policy-bypass-pr) from the CLI also clears the check run on its next evaluation.
A check run that went green on a bypass says so in its title, reading `3 required check(s) bypassed` rather than reporting a pass, so a reviewer scanning the checks list can tell the two apart. The comment below it names who authorized each one.
## Next steps
Self-hosted installs carry these four values into Kubernetes secrets at [prereqs Step 6](/install/lunar-hub/self-hosted/prerequisites#step-6-plan-your-kubernetes-secrets), and into your chart values at [install Step 4](/install/lunar-hub/self-hosted/install-walkthrough#git-platform-credentials). On Dedicated you [deposit the PEM](/install/lunar-hub/dedicated/setup#step-4-deposit-your-secrets) into your install's secret drop instead.
For how GitHub and GitLab differ once Lunar is running, see [Git Platforms](/install/git-platforms).
# GitLab
Set up GitLab for Lunar. Create the service account and its token, configure the Hub, and understand how results are reported and how merge blocking works per tier.
The Hub authenticates as a **service account**: a machine user that you create, grant group memberships to, and issue a token for.
This page covers the GitLab side only. The install steps that consume it are in [Prerequisites → Step 5](/install/lunar-hub/self-hosted/prerequisites#step-5-connect-your-git-platform) for self-hosted, or the [Dedicated](/install/lunar-hub/dedicated/setup) setup steps.
## Authentication
How many accounts and tokens you need depends on where your GitLab runs:
| Your GitLab | Service account | Tokens |
| -------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------- |
| GitLab Dedicated or self-managed | A single **instance service account**, made a member of every top-level group Lunar serves | **One token** for everything |
| GitLab.com | One **group service account** per top-level group | One token per group |
Prefer the single instance service account wherever you administer the instance. GitLab.com has no such thing, so each top-level group there brings its own account and token.
With an instance service account you do not need to tell Lunar which groups it serves. It reads that from the account's memberships: every group where the account holds the Maintainer role, each covering its whole subtree. Lunar follows those memberships as they change, so you bring a group into scope by inviting the service account to it. A group service account's token, by contrast, is bound to its group in the Hub configuration (the `group` field below), and Lunar only uses it there. Where several tokens are configured for the same scope, Lunar load-balances its read traffic across them.
### Create the service account
On **GitLab Dedicated or self-managed**, an instance administrator does this once:
1. Go to **Admin → Settings → Service accounts** and select **Add service account**.
2. Name it something recognizable, e.g. `Earthly Lunar`. The account appears as the author of Lunar's merge-request comments and commit statuses.
3. Add the account to **every top-level group** Lunar should serve, with the **Maintainer** role (each group's **Manage → Members → Invite members**). A membership covers all of the group's subgroups and projects, and it is how Lunar decides what to serve. Inviting the account to a new group later onboards that group without any configuration change.
On **GitLab.com**, a group Owner does it once per top-level group:
1. In the group, go to **Settings → Service accounts** and select **Add service account**.
2. Add the account to the group with the **Maintainer** role.
### Create the token
On the service accounts page, select the vertical ellipsis (**⋮**) next to the account, then **Manage access tokens → Add new token**. Give it the `api` scope, and pick an expiry (see [Expiry and rotation](#expiry-and-rotation) below).
What each token can do decides which features are available for the groups it serves:
| Permission | Value | What it enables |
| ---------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| scope | `api` | Everything Lunar does over the API: reading repositories, commits, and merge requests; posting commit statuses and MR comments |
| role | `Maintainer` | Registering project webhooks, maintaining [project badges](#project-badges), and on Ultimate provisioning the [merge gate](#merge-gate): the status check and the **Status checks must succeed** setting |
Copy the token from GitLab. You leave this section with either a **single token** (instance service account) or **one token per top-level group** (GitLab.com).
### Expiry and rotation
GitLab access tokens carry a fixed expiry (by default at most a year out), and the Hub reads each token once at startup.
Set a calendar reminder ahead of the expiry date. When a token lapses, Lunar stops posting results and stops reacting to webhooks for the groups it served, and because the Hub only reads tokens at startup, nothing fails loudly to tell you.
A service account can hold several tokens at once, so replacement is a rollover rather than a cutover: create the new token next to the old one on the **Manage access tokens** page, deliver it, and revoke the old one once the Hub is running with the new. The delivery mechanics depend on your install: [self-hosted](/install/lunar-hub/self-hosted/day-2-operations#git-platform-credentials) is a secret update plus a Hub restart; on [Dedicated](/install/lunar-hub/dedicated/setup#step-4-deposit-your-secrets) you re-deposit the token into your install's secret drop.
{% hint style="warning" %}
GitLab 19.2 added an instance setting that **enforces fine-grained tokens after a chosen date**, which blocks the creation and rotation of classic-scope tokens. Service accounts cannot use fine-grained tokens yet, so if your instance plans to turn that enforcement on, keep its date clear of Lunar's rotation schedule until GitLab extends them to service accounts.
{% endhint %}
## Hub configuration (Dedicated)
There is nothing to configure: Earthly runs the Hub and configures it for you. Continue at [Dedicated → Deposit your credentials](/install/lunar-hub/dedicated/setup#step-4-deposit-your-secrets), where the token goes to your install rather than to Earthly. What you deposit is what the steps above produced:
* **GitLab Dedicated or self-managed**: the instance service account's single token, alongside your instance hostname.
* **GitLab.com**: one token per **group service account**.
Everything below is for self-hosted installs; you can skip to [Merge gate](#merge-gate).
## Hub configuration (self-hosted)
Lunar reads GitLab credentials from `HUB_GITLAB_TOKENS`, a JSON array with one entry per token, typically a single entry holding the instance service account's token. [Install Step 4](/install/lunar-hub/self-hosted/install-walkthrough#git-platform-credentials) has the values block to paste; this is the field reference behind it.
### Entry fields
| Field | Required | Meaning |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token_path` | Yes | Where the token file is mounted inside the Hub container. |
| `group` | No | Binds the token to one top-level group or subgroup, which it serves together with everything beneath it. Omit it for an instance service account: the token then serves every group on `host` that no `group` entry claims. A `group` entry always takes precedence over a group-less one, and the most specific `group` wins when several match. |
| `webhook_secret` | No | Overrides the chart-generated signing secret (`-gitlab-webhook`) for the groups this entry serves. Set it when one group should not be able to forge deliveries for another; leave it out otherwise. Entries that form a pool (same host and `group`) must agree on it; the hub refuses to start otherwise. |
| `host` | No | Defaults to `gitlab.com`. Set it to your instance hostname for self-managed. |
| `base_url` | No | Defaults to `https:///api/v4`. Set it only if your instance serves the API somewhere else. |
A token without `group` must be a Maintainer everywhere Lunar reaches on that host: Lunar does not fall back to another token when a call it makes with that account is refused. On GitLab.com, where each token belongs to a group service account, set `group` on every entry.
{% hint style="warning" %}
**A self-managed host must be listed here.** Lunar decides whether a host is GitLab from this configuration. If you omit `host` for a self-managed instance, Lunar treats that host as GitHub, and every operation against it fails in confusing ways. `gitlab.com` is recognized without configuration.
{% endhint %}
### Multiple groups
What this looks like depends on which GitLab you run.
#### GitLab.com: one entry per group
There is no instance-wide service account on GitLab.com, so every top-level group brings its own account and its own `group` entry:
```yaml
hub:
extraEnv:
- name: HUB_GITLAB_TOKENS
value: >-
[{"group":"acme","token_path":"/secrets/gitlab/acme.token"},
{"group":"globex","token_path":"/secrets/gitlab/globex.token"}]
```
#### GitLab Dedicated or self-managed
The instance service account serves every group it is a Maintainer of, so one group-less entry covers them all. Invite the account to a new group and nothing here changes:
```yaml
hub:
extraEnv:
- name: HUB_GITLAB_TOKENS
value: '[{"host":"gitlab.example.com","token_path":"/secrets/gitlab/lunar-sa.token"}]'
```
One group can still take a token of its own, for example a sensitive group that should show a separate bot in its audit trail. A `group` entry wins over the group-less one, so the shared account never touches that group:
```yaml
hub:
extraEnv:
- name: HUB_GITLAB_TOKENS
value: >-
[{"host":"gitlab.example.com","token_path":"/secrets/gitlab/lunar-sa.token"},
{"host":"gitlab.example.com","group":"finance","token_path":"/secrets/gitlab/finance-bot.token"}]
```
### More rate limit for a busy scope
Repeating a scope (the same `group`, or the same `host` with no `group`) pools its tokens: Lunar spreads read traffic (commits, merge requests, project metadata) across the pool and uses the first entry listed for everything it writes, so comments, statuses, and webhooks always come from one identity. To give a busy subgroup more rate limit without changing who serves the rest of the instance, add a second account to that subgroup and list both tokens under its `group`:
```yaml
hub:
extraEnv:
- name: HUB_GITLAB_TOKENS
value: >-
[{"host":"gitlab.example.com","token_path":"/secrets/gitlab/lunar-sa.token"},
{"host":"gitlab.example.com","group":"platform/checkout","token_path":"/secrets/gitlab/lunar-sa.token"},
{"host":"gitlab.example.com","group":"platform/checkout","token_path":"/secrets/gitlab/checkout-sa.token"}]
```
Here `platform/checkout` draws on both accounts' rate limits, and everything else stays on the shared account alone. Give the accounts in a pool the same role, so that what Lunar can do in a group does not depend on which token serves a call.
{% hint style="info" %}
**Scaling tip.** GitLab applies API rate limits per account. If the whole instance is busy, add a second instance service account as another group-less entry; if one group or subgroup pushes constantly, pool extra tokens under its `group` as above. (On a self-managed instance you can also raise the limits; on gitlab.com you cannot.)
{% endhint %}
## Merge gate
Lunar can block a merge request on every tier. What differs is the mechanism, how precisely it targets Lunar, and who switches it on.
| Tier | Mechanism | Blocking |
| ------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Ultimate | [External status check](#external-status-checks-ultimate) | Lunar provisions and enables it for you |
| Free, Premium | [Commit status](#commit-status-default) | Available, but you enable **Pipelines must succeed** yourself, and it gates on the whole pipeline rather than on Lunar specifically |
Only policies at a gating enforcement level participate. See [policies](/configuration/lunar-config/policies). Whichever mechanism you are on, a blocked merge request can be let through by [overriding a block](#overriding-a-block).
### External status checks (Ultimate)
On **GitLab Ultimate**, Lunar blocks a merge request whose gating policies do not pass.
{% hint style="warning" %}
**There is no setting to turn this on, and Lunar changes your projects to enable it.** Read what it changes below before rolling Lunar out to an Ultimate namespace.
{% endhint %}
Merge blocking is capability-driven: Lunar detects that a namespace is on Ultimate and switches on automatically. There is no configuration flag, so if you upgrade a namespace's licence later, blocking activates on the next sync without anyone touching Lunar's configuration.
To make blocking work, Lunar changes each project it tracks:
| Change | Where you see it in GitLab |
| -------------------------------------------- | --------------------------------------------- |
| Creates a status check named `Earthly Lunar` | **Settings → Merge requests → Status checks** |
| Enables **Status checks must succeed** | **Settings → Merge requests** |
**Lunar re-applies these settings on every sync.** Turning them off in the GitLab UI is temporary; they come back. This is deliberate: it keeps the gate from being quietly disabled on one project and drifting out of policy. But it does mean that switching the gate off is not a supported way to stop it; see [Turning the gate off](#turning-the-gate-off).
This requires the service account to hold the `Maintainer` or `Owner` role, since Lunar creates the status check and changes merge-request settings.
#### Turning the gate off
The gate is **fail-closed**. If Lunar is unavailable, gated merge requests stay blocked rather than falling open. That is the safe default for a compliance control, but it means you should know the lever before you need it.
To unblock merges during an incident, a project **Owner** disables **Status checks must succeed** in **Settings → Merge requests**.
### Commit status (default)
On **GitLab Free and Premium** there are no external status checks, so Lunar posts a commit status named `Earthly Lunar` instead. Lunar provisions no merge gate on these tiers, and changes no merge-request setting. It still writes the status, registers the project webhook, and maintains [project badges](#project-badges), as it does on Ultimate.
A commit status folds into the commit's pipeline result, so it **can** gate merges, but you enable that yourself, per project, in **Settings → Merge requests → Merge checks → Pipelines must succeed**. With it on, a failing Lunar status makes the pipeline fail and the merge request unmergeable.
Two consequences worth knowing before relying on it:
* **It is not Lunar-specific.** The setting gates on the pipeline as a whole, so a Lunar failure and a broken test look the same to it, and you cannot require Lunar without also requiring everything else in the pipeline. The Ultimate status check is a named requirement; this is not.
* **Pending counts as not-succeeded.** Lunar reports `running` while a commit's checks are still evaluating, so a merge request stays unmergeable until Lunar resolves. That is the point, and it is why [overriding a block](#overriding-a-block) forces the status green for a commit rather than waiting for the evaluation to finish.
### Overriding a block
A blocked merge request can be overridden without leaving the thread: comment `/lunar bypass: ` to override the gate, or `/lunar bypass rm` to take an override back. See the [PR/MR comments reference](/docs/pr-comments) for the commands, the Maintainer bar they demand, and the audit trail they leave. A [`lunar policy bypass-pr`](/docs/lunar-cli#lunar-policy-bypass-pr) from the CLI clears the same gate.
This works on every tier, against whichever mechanism the project has: on Ultimate it answers the status check, and on Free and Premium it writes the commit status **Pipelines must succeed** reads.
## MR status reporting
On a merge request, Lunar reports each evaluation as:
* **A named result**: the `Earthly Lunar` status check on Ultimate, or a commit status on Free and Premium. See [Merge gate](#merge-gate) for which of those can block.
* **A merge-request comment** summarising the policy results, updated in place as new commits arrive rather than posted repeatedly.
Reporting depends on webhooks, which the Hub registers on each project automatically, on every tier. The hook subscribes to push, merge-request, and comment events; the comment events are what carry the [`/lunar` commands](/docs/pr-comments).
## Main branch status reporting
On commits to the default branch, Lunar posts a **commit status**, on every tier.
Status checks exist only on merge requests, so there is no Ultimate-specific behaviour here and nothing to configure: default-branch reporting looks the same whichever tier you are on. These statuses are informational; there is no merge to block.
### Project badges
Lunar maintains **project badges** that reflect the latest default-branch result, so a project's standing is visible from its overview page without opening a commit or a dashboard. Each links to the dashboard behind it.
* **Release readiness**, one per project. It reads `release ready` when nothing blocks a release, `release blocked` when something does, `release bypassed` when the only things blocking are covered by an active [`lunar policy bypass-release`](/docs/lunar-cli#lunar-policy-bypass-release), and `evaluating` while results are still arriving. A partial bypass still reads `release blocked`.
* **One per initiative**, showing that initiative's score for the component.
Lunar gates releases but never observes one, so `release ready` means nothing is blocking, not that anything shipped. A component with no release-gating policies reads `release ready`.
The default-branch commit status is deliberately left at its un-bypassed verdict, so a bypassed project reads as blocked on the commit and overridden on the badge.
On a monorepo, the badges belong to the component whose name carries no subdirectory, and the release badge is omitted, since release readiness is per component and the project has several. A monorepo with no whole-repo component gets no badges.
Lunar provisions badges with the service account's token, as it does the merge gate's status check, so the account needs the same `Maintainer` or `Owner` role.
## Next steps
Self-hosted installs carry the token into a Kubernetes secret at [prereqs Step 6](/install/lunar-hub/self-hosted/prerequisites#step-6-plan-your-kubernetes-secrets), and into your chart values at [install Step 4](/install/lunar-hub/self-hosted/install-walkthrough#git-platform-credentials). On Dedicated you [deposit it](/install/lunar-hub/dedicated/setup#step-4-deposit-your-secrets) into your install's secret drop instead.
After that, set up [config sync from GitLab CI](/install/lunar-hub/self-hosted/sync-config#gitlab-ci) so the Hub's copy of your configuration stays current as you edit it. [Git Platforms](/install/git-platforms) has the full capability comparison with GitHub.
# Lunar CI Tracer
Which CI platforms the Lunar CI Tracer can trace (GitHub Actions, Buildkite, and GitLab CI), and where the setup instructions for each live.
The **Lunar CI Tracer** instruments your CI runners: it wraps the runner process, watches what a build actually does, and triggers collectors at the right moments. That is how build-time facts reach the Hub, including test results, scan output, image digests, and deploy markers.
It installs on your runners rather than in the cluster, so it is independent of the Hub install and can be added at any point after it.
CI tracing is optional. Lunar still collects from pushes and merge requests without it; the tracer is what adds the build-time half.
| CI platform | Support | Setup |
| ------------------ | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **GitHub Actions** | Supported | [Self-hosted runners](/install/ci-tracer/github-actions-self-hosted): install the tracer on the runner. [GitHub-managed runners](/install/ci-tracer/github-actions-managed): add the `earthly/lunar-ci-tracer` action to your workflow. |
| **Buildkite** | Supported | [Buildkite](/install/ci-tracer/buildkite): an agent command hook plus a Notification Service webhook. |
| **GitLab CI** | [Coming soon](/install/ci-tracer/gitlab-ci) | Nothing to install yet. Submit build-time facts from a job with [`lunar collect`](/docs/lunar-cli#lunar-collect) in the meantime. |
## Choosing between the two GitHub Actions options
Both put the same tracer on the runner; they differ in where the install happens.
* [**The action**](/install/ci-tracer/github-actions-managed) is per workflow job, and works on GitHub-hosted *and* self-hosted runners. It is the easier starting point, and the only option when you do not control the runner image.
* [**Installing on the runner**](/install/ci-tracer/github-actions-self-hosted) is per-machine, so every workflow on that runner is traced without touching any workflow YAML. It needs self-hosted runners you administer.
## Shared configuration
* [Configuration reference](/install/ci-tracer/configuration-reference) covers every environment variable the tracer reads, on any platform.
* [Systemd](/install/ci-tracer/systemd) covers running the tracer as a service on a Linux host.
## Next steps
* [Git Platforms](/install/git-platforms) for the credentials Lunar uses to read repositories and post results.
* [Install Lunar](/install) for where CI integration fits in the overall install.
# GitHub Actions (Self-Hosted)
Install the Lunar CI Tracer on self-hosted runners to instrument CI/CD pipelines and collect metadata during builds, tests, scans, and deploys.
The Lunar CI Tracer 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/ci-tracer/github-actions-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 tracer 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 tracer 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 tracer
```bash
lunar ci-tracer run
```
On first run, `lunar ci-tracer run` downloads the tracer 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 tracer binary is cached, the tracer 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 tracer with `lunar ci-tracer run`, which fetches the tracer 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/ci-tracer/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 tracer 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 tracer 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 tracer 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 tracer 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 tracer 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/ci-tracer/configuration-reference).
***
## Running `sudo` and setuid binaries in traced workflows
To trace command execution, the tracer 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 tracer 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 tracer 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 tracer 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/ci-tracer/github-actions-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
# GitHub Actions (Managed)
Use the Lunar CI Tracer action to instrument GitHub-hosted and self-hosted GitHub Actions runners with the Lunar CI Tracer.
The [`earthly/lunar-ci-tracer`](https://github.com/earthly/lunar-ci-tracer) action is the easiest way to add the Lunar CI Tracer 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 tracer to [wrap the runner's `run.sh` command](/install/ci-tracer/github-actions-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 tracer 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 tracer through your Hub on first use and execs it. The tracer attaches to the current shell process via ptrace and traces all commands executed by subsequent steps. The tracer exits automatically when the job completes.
The same [configuration reference](/install/ci-tracer/configuration-reference) 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/ci-tracer/github-actions-self-hosted).
{% endhint %}
## Failure Handling
Tracer installation failures (CLI download, tracer download through the Hub, tracer 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
```
# 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 %}
{% hint style="warning" %}
Buildkite support assumes **GitHub-hosted repositories**. Component attribution and changed-path inference both resolve against GitHub, so Buildkite pipelines building GitLab projects are not supported. See [Git Platforms](/install/git-platforms).
{% 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 tracer 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/ci-tracer/configuration-reference) 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.
# GitLab CI
GitLab CI tracing support in Lunar is coming soon.
**Coming soon.** The Lunar CI tracer does not support GitLab CI yet, so there is nothing to install on a GitLab Runner.
In the meantime, Lunar collects on GitLab from pushes and merge requests, and build-time facts can be submitted from a pipeline job with [`lunar collect`](/docs/lunar-cli#lunar-collect).
# Configuration Reference
Reference for all environment variables that configure the Lunar CI Tracer, 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 — a bare host name such as `hub.example.com`. Must be reachable from the runner. |
| `LUNAR_HUB_GRPC_PORT` | Hub's gRPC port. Used for configuration sync, collection results, and SCM 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`. `gitlab` coming soon (see [GitLab CI](/install/ci-tracer/gitlab-ci)). For Buildkite setup, see [Buildkite](/install/ci-tracer/buildkite). |
| `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/ci-tracer/github-actions-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 tracer polls Lunar Hub for configuration updates. Each poll asks only for what has changed since the tracer's last one, so a poll that finds nothing new costs a single small request. |
| `LUNAR_CATALOG_FULL_REFRESH_PERIOD` | `15m` | How often the tracer re-reads the component catalog in full instead of asking only for changes, as a backstop against a change being missed by the incremental check. Jobs do not depend on it: the tracer re-reads the catalog for a repository whenever a job for that repository starts. Lower it to converge faster at the cost of more traffic; `0` disables it. |
| `LUNAR_CATALOG_FETCH_TIMEOUT` | `10s` | How long the tracer will wait, at the start of a job, for an up-to-date catalog of the repository being built. This read is unconditional, so a job always starts against a current catalog for its own repository. On timeout the tracer proceeds with the catalog it already has rather than failing the job. `0` turns off per-repository fetching, so the tracer keeps a copy of the whole catalog instead. |
| `LUNAR_LOG_LEVEL` | `info` | Log verbosity. Set to `debug` for troubleshooting. |
| `LUNAR_GITHUB_HOST` | `github.com` | The GitHub host whose components this tracer collects for (the `` in `//` component names). Auto-detected from `GITHUB_SERVER_URL` when the tracer runs as a GitHub Actions step (including via the [Lunar CI Tracer action](/install/ci-tracer/github-actions-managed)), so **GitHub Enterprise Server "just works"** there. Set it explicitly only when the tracer 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 tracer 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 tracer 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. |
# 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 Tracer
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 %}
# 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. On GitLab the component name includes the full namespace — `gitlab.com/my-group/my-service`, or `gitlab.com/my-group/my-subgroup/my-service` for a project in a subgroup. See [Components](/configuration/lunar-config/components) for the naming rules.
{% 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
# GitHub
lunar hub pull github://my-org/lunar@main
# GitLab
lunar hub pull gitlab://gitlab.com/my-group/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
# ... or gitlab://gitlab.com/my-group/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, CI/CD hooks, or data from other collectors.
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 Tracer 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 Tracer
The Earthly Lunar CI Tracer allows you to trigger and execute collectors related to CI/CD pipelines running on a CI runner. The tracer is installed on the self-hosted runner of the CI (GitHub Actions or 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 tracer is installed properly in such situations.
The Lunar CI Tracer 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.
# Guides
Opinionated guides for rolling out Lunar in a large engineering organization, beyond the reference documentation.
The rest of the documentation describes what each part of Lunar does. These guides describe what to actually do with them — the sequencing, the trade-offs, and the failure modes we see most often in large engineering organizations.
* [Cataloging Strategy](/docs/guides/cataloging-strategy) — how to get from a partial, inconsistent software catalog to one complete and trustworthy enough to scope guardrails with. Covers coverage, cleanup, monorepos, and the guardrails that keep the catalog honest.
Guides assume you have already [installed Lunar](/install) and read [Key concepts](/docs/key-concepts).
# Cataloging Strategy
How to build a complete, trustworthy software catalog in Lunar — achieving full coverage, cleaning up inconsistent existing catalog data, handling monorepos, and enforcing catalog quality with guardra
Lunar decides what to enforce, and where, from your catalog. Domains determine the reporting structure, and tags determine which collectors and policies apply to which component through [`on` expressions](/configuration/lunar-config/on). A component that is missing, misfiled, or mistagged is a component your guardrails silently skip.
That makes catalog quality the first thing to work on in a Lunar rollout. In most large organizations only a fraction of repositories ship to production, handle regulated data, or fall in scope for a compliance audit, and targeting your strictest guardrails at that fraction is what keeps them credible with the teams they apply to.
You do not need a good catalog to start. Most organizations do not have one, and the steps below are designed to be run against a messy or largely absent catalog — Lunar becomes the thing that gets you to a good one, and starts returning findings while you are still working on it.
## What you are starting from
Most organizations we work with already have a catalog of some kind. It typically has three problems.
**It is incomplete.** Registering a service was a convention, not a requirement, and nothing enforced it. A meaningful share of repositories were never cataloged at all.
**It is inconsistent.** Entries were filled in by individual teams over several years, against a schema that drifted. Owners point at people who left. Tags mean different things in different divisions. Nothing has ever validated the data, because nothing has ever depended on it programatically.
**It does not identify monorepo components uniquely.** A monorepo's catalog entries were written for a system that keys on a service name. Lunar keys on a repository URL plus an optional subdirectory, and most existing catalogs carry no field that maps cleanly onto that.
None of this was a problem before, because the catalog was a directory that people read. Lunar is the first system to make automated, consequential decisions from it, and that is a much higher bar.
The catalog data itself usually comes in one of three shapes, and the strategy below works for all of them:
| Shape | Example | Source of truth |
| ---------------------------------- | --------------------------------------------------- | --------------------------- |
| **Catalog service with an API** | Backstage, an internal service registry | A server you can query |
| **Files distributed across repos** | `catalog-info.yaml` in each repository | The repositories themselves |
| **Central metadata repository** | One repo of YAML/TOML/JSON describing every service | A single repository |
Backstage is used as the running example because it is the more common, and because Lunar ships plugins for it. The same phases apply to a home-grown catalog; only the plugins differ. Where a shipped plugin does not fit your format, the [AI skills](/install/skills) for Claude Code, Codex, and Cursor are the fastest way to produce the collector, policy, or cataloger you need — they know Lunar's SDKs and conventions, so pointing one at your existing catalog schema gets you most of the way.
## The shape of the operation
At the highest level this is three moves, in order:
{% stepper %}
{% step %}
### Ingest every repository, ignoring the existing catalog
Get 100% of your repositories into Lunar as components before looking at any pre-existing catalog data. You immediately know the true size of the estate.
{% endstep %}
{% step %}
### Validate and fix the catalog data at scale
Pull the existing catalog entries in as raw data and run guardrails against them, without letting them shape your catalog yet. Developers get feedback in their pull requests on exactly what is wrong with their own entries, and the cleanup happens in parallel across the organization instead of as a central project.
{% endstep %}
{% step %}
### Ingest the clean catalog
Once the data is trustworthy, let it drive Lunar's components, domains, and tags — then enrich it with what nobody wrote down.
{% endstep %}
{% endstepper %}
## The steps
| # | Step | Primitive | Required | Purpose |
| ----- | ---------------------------------------------------------------------------------- | --------- | --------- | -------------------------------------------------- |
| **1** | **Ingest every repository** | | | |
| 1.1 | [Discover every repository](#11-discover-every-repository) | Cataloger | Yes | Establish 100% coverage as the floor |
| **2** | **Validate and fix the catalog data** | | | |
| 2.1 | [Collect the existing catalog data](#21-collect-the-existing-catalog-data) | Collector | Yes | Pull raw catalog entries into Lunar |
| 2.2 | [Validate structure and identity](#22-validate-structure-and-component-identity) | Policy | Yes | Developer feedback; monorepo uniqueness |
| 2.3 | [Require a catalog entry](#23-require-a-catalog-entry) | Policy | Optional | Close the coverage gap continuously |
| **3** | **Ingest the clean catalog** | | | |
| 3.1 | [Ingest the catalog](#31-ingest-the-catalog-into-lunar) | Cataloger | Yes | Turn validated data into components, domains, tags |
| 3.2 | [Validate the ingested catalog](#32-validate-the-ingested-catalog) | Policy | Optional | Enforce semantics beyond structure |
| 3.3 | [Enrich with heuristics](#33-enrich-with-heuristics) | Cataloger | Optional | Classify what nobody wrote down |
| 3.4 | [Declare paths for monorepo components](#34-declare-paths-for-monorepo-components) | Cataloger | Monorepos | Make change detection correct in monorepos |
## Phase 1. Ingest every repository
### 1.1 Discover every repository
Start with a cataloger that enumerates your source control and creates one component per repository. This is your coverage floor, and it is what makes 100% coverage achievable on day one rather than as the outcome of a migration.
{% code title="lunar-config.yml" %}
```yaml
catalogers:
- name: github-org
uses: github://earthly/lunar-lib/catalogers/github-org@v1.12.0
with:
org_name: acme
default_owner: platform@acme.com
default_domain: engineering
include_archived: "false"
```
{% endcode %}
Set `default_domain`. Every component then lands under a known root domain, which gives you a handle that matches everything: [domain tags match hierarchically](/configuration/lunar-config/on#domain-tags), so `on: ["domain:engineering"]` covers `engineering` and every subdomain beneath it.
Repeat the cataloger once per organization if you have several. See the [GitHub Org cataloger documentation](https://earthly.dev/lunar/integrations/catalogers/github-org/) for all the available settings.
At this point every repository exists as a component, everything is in one domain, and nothing is classified. That is the correct starting state. The remaining steps add more meaning.
{% hint style="info" %}
**Monorepos at this stage.** The GitHub org cataloger creates a single component for the monorepo root (`github.com/acme/monorepo`). Lunar has no awareness of the internal breakdown yet. Phase 2 is what begins interpreting the monorepo structure; step 3.1 is what turns it into real subcomponents.
{% endhint %}
## Phase 2. Validate and fix the catalog data
### 2.1 Collect the existing catalog data
Write a collector that reads your existing catalog entries out of each repository and writes them into the [Component JSON](/docs/component-json) verbatim. Do not interpret or reshape the data here. The point is to make the raw entry visible so a policy can judge it.
Lunar ships a collector for Backstage's `catalog-info.yaml`; a home-grown format needs an equivalent collector of your own.
{% code title="lunar-config.yml — Backstage example" %}
```yaml
collectors:
- uses: github://earthly/lunar-lib/collectors/backstage@v1.12.0
on: ["domain:engineering"]
```
{% endcode %}
The component JSON convention is to write the raw descriptor under `.catalog.native.`, where the *presence* of the key is itself the signal: if the collector finds no entry, it writes nothing, and the absence means "not cataloged".
Use a `code` hook so this re-runs whenever the repository changes, which is what makes the feedback in step 2.2 immediate.
**In monorepos, collect the whole tree onto the repository-level component.** The subcomponents do not exist yet, so a collector scoped to a single directory would find nothing. Have the collector gather every entry in the repository and write them as a set onto the root component. That is what lets step 2.2 see all the entries at once and check them against each other. The repository-level component has no `paths` restriction, so it runs on any change anywhere in the monorepo.
How you gather that set depends on how the monorepo declares its components. Two layouts are common:
**One entry file per component directory** — `services/payments/catalog-info.yaml`, `services/web/catalog-info.yaml`, and so on. Walk the tree and record each entry *together with the path of the file it came from*. That path is what makes each component's identity derivable in step 2.2, so carry it through rather than discarding it after parsing.
**One shared entry file listing every component** — a single root `catalog-info.yaml`, typically a multi-document YAML or a list of entities, declaring every service in the repository. Collect the whole file and keep every entity in it. The catch is that there is no per-component file location to fall back on here: every entry shares one path, so the subdirectory has to come from a field *inside* each entry. If no such field exists today, this is the layout that forces you to introduce one. See [Component identity](#component-identity) below.
The two layouts often coexist in the same organization, and can coexist in the same repository. You may handle both in the collector rather than mandating one, since consolidating a monorepo's catalog files is a migration in its own right and not necessarily a prerequisite for getting started.
A central metadata repository behaves like the shared-file layout: one location, many entries, so identity has to be carried in a field. The same collector logic applies, driven from the central repo rather than from each component's own tree.
### 2.2 Validate structure and component identity
Now add a policy that validates the raw entries the collector gathered. This is the step that turns catalog quality into something developers see and act on, because policies report into pull requests and catalogers do not.
{% code title="lunar-config.yml — Backstage example" %}
```yaml
policies:
- uses: github://earthly/lunar-lib/policies/backstage@v1.12.0
name: catalog-structure
initiative: cataloging
on: ["domain:engineering"]
include: [catalog-info-exists, catalog-info-valid, owner-set, lifecycle-set, system-set]
enforcement: report-pr
```
{% endcode %}
{% hint style="info" %}
The checks in that plugin are written against the `catalog-info.yaml` schema, so they only apply if your catalog is Backstage-shaped. For a home-grown catalog the structure of this step is identical, but the assertions are yours to write — see the [Python SDK](/plugin-sdks/python-sdk/policy), or use the [AI skills](/install/skills) to generate a policy plugin against your own schema.
Whichever route you take, the checks in [Component identity](#component-identity) below are the ones that are not optional.
{% endhint %}
#### Component identity
Lunar identifies a component by repository URL plus an optional subdirectory. The grammar is positional:
```
github.com//[/] # GitHub
gitlab.com//[/-/] # GitLab
```
On GitHub the first three segments are always host, org, and repo; everything after is the subdirectory. On GitLab, namespaces nest arbitrarily, so the `/-/` marker is what separates the project from the subdirectory. See [Components](/configuration/lunar-config/components) for the full rules.
Every component in a monorepo therefore needs its own distinct subdirectory path — `github.com/acme/monorepo/services/payments`, `github.com/acme/monorepo/services/web`. Deciding where that subdirectory comes from is the main piece of design work in a monorepo migration, and it is worth doing deliberately rather than discovering it later.
#### Where the subdirectory comes from
{% hint style="info" %}
If your monorepos use **one entry file per component directory**, the subdirectory is inherent in the layout (it is the directory the file sits in) and you can skip to [the collision danger](#why-identity-collisions-are-dangerous) below. The rest of this section matters when the file's location does not identify the component: a **shared entry file** listing many components, or a sync from the catalog API, where every entry arrives with the same location or none at all.
{% endhint %}
In Backstage, three annotations are candidates, and the one most people reach for first is the one that cannot work:
* **`github.com/project-slug` is repo-level by definition.** Its [documented format](https://backstage.io/docs/features/software-catalog/well-known-annotations/) is `owner/repo`, with no path component, and the processor that auto-populates it derives it from the repository alone. Every component in a monorepo receives an identical value. This is also the default `component_id_annotation` for Lunar's Backstage catalogers, so leaving it at the default is exactly how a monorepo collapses into a single component.
* **`backstage.io/source-location`** ***can***** carry the subdirectory, but frequently does not.** Backstage's built-in location processor resolves it relative to the entity's own location, so an entry in `services/payments/` auto-populates to `url:https://github.com/acme/monorepo/tree/main/services/payments/`. It is also documented as hand-writable, for the case where the catalog file does not sit with the source it describes. In practice, though, a great many real catalogs have this annotation pointing at the repository root anyway — hand-written once and never revisited, copied between services, or carried over from a migration. **Treat it as a hint, not a fact.** Validate it rather than trusting it, which is exactly what the next section is for.
* **`backstage.io/managed-by-location` is a weaker fallback.** It is always present and points at the entry file, so its directory is recoverable. But Backstage documents it as many-to-one — a single location can be the source of many entities — and does not guarantee the value is even a `url` type, so it cannot be the primary key in the shared-file layout.
That leaves three realistic options:
| Option | How identity is derived | When it fits |
| ------------------------------ | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **The entry file's location** | The directory containing each entry file *is* the subdirectory | One entry file per component. Correct by construction, nothing to maintain, nothing to trust. |
| **An existing location field** | Parse `source-location` down to a repo-relative path | A shared entry file, or syncing from the catalog API — provided you validate the values first |
| **A dedicated field** | A new annotation holding the subdirectory verbatim | The existing fields are unreliable, or you want the value explicit and reviewable |
Deriving from the entry file's location is the best option wherever it applies, precisely because it depends on no field anyone has to maintain. It is what Lunar's monorepo cataloger does.
The choice between repurposing `source-location` and introducing a dedicated annotation usually comes down to how much of your existing data is already correct. Measure that first — step 2.2 gives you the number — and repurpose only if the answer is "most of it". Introducing a new field costs one backfill; adopting a field that is quietly wrong for a third of your services costs you a wrong catalog that looks right.
Both annotation-based routes also need a parsing step: Lunar's API-based Backstage cataloger concatenates `component_id_prefix` with the raw annotation value, so it needs a field already in bare `owner/repo/subdir` form. A full `url:https://…` value cannot be pointed at directly.
{% hint style="info" %}
Repurposing `backstage.io/source-location` is safe. TechDocs resolves against `backstage.io/techdocs-ref`, and the catalog page's view and edit links are governed by `backstage.io/view-url` and `backstage.io/edit-url`, so none of them depend on it. Several tools in the ecosystem already read this annotation for exactly this purpose — scoping themselves to a component's subdirectory within a monorepo.
{% endhint %}
The shared-entry-file layout from step 2 needs particular care here. Every entity in that file shares one location, so the auto-populated `source-location` is identical for all of them and points at the repository root. Auto-derivation cannot disambiguate them at all, which makes a hand-written `source-location` or a dedicated field mandatory in that layout rather than a preference.
#### Why identity collisions are dangerous
If two catalog entries resolve to the same component id, Lunar merges them into one component, and the merge is **silent and lossy in a specific way**:
* Scalar fields — `owner`, `domain`, `branch`, `description` — take the value of whichever cataloger ran last.
* Array fields — `tags`, `paths`, `ciPipelines` — are **concatenated**.
The array behavior is the one that causes real damage. Two colliding services produce one component holding the union of both tag sets, so a service that is not production can inherit `production` from its collision partner and pull strict guardrails onto itself, while its partner's `owner` is quietly overwritten with the wrong team. Nothing errors, and the result looks plausible in the UI.
{% hint style="danger" %}
This is the single most important check to get right in a monorepo. Assert it before the data reaches your cataloger, not after.
{% endhint %}
Your policy should assert, over the full set of entries the collector found:
1. Every entry resolves to a **distinct** component id. This is the check that makes the identity decision above real, and the only one that catches a collision before it silently merges.
2. Whatever field you chose to carry the subdirectory is **present** on every entry in a monorepo. An entry that omits it falls back to the repository root and collides with every other entry that does the same.
3. That field is **actually specific to the component**, not left at the repository root. This is the check that catches a stale `source-location`, and in a monorepo a root-pointing value is indistinguishable from a missing one.
4. Each id is **well-formed** for your git platform — three segments plus a subdirectory on GitHub, `/-/` separated on GitLab.
5. The subdirectory **corresponds to a real directory** in the repository, and where you derive identity from entry-file locations, that it matches the file's own directory. This is what keeps identity stable when the repository is reorganized.
6. Required fields are present and typed correctly.
Start at `enforcement: report-pr` so teams see the problems without being blocked, then escalate to `block-pr` once the backlog is worked down. Group the policies under a `cataloging` [initiative](/configuration/lunar-config/initiatives) so the effort is trackable as a unit.
### 2.3 Require a catalog entry
*Optional, but this is the step that closes the coverage gap permanently.*
Because step 1.1 made every repository a component, you can now enforce that every component has a catalog entry — the mechanism your organization previously lacked.
{% code title="lunar-config.yml — Backstage example" %}
```yaml
policies:
- uses: github://earthly/lunar-lib/policies/backstage@v1.12.0
name: catalog-coverage
initiative: cataloging
on: ["domain:engineering"]
include: [catalog-info-exists]
enforcement: score
```
{% endcode %}
Roll this out along the [enforcement ladder](/configuration/lunar-config/policies#enforcement): `score` to measure the gap without touching anyone, `report-pr` to surface it in pull requests, then `block-pr` once coverage is high enough that blocking is fair.
## Phase 3. Ingest the clean catalog
### 3.1 Ingest the catalog into Lunar
Now add the cataloger that reads your existing catalog and maps it onto Lunar's components, domains, and tags. The source can be the same files the collector read, or the catalog service's API if the server adds value your files do not have — resolved group hierarchies, defaulted namespaces, entity relations.
Catalogers run on a [hook](/configuration/lunar-config/cataloger-hooks). A scheduled full sync is the usual backbone — catalog data changes slowly, and a nightly pass is simple to reason about and self-healing. Use a `repo` hook instead if your source is a central metadata repository, so the catalog refreshes on merge rather than on a schedule.
You can also pair the nightly sync with a commit-triggered cataloger where your source is repo-resident files. The [Backstage catalog-info.yaml cataloger](https://earthly.dev/lunar/integrations/catalogers/backstage-catalog-info/) ships both by default: a scheduled `augment`, and an `augment-on-commit` that re-reads the file as soon as the repo is committed to, so an edited `catalog-info.yaml` lands immediately rather than at the next nightly tick.
#### Available Backstage catalogers
Lunar ships four catalogers relevant to this step. They are designed to layer, not to compete:
| Cataloger | Source | What it does |
| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| [`github-org`](https://earthly.dev/lunar/integrations/catalogers/github-org/) | GitHub API | One component per repository. The coverage floor from step 1.1. |
| [`backstage`](https://earthly.dev/lunar/integrations/catalogers/backstage/) | Backstage REST API | Components and domains from the running server, with `subdomainOf` / `spec.system` hierarchy resolved into dotted domain paths. |
| [`backstage-catalog-info`](https://earthly.dev/lunar/integrations/catalogers/backstage-catalog-info/) | `catalog-info.yaml` per repo | Augments each existing component from its own committed file. |
| [`backstage-catalog-info-monorepo`](https://earthly.dev/lunar/integrations/catalogers/backstage-catalog-info-monorepo/) | Every `catalog-info.yaml` in a repo | Creates one component per file, keyed to that file's directory. The monorepo answer. |
{% code title="lunar-config.yml — Backstage example" %}
```yaml
catalogers:
# Repo-level components, from each repository's own catalog-info.yaml.
- uses: github://earthly/lunar-lib/catalogers/backstage-catalog-info@v1.12.0
with:
default_domain: engineering
# Monorepo subcomponents, one per discovered catalog-info.yaml.
- uses: github://earthly/lunar-lib/catalogers/backstage-catalog-info-monorepo@v1.12.0
with:
orgs: acme
allowed_topics: monorepo
```
{% endcode %}
Running those two together is the intended monorepo setup: the first owns the repository-level component, the second adds the subcomponents. The monorepo cataloger's `exclude_paths` default skips the root entry, so the two never write the same component id.
If you sync from the Backstage API instead, `component_id_annotation` is the bridge between your catalog's identity and Lunar's — and, per [Component identity](#where-the-subdirectory-comes-from) above, its default of `github.com/project-slug` is repo-level only. Point it at a field that carries the subdirectory before running it against a monorepo.
For a home-grown catalog you write the cataloger yourself. Here is a basic example.
{% code title="lunar-config.yml — central metadata repo" %}
```yaml
catalogers:
- name: central-catalog
runBash: |-
cat domains.yaml | yq -o=json | lunar catalog raw --json '.domains' -
cat services.yaml | yq -o=json | lunar catalog raw --json '.components' -
hook:
type: repo
repo: github://acme/software-catalog
```
{% endcode %}
#### Mapping onto Lunar's model
Three mapping decisions are worth making deliberately:
**Domains.** Lunar's domains are hierarchical and dotted (`engineering.payments.ledger`). If your catalog expresses hierarchy by reference rather than by path — Backstage's `subdomainOf` and `spec.system`, for example — the cataloger has to resolve those references into a dotted path. Sync every level of the hierarchy, or a reference to an unsynced parent falls back to a bare name and the tree flattens.
**Tags.** Namespace imported tags with a prefix, which the shipped catalogers do by default (`bs-` for Backstage, `gh-` for GitHub topics). This keeps imported data distinguishable from tags you assign deliberately, and it doubles as gap detection: a component carrying `gh-` tags but no `bs-` tags is provably absent from Backstage, and `on:` supports `NOT`, so you can target exactly that population.
**Precedence.** Catalogers merge in declaration order, last one wins, and then `lunar.yml` 🚧 Coming Soon and `lunar-config.yml` are applied on top. Declare the broad, low-confidence source first and the specific, high-confidence source last.
`lunar-config.yml` being the highest-precedence layer is what gives the central platform team a way to augment and correct the catalog without waiting on the upstream system. The merge is per field, so setting `owner` on a component there overrides just that field — the domain, tags, and everything else keep tracking the cataloger. Use it to pin a value you know the upstream has wrong, or to add metadata the upstream cannot express, and leave the rest to sync.
### 3.2 Validate the ingested catalog
*Optional.*
Structural validity is not the same as being correct. Once the data is flowing, add policies for the semantics that only matter because Lunar now depends on them.
{% code title="lunar-config.yml — Backstage example" %}
```yaml
policies:
- uses: github://earthly/lunar-lib/policies/backstage@v1.12.0
name: catalog-semantics
initiative: cataloging
on: ["domain:engineering"]
include: [domain-exists, system-exists, required-annotations, required-tag-patterns]
with:
required_tag_patterns: "tier/*,data-classification/*"
enforcement: report-pr
```
{% endcode %}
The checks worth having here are referential integrity — a component pointing at a domain or system that does not exist — and required tag patterns, which is how you force the classification decisions that scoping depends on. Requiring a `data-classification/*` tag makes every team state whether their service handles sensitive data, which is exactly the input you need before you can scope a compliance guardrail to it.
### 3.3 Enrich with heuristics
*Optional, and the highest-leverage of the optional steps if large parts of your catalog are unclassified.*
Some of what you need to know was never written down anywhere. Rather than asking every team to backfill it, derive it.
A `component-cron` cataloger can read a component's accumulated [Component JSON](/docs/component-json) and classify from evidence Lunar already collected — a deployment in a production Kubernetes namespace, a release pipeline that has actually run, an ingress reachable from the internet:
{% code title="lunar-config.yml" %}
```yaml
catalogers:
- name: production-detection
description: Tag components with observed production deployments
runBash: |-
JSON="$(lunar component get-json "$LUNAR_COMPONENT_ID")"
if echo "$JSON" | jq -e '.k8s.deployments[]? | select(.namespace == "prod")' >/dev/null; then
lunar catalog raw --json ".components.\"$LUNAR_COMPONENT_ID\".tags" '["production"]'
fi
hook:
type: component-cron
schedule: "0 3 * * *"
```
{% endcode %}
A `component-repo` cataloger with `clone-code: true` does the same from repository signals rather than collected data — the presence of a deploy workflow, a Helm chart, a Terraform production variable file.
Treat heuristics as a supplement, not a replacement. Where a heuristic and a declared value disagree, that disagreement is itself worth a check: a component that deploys to production but is declared `experimental` is a catalog defect, and often an interesting one.
### 3.4 Declare paths for monorepo components
*Optional, and only relevant if you have monorepos.*
The `paths` field tells Lunar which file changes affect which component. In a monorepo, this determines whether a component's collectors run at all when a commit lands.
A monorepo component automatically gets an implicit `/*` pattern derived from its own name, and by default that is the whole of its trigger set. A component whose only pattern is `services/payments/*` **will not re-evaluate** when a shared library it depends on changes. Its checks stay green against stale data. The commit is recorded as handled for that component rather than left pending, so nothing hangs and nothing warns — the result is simply out of date.
`paths` is how you widen that set. The implicit subdirectory pattern is always present, so entries you add are **additional** triggers on top of it: in a monorepo, `paths` only ever expands what the component reacts to, and can never narrow it below its own subdirectory. Declare the shared code and configuration that should also trigger re-evaluation:
{% code title="lunar-config.yml" %}
```yaml
components:
github.com/acme/monorepo/services/payments:
paths:
- libs/common/* # shared library the service depends on
- build/bazel/* # shared build configuration
- catalog-info.yaml # shared catalog file at the repo root
```
{% endcode %}
Matching is deliberately simple: a single trailing `*` is a string prefix match, and an entry without one must match a changed path exactly.
{% hint style="info" %}
The one case where `paths` narrows rather than widens is a **repository-level** component — one with no subdirectory in its name, and so no implicit pattern. Those match every change by default, and setting `paths` on one restricts it to just the entries you list. Worth knowing, but it is the opposite of the monorepo case above and rarely what you want.
{% endhint %}
**Who should own this.** The people who know which shared code a component depends on are the component's owners, not the platform team. Maintaining these lists centrally in `lunar-config.yml` does not scale and goes stale immediately. Put the field in the catalog file the team already edits — `catalog-info.yaml`, `lunar.yml` 🚧 Coming Soon, or your internal equivalent — and wire it through the pipeline you have already built:
* **Step 2.1** collects the declared paths along with the rest of the entry.
* **Step 2.2** validates them: correct type, paths that exist, no attempt to reach outside the repository.
* **Step 3.1** emits them to `.components[""].paths` so Lunar's change detection actually uses them.
Without that last wiring the field is inert documentation. It has to reach the Catalog JSON to have any effect.
## Putting it together
{% code title="lunar-config.yml" %}
```yaml
version: 0
hub:
host: lunar.acme.com
grpcPort: 443
httpPort: 443
default_image: earthly/lunar-scripts:1.0.0
domains:
engineering:
description: Acme engineering
owner: platform@acme.com
catalogers:
# 1.1 Coverage floor: every repo becomes a component.
- uses: github://earthly/lunar-lib/catalogers/github-org@v1.12.0
with:
org_name: acme
default_owner: platform@acme.com
default_domain: engineering
# 3.1 Existing catalog, mapped onto Lunar's model.
- uses: github://earthly/lunar-lib/catalogers/backstage-catalog-info@v1.12.0
- uses: github://earthly/lunar-lib/catalogers/backstage-catalog-info-monorepo@v1.12.0
with:
orgs: acme
allowed_topics: monorepo
# 3.3 Classification derived from collected evidence.
- name: production-detection
runBash: |-
JSON="$(lunar component get-json "$LUNAR_COMPONENT_ID")"
if echo "$JSON" | jq -e '.k8s.deployments[]? | select(.namespace == "prod")' >/dev/null; then
lunar catalog raw --json ".components.\"$LUNAR_COMPONENT_ID\".tags" '["production"]'
fi
hook:
type: component-cron
schedule: "0 3 * * *"
collectors:
# 2.1 Raw catalog entries into the Component JSON.
- uses: github://earthly/lunar-lib/collectors/backstage@v1.12.0
on: ["domain:engineering"]
initiatives:
- name: cataloging
description: Catalog completeness and correctness
owner: platform@acme.com
on: ["domain:engineering"]
policies:
# 2.2 + 2.3 Structure, identity, and coverage.
- uses: github://earthly/lunar-lib/policies/backstage@v1.12.0
name: catalog-structure
initiative: cataloging
on: ["domain:engineering"]
include: [catalog-info-exists, catalog-info-valid, owner-set, lifecycle-set, system-set]
enforcement: report-pr
# 3.2 Semantics, once the structure is clean.
- uses: github://earthly/lunar-lib/policies/backstage@v1.12.0
name: catalog-semantics
initiative: cataloging
on: ["domain:engineering"]
include: [domain-exists, system-exists, required-tag-patterns]
with:
required_tag_patterns: "tier/*,data-classification/*"
enforcement: score
```
{% endcode %}
## See also
* [Catalogers](/configuration/lunar-config/catalogers) and [cataloger hooks](/configuration/lunar-config/cataloger-hooks) — configuration reference
* [Components](/configuration/lunar-config/components) — naming rules, `paths`, and CI attribution
* [Domains](/configuration/lunar-config/domains) — hierarchy and ownership
* [Catalog JSON](/docs/catalog-json) — the merged structure and its precedence rules
* [Tag Matching with `on`](/configuration/lunar-config/on) — targeting expressions
* [Cataloger Bash SDK](/plugin-sdks/bash-sdk/cataloger) — the `lunar catalog` command
* [AI Skills](/install/skills) — agent skills for writing catalogers, collectors, and policies
# 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": {
"": "",
...
}
},
...
}
}
```
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 host name of the Lunar Hub. This setting is inferred from the Lunar config if not specified.
Correct:
* `hub.example.com`
* `myhost`
Incorrect:
* `https://hub.example.com`
* `http://hub.example.com`
* `hub.example.com:8080`
* `myhost:443`
### `--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` (or `LUNAR_GITLAB_TOKEN`, for components on GitLab) must be set if GitHub or GitLab 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/lunar-hub/self-hosted/sync-config) 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:///[/]@` or `gitlab:////[/-/]@`
* 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`
* `gitlab://gitlab.com/acme-corp/lunar@main`
* `gitlab://gitlab.example.com/acme-corp/platform/lunar@main`
The GitLab form requires an explicit host, including for `gitlab.com`, and the namespace may contain subgroups.
The optional `` selects which configuration file to load, so one repository can hold several — one per Hub or per environment — and a monorepo can keep its configuration somewhere other than the root. It may name the file itself (`github://acme-corp/lunar/lunar-config.dev.yml@main`) or a directory holding a `lunar-config.yml` (`github://acme-corp/lunar/configs/dev@main`). Omitted, the entry point is `lunar-config.yml` at the repository root.
A local filesystem path is also accepted, and may likewise name either a directory or the configuration file inside it — useful with `--dry-run`.
#### `--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 the entry point + its 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 or GitLab access to resolve `uses:` plugins (set `LUNAR_GITHUB_TOKEN` or `LUNAR_GITLAB_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`
{% hint style="warning" %}
**Deprecated — use** [**`lunar collector run`**](#lunar-collector-run)**.** That command covers cron collectors as well, and can scope a rerun to one component, PR, or commit. `lunar collector run --only-code` is the closest equivalent.
This command still works and is not scheduled for removal. It remains the only collector trigger available against a Lunar Hub older than the release that added `lunar collector run`, and it is currently the only way to sweep primary-branch commits *without* also covering recent PR commits.
{% endhint %}
* 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. Combined with `--git-sha`, it narrows the lookup to that commit as seen in that PR; a `--git-sha` on its own resolves the commit whether it was reached through the primary branch or a PR.
#### `--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`
* 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.
Collectors are dispatched asynchronously, so the command reports what it triggered rather than waiting for results. Read the outcome with [`lunar component get-json`](#lunar-component-get-json) once the collectors have run.
{% hint style="info" %}
**Naming a collector that isn't in the current manifest is an error.** Lunar Hub checks the names given to `--collector` before dispatching anything, so a typo fails the command instead of quietly running nothing.
{% endhint %}
#### ``
* Type: `string`
* Optional
The name of the component to rerun collectors for. Omit it to cover every component, across both code and cron collectors. The code leg also covers recent PR commits, bounded by `--pr-max-age-days`.
{% hint style="warning" %}
**Omitting the component name can trigger a large amount of work in Lunar Hub.** It reruns collectors across every component, which can produce a significant backlog and elevated load.
Naming a component is the only way to bound both legs. `--pr-max-age-days` bounds the code leg alone: the cron leg fans out over every open pull request of every component it matches, capped per component rather than by age.
{% endhint %}
#### `--pr `
* Type: `integer`
* Optional
The PR number to rerun collectors for. If not specified, collectors will be run for the component's primary branch. Requires a component name, since the PR is resolved against that component's repository.
#### `--git-sha `
* Type: `string`
* Optional
The specific git SHA to rerun collectors for. If specified, this takes precedence over `--pr`. Requires a component name, and the commit must be one Lunar Hub has already ingested for that component's repository.
#### `--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. A name matches a collector exactly, or matches every sub-collector of a plugin: `--collector trivy` selects `trivy.auto` and `trivy.rescan`.
#### `--pr-max-age-days `
* Type: `integer`
* Optional
* Default: `5`
Ignore PR commits older than this maximum number of days. Only consulted for the fleet-wide **code** sweep, which covers recent PR commits as well as each repository's primary branch. Cron collectors ignore it, so it has no effect at all under `--only-cron`.
#### `--output-json`
Output the results in JSON format: one object per triggered run, carrying `component`, `collector`, `source` (`code` or `cron`), `repo_uri`, `commit_sha`, and `pr`. A run that Lunar Hub deduplicated onto an identical run already in flight is reported with `already_pending: true` rather than omitted, so an empty array means nothing matched.
Example:
```bash
# Rerun all collectors for all components for all PRs, limiting 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 a cron collector now, without waiting for its next tick
lunar collector run --only-cron --collector pagerduty.oncall 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.
{% hint style="warning" %}
`--pr` requires a GitHub connection and is not available for components on GitLab — the command exits with an error. Use `--git-sha`, or the component's branch, instead.
{% endhint %}
#### `--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 or GitLab 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 a token** — `LUNAR_GITHUB_TOKEN`, or `LUNAR_GITLAB_TOKEN` for a component on GitLab. 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