Skip to content
Documentation

Register a runner

Registering connects a machine to a runner you created in CHAMPREP Code. You need the runner’s authentication token, which starts with ccrt_.

  1. Open your project (or group) and go to Settings > CI/CD > Runners.
  2. Select New runner.
  3. Choose which jobs it takes:
    • Tags: jobs with tags: run only on runners that have all of them.
    • Run untagged jobs: whether it also takes jobs without tags.
    • Protected: run only jobs of protected branches and tags.
  4. Select Create runner and copy the token. It is shown once.

Treat the token like a password. Anyone who has it can take your jobs.

The simplest way, in a terminal on the machine:

Terminal window
champrep-code-runner register --url https://code.champrep.com

The runner asks for the token (without showing it) and the executor. It checks the token, then saves the runner in its configuration file.

To script it, pass the token on standard input or from a file, so it never appears in your shell history or the process list:

Terminal window
printf '%s\n' "$RUNNER_TOKEN" | champrep-code-runner register \
--url https://code.champrep.com --token-stdin \
--name build-01 --executor shell
Terminal window
champrep-code-runner register --url https://code.champrep.com \
--token-file /root/runner-token --executor docker --docker-image alpine:3.24

On Windows, from an elevated PowerShell prompt:

Terminal window
$env:RUNNER_TOKEN | champrep-code-runner.exe register `
--url https://code.champrep.com --token-stdin --name win-build-01 `
--executor shell --shell pwsh
OptionMeaning
--urlYour CHAMPREP Code address, for example https://code.champrep.com.
--token-stdin / --token-file PATHRead the token from standard input or a file.
--name NAMEThe runner’s name on this machine (default: the host name).
--executorshell, docker or kubernetes.
--shellFor the shell executor: bash, sh, pwsh or powershell.
--docker-image IMAGEDefault job image for the Docker and Kubernetes executors.
--kubernetes-namespace NSRun Kubernetes jobs in this namespace.
--limit NAt most N jobs at once for this runner.
--non-interactiveNever prompt; fail if a value is missing.
--config PATHUse this configuration file (see below).

CHPCODE_RUNNER_URL and CHPCODE_RUNNER_TOKEN can replace --url and the token options.

When you run it asFile
root (Linux, macOS)/etc/champrep-runner/config.toml
An elevated prompt or the service (Windows)%ProgramData%\champrep-runner\config.toml
Any other user~/.champrep-runner/config.toml

CHPCODE_RUNNER_CONFIG or --config choose another file. The file is created readable only by its owner. One machine can hold several runners: register again with a different --name.

Terminal window
champrep-code-runner run # in this terminal
champrep-code-runner service install # or as a service that starts at boot

See Runner commands to check its status, stop it, and more.