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

.github/workflows/hil.yml
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>
.gitlab-ci.yml
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.
FlagWhy in CI
--uploadUploads the run to the procedure named in step 2.
--ui-values ui.jsonAnswers the procedure's operator prompts from a file. See headless runs.
--ui-timeout 300Fails a prompt nobody can answer instead of hanging the job.
--jsonOne 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.

KeyGitHub ActionsGitLab CIJenkins
ci_providergithub_actionsgitlab_cijenkins
ci_committhe pull request's head commit, else GITHUB_SHACI_COMMIT_SHAGIT_COMMIT
ci_branchGITHUB_HEAD_REF, else GITHUB_REF_NAMECI_COMMIT_REF_NAMEGIT_BRANCH, without origin/
ci_job_urlthe workflow run's URLCI_JOB_URLBUILD_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?

On this page