> For the complete documentation index, see [llms.txt](https://docs-lunar.earthly.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-lunar.earthly.dev/install/lunar-hub/self-hosted/sync-config.md). # Sync Config 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.md#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.md#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.md#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.md#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.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs-lunar.earthly.dev/install/lunar-hub/self-hosted/sync-config.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.