Configuration Reference
Reference for all environment variables that configure the Lunar CI Tracer, including required settings, Docker options, and state directories.
Required
LUNAR_HUB_TOKEN
Auth token for your Hub installation.
LUNAR_HUB_HOST
Hostname of your Hub installation. Must be reachable from the runner.
LUNAR_HUB_GRPC_PORT
Hub's gRPC port. Used for configuration sync, collection results, and SCM token resolution.
LUNAR_HUB_HTTP_PORT
Hub's HTTP port. Used for log uploads and script downloads.
LUNAR_CI_TYPE
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 GitHub Action.
Optional
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 <host> in <host>/<org>/<repo> component names). Auto-detected from GITHUB_SERVER_URL when the tracer runs as a GitHub Actions step (including via the Lunar CI Tracer action), 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).
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.
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.
Last updated