Managed Runners

Use the Lunar CI Tracer action to instrument GitHub-hosted and self-hosted GitHub Actions runners with the Lunar CI Agent.

The earthly/lunar-ci-tracer action is the easiest way to add the Lunar CI Agent to your GitHub Actions workflows. It works with both GitHub-hosted and self-hosted runners.

For GitHub-hosted runners (managed runners), this action is the only installation method — you cannot modify the runner startup process.

For self-hosted runners, you can either use this action or configure the agent to wrap the runner's run.sh command directly, which avoids adding a step to every job.

Setup

Add the Lunar CI Tracer action as an early step in your workflow jobs:

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

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

The action installs the lunar CLI for you (no pre-install step needed) and runs lunar ci-tracer run, which fetches the agent through your Lunar Hub on first use, verifies it, and attaches it to the job process. All subsequent steps in the job are automatically instrumented. Your Hub must be reachable when the action starts.

How It Works

The action runs as a step in a job. It downloads the lunar CLI, then runs lunar ci-tracer run, which fetches the agent 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. The agent exits automatically when the job completes.

The same configuration reference applies. The only difference is that LUNAR_RUN_CMD is not needed — the action handles process supervision internally.

For self-hosted runners that require the use of sudo in workflows, the CAP_SYS_ADMIN capability should be provided — see Running sudo and setuid binaries in traced workflows.

Failure Handling

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 the agent-installed output to false, and the step succeeds so the rest of the job continues uninstrumented.

The action exposes an agent-installed output ('true' / 'false') so downstream steps can branch on whether instrumentation is active:

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