Run in CI
Last updated on November 16, 2026
A CI runner that is rebuilt for every job has no stored login, so the CLI reads its key from the TOFUPILOT_API_KEY environment variable instead. The job runs the procedure without prompts, uploads the run as a station, and exits with the run's outcome, so a failed test fails the job.
Step 1: Create a station API key
Create a station for the runner, or for a pool of runners that share it, then create an API key on the station page under API Keys. A station key can only act as that station, and it can be created without an expiry date.
Save the key as a secret in your CI provider, under the name TOFUPILOT_API_KEY. Pass the key through the environment, not on the command line: a command line shows in process lists and job logs.
Step 2: Name the procedure
A run --upload needs to know which procedure it uploads to. On a developer machine, tofupilot link writes it to tofupilot.json. In CI, either commit that file with the procedure, or set TOFUPILOT_PROCEDURE_ID, which takes precedence.
The procedure must also be linked to the station. The server refuses a station's upload to a procedure it is not linked to: the job still exits with the run's outcome, and the run stays in the runner's queue.
Step 3: Run the procedure in the job
jobs:
hil:
runs-on: [self-hosted, hil-bench]
steps:
- uses: actions/checkout@v4
- run: curl -fsSL https://www.tofupilot.app/install | sh
- run: tofupilot run ./procedures/cb100 --upload --ui-values ui.json --ui-timeout 300 --json
env:
TOFUPILOT_API_KEY: ${{ secrets.TOFUPILOT_API_KEY }}
TOFUPILOT_PROCEDURE_ID: <procedure id>hil:
tags: [hil-bench]
script:
- curl -fsSL https://www.tofupilot.app/install | sh
- tofupilot run ./procedures/cb100 --upload --ui-values ui.json --ui-timeout 300 --json
variables:
TOFUPILOT_PROCEDURE_ID: "<procedure id>"
# TOFUPILOT_API_KEY is a masked CI/CD variable of the project.| Flag | Why in CI |
|---|---|
--upload | Uploads the run to the procedure named in step 2. |
--ui-values ui.json | Answers the procedure's operator prompts from a file. See headless runs. |
--ui-timeout 300 | Fails a prompt nobody can answer instead of hanging the job. |
--json | One event per line on stdout, for the job log or a later step. |
The exit code is the run's outcome: 0 on PASS, 1 on FAIL or TIMEOUT, 5 on ERROR. See exit codes.
For a self-hosted dashboard, also set TOFUPILOT_URL to its address, and TOFUPILOT_CA_CERT to its CA bundle when it uses a private CA.
CI context on the run
When the CLI detects a CI job, it adds the job to the run's metadata, so a run on the dashboard leads back to the commit that produced it.
| Key | GitHub Actions | GitLab CI | Jenkins |
|---|---|---|---|
ci_provider | github_actions | gitlab_ci | jenkins |
ci_commit | the pull request's head commit, else GITHUB_SHA | CI_COMMIT_SHA | GIT_COMMIT |
ci_branch | GITHUB_HEAD_REF, else GITHUB_REF_NAME | CI_COMMIT_REF_NAME | GIT_BRANCH, without origin/ |
ci_job_url | the workflow run's URL | CI_JOB_URL | BUILD_URL |
Another provider that sets CI=true gets ci_provider: ci only. A key the procedure writes itself takes precedence over these. Set TOFUPILOT_NO_CI_METADATA=1 to turn the context off.
Upload before the job ends
A run whose upload fails stays in the runner's local queue, and a runner rebuilt for every job loses that queue when the job ends. When this happens, the CLI prints a warning at the end of the run. To retry within the job, add a step that runs tofupilot queue retry with the same environment. A run the server refused, such as an upload to a procedure not linked to the station, is reported apart: a retry does not upload it, and tofupilot queue ls shows the reason. With --json, a run_upload_succeeded event confirms each upload.
Precedence
TOFUPILOT_API_KEY takes precedence over a login stored by tofupilot login, and the CLI says so when both exist. It never turns the machine into a station: a runner kept alive as a station is registered once with tofupilot login --token, and its station service ignores the variable. tofupilot whoami shows which identity the key resolves to.
How is this guide?