Managed Runners
Use the Lunar CI Tracer action to instrument GitHub-hosted and self-hosted GitHub Actions runners with the Lunar CI Agent.
Last updated
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.
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 workflowThe 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.
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.
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:
Last updated
- name: Run checks that need the tracer
if: steps.lunar.outputs.agent-installed == 'true'
run: ./run-traced-tests.sh