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:

Installed Lunar following the installation guide
Access to your code repositories
Basic understanding of your CI/CD pipeline setup

Basic Concepts

Lunar operates on a few key concepts:

Components: These are your software projects (services, libraries, repositories)
Collectors: These gather information about your components
Policies: These define rules and standards for your components
Checks: These are the results of policy evaluations

Your First Lunar Setup

Populate your Lunar configuration

Start by creating a lunar-config.yml file in your project root:

lunar-config.yml

version: 0

hub:
  host: <host>
  grpcPort: <grpc-port>
  httpPort: <http-port>

# 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: []

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.

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 for the naming rules.

Lunar can also auto-discover components from external systems like GitHub, Backstage, and other sources using catalogers. See the catalogers documentation for details on setting up automated component discovery. For now, this example will focus on manually declared components.

Commit this code to a new repository called lunar. To apply this configuration, run the following command:

# 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.

Define your first policy

Add a policy to check your component:

lunar-config.yml

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")

Since we're using the official earthly/lunar-scripts image (via default_image), the Lunar Policy SDK is already pre-installed—no requirements.txt needed.

Commit the code, and apply the new configuration:

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.