Lunar CI Tracer

A GitHub Action that installs the Lunar CLI, and uses it to run the CI tracer. The tracer instruments your workflow, triggering collectors and policies at the appropriate points during execution.

Add the action as an early step in your workflow:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Run Lunar CI Tracer
        id: lunar
        uses: earthly/lunar-ci-tracer@v4.8.0
        env:
          LUNAR_HUB_TOKEN: ${{ secrets.LUNAR_HUB_TOKEN }}
          LUNAR_HUB_HOST: your_hub_host

      - uses: actions/checkout@v4
      # ... rest of your workflow

The action installs the Lunar CLI (by default, the latest version available at the time the action release was created) and invokes lunar ci-tracer run, which fetches the agent binary through your Lunar Hub on first use (caching it in ~/.lunar/bin), verifies it, and attaches it to the workflow process. All subsequent steps are automatically instrumented. The Hub must be reachable when the action starts.

Downstream steps can branch on it:

- name: Run checks that need the tracer
  if: steps.lunar.outputs.agent-installed == 'true'
  run: ./run-traced-tests.sh

All configuration is passed via environment variables.

Agent installation failures (CLI download, agent download through the Hub, agent startup) are gated by LUNAR_STRICT_MODE:

• LUNAR_STRICT_MODE=true: the step fails with the error output.
• Unset or false (default): the action emits an ::error:: annotation plus a warning, sets agent-installed to false, and the step succeeds so the rest of the job continues without instrumentation.

The action runs as a job step. It downloads the lunar CLI and shells out to lunar ci-tracer run, which fetches the agent binary through your Hub on first use and execs it. The agent attaches to the current shell process via ptrace and traces all commands executed by subsequent steps in the same job.

The agent exits automatically when the job completes.

• Linux x86_64 runners (GitHub-hosted or self-hosted).
• Network access from the runner to your Lunar Hub.

Copyright Earthly Technologies, Inc. All rights reserved.