Lunar CI Agent

Installing the Lunar CI Agent

The Lunar CI Agent is used to instrument CI/CD pipelines and collect metadata during builds, tests, scans, and deployments. It is typically installed as a step in your CI configuration.

GitHub Actions (Managed Runners)

To instrument pipelines on GitHub Actions (managed runners), insert the following step in your workflow.

Include the required environment variables for your installation (see below for the full list and their descriptions):

- name: Run Lunar CI Agent
  uses: earthly/lunar-ci-action@v1
  env:
    LUNAR_GITHUB_TOKEN: ${{ secrets.LUNAR_GITHUB_TOKEN }}
    LUNAR_HUB_TOKEN: ${{ secrets.LUNAR_HUB_TOKEN }}
    # See below for the full list of environment variables and optional settings

Self-Hosted Runners

For self-hosted runners (including GitHub Actions self-hosted), you'll need to manually install the Lunar CI Agent from a GitHub release and run it using the binary lunar. Follow these steps:

1. Download the latest release (replace with appropriate download command):

   curl -LO https://github.com/earthly/lunar-dist/releases/download/v1.0.0/lunar-linux-amd64

2. Move the binary to somewhere on your path and make it executable:

   sudo chmod +x lunar-linux-amd64 && mv ./lunar-linux-amd64 /usr/local/bin/lunar

3. Set required and optional environment variables:

   The Lunar CI Agent requires several environment variables to function properly. Set them in your environment or in a file:

   # Required
   export HUB_LOGS_AWS_BUCKET=your_logs_bucket
   export LUNAR_GITHUB_TOKEN=your_github_token
   export LUNAR_HUB_TOKEN=your_hub_token
   export LUNAR_HUB_HOST=your_hub_host
   export LUNAR_HUB_GRPC_PORT=your_grpc_port
   export LUNAR_HUB_HTTP_PORT=your_http_port
   
   # Optional: logs integration
   export LUNAR_ELASTIC_URL=your_elastic_url
   export LUNAR_ELASTIC_API_KEY=your_elastic_api_key
   export LUNAR_TENANT_ID=your_tenant_id
   
   # Optional (defaults shown)
   export LUNAR_STATE_DIR=/var/lib/lunar
   export LUNAR_LOG_LEVEL=info
   export LUNAR_LOG_FORMAT=json
   export LUNAR_UPDATE_PERIOD=60s

4. Configure the CI Agent:

   See the below section for full details.

5. Start the Lunar CI Agent:

   LUNAR_RUN_CMD="/path/to/github/runner/run.sh" lunar

   For production usage, consider running and monitoring the lunar process with a process supervisor such as systemd. This helps ensure the agent is automatically restarted if it fails. See the Systemd configuration page for guidance on creating a unit file.

Configuring the CI Agent

You can configure the Lunar CI Agent to pull and apply a primary lunar-config.yml configuration file from a GitHub repository, similar to the Hub’s configuration. This is done using the lunar install github://... command, which should be run on the CI agent machine.

lunar install github://repo-name/project-name@branch-or-sha

Examples:

Pulling from a specific branch:

lunar install github://acme-corp/ci-config@main

Pulling from a specific commit SHA:

lunar install github://acme-corp/ci-config@de4adbeef

This command downloads the lunar-config.yml from the specified repo and reference, and configures the agent accordingly before running CI tasks.

---

Next Steps

Once installed, you can begin configuring:

• Collectors to gather SDLC data

• Policies to enforce standards

• Domains and Components to organize your software landscape

For questions or enterprise onboarding, contact the Earthly team.