Earthly - How Lunar Works

How Lunar Works

Automated engineering standards enforcement in minutes

⚙️ Integration Points

Instrumentation
at Scale

Lunar instruments all your code repositories and CI/CD pipelines in a central manner.

No repo-by-repo integration needed.

View installation docs →

GitHub App

Integration Point #1

• Reacts to code changes

• Provides PR feedback

Provides access to

📄 Source code

🔧 Tech-specific config files

📋 Dependencies & manifests

🔀 Repository metadata

CI/CD Agent

Integration Point #2

• Runs alongside CI/CD runners

• Detects pipeline processes via syscalls

Compatible with all major CI vendors

Detects globally

✅ Test runs

🔍 Security scans

📦 Build artifacts & SBOMs

🛠️ Tool versions

⚡ Execution Flow

Once instrumented, Lunar automatically runs these steps on every code change

Automatic Data Collection

Collect application metadata from:

• Code and configuration files
• Tools used in CI/CD
• Registries and Artifactories coming soon

Centralized SDLC data as JSON

A structured JSON document reflects the overall posture of each application in rich detail.

The normalized data is stored in a central database.

{
    "repo": {                           },
    "k8s": {                            },
    "helm": {                           },
    "iac": {                            },
    "dockerfiles": {                    },
    "testing": {                        },
    "sbom": {                           },
    "security": {                       },
    ...
}

Real-time Guardrail Feedback

Guardrails define practices to enforce. Lunar's guardrails-as-code verifies that each application's JSON SDLC data abides by defined standards.

Real-time guardrail feedback is provided on every code change, directly in developer PRs.

Some checks were not successful

The Result?

Standards that enforce themselves.
No manual checklists. No forever‑backlogged tickets.
No release‑day surprises.

Minutes

Not quarters

100%

Accidental rubber-stamping eliminated

30x

More standards enforced

Why Not Use CI Only?

↓

Book a Demo with Your Own Use Cases

→

Example Guardrails

Real standards you can enforce in minutes, not months

Guardrail Categories

Ensure CODEOWNERS File Exists and Is Valid Example

Step 1: Collect the data

- on: [all-services]
  hook:
    type: code
  runBash: |-
    # Download codeowners-validator
    # from github.com/mszostok/codeowners-validator
    curl -L ...

    # Check if CODEOWNERS file doesn't exist
    if [ ! -f .github/CODEOWNERS ]; then
      lunar collect ".repo.codeowners.exists" false
      exit 0
    fi
    lunar collect ".repo.codeowners.exists" true

    # Validate CODEOWNERS file syntax and format
    if ! codeowners-validator -c .github/CODEOWNERS > validation_output.txt 2>&1; then
      lunar collect ".repo.codeowners.valid" false
      error=$(cat validation_output.txt)
      lunar collect ".repo.codeowners.validation_error" "$error"
    else
      lunar collect ".repo.codeowners.valid" true
    fi

    # Count teams referenced in CODEOWNERS
    teams=$(grep -oP '@\S+' .github/CODEOWNERS | sort -u | wc -l)
    lunar collect ".repo.codeowners.teams_count" "$teams"

Download and use the codeowners-validator tool to check if CODEOWNERS file exists, validate its syntax and format, and count the number of teams assigned.

Step 2: Enforce the guardrail

- enforcement: block-pr
  runPython: |-
    with Check("codeowners", "CODEOWNERS file must be valid") as c:
      c.assert_equals(".repo.codeowners.exists", True)
      is_valid = c.get(".repo.codeowners.valid", False)
      if not is_valid:
        validation_error = c.get(".repo.codeowners.validation_error", "Unknown validation error")
        c.fail(f"CODEOWNERS file validation failed: {validation_error}")

      teams_count = c.get(".repo.codeowners.teams_count", 0)
      if teams_count == 0:
        c.fail("CODEOWNERS file must reference at least one team")

Enforce that all repositories have a valid CODEOWNERS file with at least one team assigned. The validator checks syntax, format, and references.

K8s Manifest Must Define Resource Requirements Example

Step 1: Collect the data

- on: [all-services]
  hook:
    type: code
  runBash: |-
    yq e -o=j -I=0 \
      '.spec.template.spec.containers[].resources' \
      deployment.yaml | jq -s | lunar collect ".kubernetes.deployment.resources" -

Extract resource specifications from Kubernetes deployment manifests.

Step 2: Enforce the guardrail

- enforcement: block-pr
  runPython: |-
    with Check("k8s", "K8s manifest must define resource requirements") as c:
      c.assert_exists(".kubernetes.deployment.resources.requests.cpu")
      c.assert_exists(".kubernetes.deployment.resources.requests.memory")

Verify that CPU and memory resource requests are defined. Block the PR if missing.

Code Coverage Standards Example

Step 1: Collect the data

- on: [all-services]
  hook:
    type: ci-after-command
    pattern: ^codecov.*
  runBash: |-
    lunar collect "codecov.ran" true

Detect if the CodeCov process (pattern: ^codecov.*) is being run in a CI pipeline.

Step 2: Enforce the guardrail

- enforcement: block-pr
  runPython: |-
    with Check("codecov", "Test coverage") as c:
      c.assert_exists(".codecov.ran")

Enforce that all services run CodeCov. Block the PR if not used.

Prevent Dockerfile :latest Tags Example

Step 1: Collect the data

- on: [all-services]
  hook:
    type: code
  runBash: |-
    # Download dockerfile-json
    # from github.com/keilerkonzept/dockerfile-json
    curl -L ...
    
    # Find all Dockerfiles and parse them into JSON ASTs
    find . -name 'Dockerfile' -o -name '*.Dockerfile' | while read -r file; do
      json=$(dockerfile-json "$file")
      echo "{\"path\":\"${file#./}\", \"json\": $json}"
    done > dockerfiles.json
    
    # Combine into an array
    jq -s '.' dockerfiles.json > dockerfile_asts.json
    
    # Extract referenced base images
    jq '[.[] | {path: .path, tags: [((.json.Stages // [])[] | (.From.Image // empty))]}]' \
      dockerfile_asts.json | lunar collect -j ".dockerfile.images" -

Collect all images referenced in FROM statements in all Dockerfiles.

Step 2: Enforce the guardrail

- enforcement: block-pr
  runPython: |-
    with Check("dockerfiles", "Prevent Dockerfile :latest tags") as c:
      imgs = c.get(".dockerfile.images")
      for dockerfile in imgs:
        for image in dockerfile.get("tags", []):
          if ":latest" in image:
            path = dockerfile.get("path", "")
            c.fail(f'File \"{path}\" contains images with \"latest\" tag: \"{image}\"')

Check that no image uses :latest. Block the PR if it does.

Ensure That Production Services Use Snyk Example

Step 1: Collect the data

collectors:
  - on: [all-services]
    hook:
      type: ci-before-command
      pattern: ^snyk.*
    runBash: |-
      lunar collect ".snyk.ran" true

Detect if Snyk security scanning is being run in the CI pipeline.

Step 2: Enforce the guardrail

- enforcement: score
  runPython: |-
    with Check("use-snyk", "Must use Snyk") as c:
      c.assert_exists(".snyk.ran")

Enforce that all production services run Snyk security scans.

Verify Structured Logging Configuration Example

Step 1: Collect the data

- on: [all-services]
  hook:
    type: code
  runBash: |-
    # Check for structured logging libraries
    if grep -qE "(winston|pino|bunyan)" package.json 2>/dev/null || \
       grep -qE "(logrus|zap)" go.mod 2>/dev/null || \
       grep -qE "(structlog|python-json-logger)" requirements.txt 2>/dev/null; then
      lunar collect ".observability.structured_logging.enabled" true
    else
      lunar collect ".observability.structured_logging.enabled" false
    fi

Detect if structured logging libraries are configured in the service dependencies.

Step 2: Enforce the guardrail

- enforcement: block-pr
  runPython: |-
    with Check("structured-logging", "Structured logging must be enabled") as c:
      c.assert_equals(".observability.structured_logging.enabled", True,
        message="Production services must use structured logging (winston, pino, logrus, zap, or structlog)")

Enforce that all production services use approved structured logging libraries.

NIST SSDF: Verify SBOM Generation Example

Step 1: Collect the data

- on: [all-services]
  hook:
    type: ci-after-command
    pattern: ^(syft|cyclonedx|trivy).*sbom.*
  runBash: |-
    lunar collect ".compliance.sbom.generated" true
    # Extract SBOM format if available
    if echo "$COMMAND" | grep -q "cyclonedx"; then
      lunar collect ".compliance.sbom.format" "cyclonedx"
    elif echo "$COMMAND" | grep -q "spdx"; then
      lunar collect ".compliance.sbom.format" "spdx"
    fi

Detect SBOM generation in CI pipelines using tools like Syft, CycloneDX, or Trivy.

Step 2: Enforce the guardrail

- enforcement: block-pr
  runPython: |-
    with Check("nist-ssdf-sbom", "NIST SSDF: SBOM must be generated") as c:
      c.assert_exists(".compliance.sbom.generated",
        message="NIST Secure Software Development Framework requires SBOM generation")
      sbom_format = c.get(".compliance.sbom.format", None)
      if sbom_format not in ["cyclonedx", "spdx"]:
        c.fail("SBOM must use CycloneDX or SPDX format")

Enforce NIST SSDF compliance by requiring SBOM generation in standard formats.

Ensure Public APIs Are Well-Documented Example

Step 1: Collect the data

- on: [all-services]
  use: github.com/earthly/lunar-lib/collectors/claude
  with:
    prompt: Analyze this codebase and identify all public APIs (exported functions, public methods, HTTP endpoints, etc.). For each API, provide 1. The API name (function/method/endpoint name), 2. File path where it's defined, 3. Line number where it starts, 4. A brief summary of what it does, 5. A documentation score from 0 to 1. Consider docstrings, inline comments, parameter descriptions, return value documentation, and usage examples.
    path: ".apis.public"
    jsonSchema: ...

Use Claude AI to analyze the codebase and evaluate documentation quality for all public APIs, scoring each on a 0-1 scale.

Step 2: Enforce the guardrail

- enforcement: report-pr
  runPython: |-
    with Check("api-documentation", "Public APIs must be well-documented") as c:
      for api in c.get(".apis.public", []):
        score = api.get("documentation_score", 0)
        c.assert_greater(score, 0.5, message=f"{api['name']} at {api['file_path']}:{api['line_number']} has score {score:.2f}")

Report in a PR comment if any public API has a documentation score below 0.5, providing detailed feedback on which APIs need better documentation.

Explore the Docs

Define your own standards

→

Make a New Guardrail

Watch the 5-minute video

100+ Guardrails Off the Shelf

100+ pre-built guardrails across Dockerfiles, Kubernetes, Terraform, CI/CD, security, and compliance.

Plus: Custom guardrail builder to codify your unique standards.

Earthly Lunar is a Guardrails Engine for your Engineering Stack

How Lunar Works

⚙️ Integration Points

Instrumentation
at Scale

⚡ Execution Flow

Automatic Data Collection

Centralized SDLC data as JSON

Real-time Guardrail Feedback

The Result?

Example Guardrails

Guardrail Categories

Ensure CODEOWNERS File Exists and Is Valid Example

K8s Manifest Must Define Resource Requirements Example

Code Coverage Standards Example

Prevent Dockerfile :latest Tags Example

Ensure That Production Services Use Snyk Example

Verify Structured Logging Configuration Example

NIST SSDF: Verify SBOM Generation Example

Ensure Public APIs Are Well-Documented Example

100+ Guardrails Off the Shelf

Gradual Enforcement

Configure Per Guardrail

Make a New Guardrail in 5 Minutes

Why Not Just Use CI?

❌ CI Only

✅ Earthly Lunar

Ready to Automate Your Standards?

Earthly Lunar is a Guardrails Engine for your Engineering Stack

How Lunar Works

⚙️ Integration Points

Instrumentationat Scale

⚡ Execution Flow

Automatic Data Collection

Centralized SDLC data as JSON

Real-time Guardrail Feedback

The Result?

Example Guardrails

Guardrail Categories

Ensure CODEOWNERS File Exists and Is Valid Example

K8s Manifest Must Define Resource Requirements Example

Code Coverage Standards Example

Prevent Dockerfile :latest Tags Example

Ensure That Production Services Use Snyk Example

Verify Structured Logging Configuration Example

NIST SSDF: Verify SBOM Generation Example

Ensure Public APIs Are Well-Documented Example

100+ Guardrails Off the Shelf

Repository and Ownership

Deployment and Infrastructure

Testing and Quality

DevEx, Build and CI

Security and Compliance

Operational Readiness

Gradual Enforcement

Configure Per Guardrail

Make a New Guardrail in 5 Minutes

Why Not Just Use CI?

❌ CI Only

✅ Earthly Lunar

Ready to Automate Your Standards?

Instrumentation
at Scale