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, 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 action pushes the latest config (manifest + snippets) from your config repo into Lunar Hub.

First time setting up a config repo? Fork earthly/lunar-config-template — it ships with this workflow pre-wired so you only need to set the LUNAR_HUB_TOKEN secret and push.

The action's inputs map 1:1 to the equivalent CLI flags — see the CLI reference for the full semantics of each.

Example

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	—	<repo> positional argument (github://<org>/<repo>@<branch>)
hub-token	yes	—	LUNAR_HUB_TOKEN env var
hub-host	yes	—	LUNAR_HUB_HOST env var
lunar-version	yes	—	Selects the lunar-dist 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)
log-level	no	debug	LUNAR_LOG_LEVEL env var

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.

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 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:

.gitlab-ci.yml

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"

Set LUNAR_HUB_TOKEN as a masked CI/CD variable on the project or group (Settings → CI/CD → Variables), not in the file.

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.

Useful flags

lunar hub pull accepts several options that change what happens after the config lands. The full list is in the CLI reference; 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:

.gitlab-ci.yml

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"

The token needs read access to the config repository and to any repositories its plugins come from. See Validating your config.