Skip to content
Documentation

Common tasks for Code, Runner Farm and QA

This page is a set of short recipes. Each one solves a single task with commands you can copy. Where a script helps, there is a --json | jq variant. For every flag of a command, see the reference pages: CHAMPREP Code, Runner Farm and CHAMPREP QA.

In the examples, acme is a group, acme/web is a project, and code.champrep.com is CHAMPREP Code.

Terminal window
champrep auth login # opens the browser to approve the sign-in
champrep auth whoami # who the CLI acts as
champrep auth list # stored sign-ins, across environments
champrep auth switch PROFILE # make another stored sign-in the active one
champrep --env test code projects ls # one command against the test environment

CHAMPREP Code has no separate workspace switch. A project belongs to a group or to your personal namespace, and your role in it decides what you can do.

Runner Farm and QA act in a workspace: your personal account, an organization or a team. List the ones you can use, then pass the KEY column of rf accounts ls (personal, organization:<id> or team:<id>) with --workspace:

Terminal window
champrep rf accounts ls # KEY, workspace, your role, whether a farm account exists
champrep org ls # the same organizations and teams (ACCOUNT column)
champrep rf pools ls --workspace organization:65f0c0ffee0000000000abcd
champrep qa repos ls --workspace team:65f0c0ffee0000000000beef

champrep org use NAME sets the default for organization commands such as business members. Runner Farm and QA ignore it. Pass --workspace to them, or let the service pick the workspace the way the web app does.

Terminal window
champrep code projects ls --search web
champrep code projects show acme/web # default branch, HTTPS and SSH addresses
champrep code repo clone-url acme/web # HTTPS address
champrep code repo clone-url acme/web --ssh # SSH address
git clone "$(champrep code repo clone-url acme/web --ssh)"

Scripting variant:

Terminal window
champrep code projects ls --limit 500 --json | jq -r '.[].path_with_namespace'
champrep code projects show acme/web --json | jq -r .ssh_url_to_repo

git talks to CHAMPREP Code directly, not through the CLI, so it needs its own credential. CHAMPREP Code does not accept your CLI sign-in as a git password. Creating a personal access token or adding an SSH key is a credential change, so it needs your signed-in web session. Do it once in the browser.

SSH (recommended). It works for every project, and nothing is stored in plain text.

  1. Open https://code.champrep.com/-/settings/ssh_keys.
  2. Paste your public key, for example the contents of ~/.ssh/id_ed25519.pub.
  3. Check the key and the connection:
Terminal window
champrep code ssh-keys ls
git ls-remote git@code.champrep.com:acme/web.git HEAD

HTTPS with a personal access token.

  1. Open https://code.champrep.com/-/settings/tokens.
  2. Create a token with the scope read_repository, or write_repository if you push. Give it an expiry date.
  3. Let git’s credential store keep the token in your system keychain:
Terminal window
# macOS
git config --global credential.https://code.champrep.com.helper osxkeychain
# Windows (Git Credential Manager)
git config --global credential.https://code.champrep.com.helper manager
# Linux with libsecret (needs git-credential-libsecret, see below)
git config --global credential.https://code.champrep.com.helper libsecret

On Linux, the libsecret helper works only when the git-credential-libsecret program is installed. Many distributions do not install it with git. Install it from your distribution’s packages, or build it from git’s contrib/credential/libsecret folder. Check with command -v git-credential-libsecret. Without a keyring, avoid the store helper, which writes the token to ~/.git-credentials in plain text. Use cache --timeout=3600 instead, which keeps it in memory only, or use SSH.

Then clone one project by hand. git asks for a user name (any value works) and a password (paste the token), and the credential store keeps them:

Terminal window
git clone https://code.champrep.com/acme/web.git

From then on, git and champrep code clone use the stored token. Never put a token in a remote URL such as https://user:TOKEN@…: git writes the URL to .git/config, and anyone who reads that file or your shell history can use it. champrep code clone refuses clone addresses that carry a credential.

Clone every project you are a member of, directly or through a group, into ~/src. Each project lands under its namespace, for example ~/src/acme/platform/api.

Terminal window
champrep code clone --membership --dest ~/src --ssh

Other choices:

Terminal window
champrep code clone --owned --dest ~/src --ssh # projects where your role is Owner
champrep code clone --all --dest ~/src --ssh # also public and internal projects you can see
champrep code clone acme/web acme/api --dest ~/src # just these projects

See the plan first. A dry run lists each project and what would happen, without touching anything:

Terminal window
champrep code clone --membership --dest ~/src --dry-run
Terminal window
champrep code clone --group acme --dest ~/src --ssh # the group's own projects
champrep code clone --group acme --include-subgroups --dest ~/src --ssh # and every subgroup
champrep code clone --group acme --include-subgroups --archived --dest ~/src --ssh # archived projects too

--parallel N sets how many clones run at once (default 4, at most 16). Archived projects are left out unless you add --archived. --search TEXT keeps only projects whose name or path contains the text.

Run the same command again with --update. It clones new projects and updates the ones you already have:

Terminal window
champrep code clone --group acme --include-subgroups --dest ~/src --ssh --update

For each existing clone, --update first checks that its origin is the project, by its HTTPS or SSH address. A clone of another repository at that path is reported as mismatch (failed) and left alone. Then it runs git fetch --prune and a fast-forward-only merge of the current branch. Local work is never overwritten:

  • a branch that has diverged is reported as failed, and you merge or rebase it yourself;
  • a detached HEAD or a branch without an upstream is fetched only and reported as no-upstream.

Without --update, existing clones are skipped.

The command ends with a summary and exits 1 when any project failed, so a scheduled job can alert you:

Terminal window
# crontab: refresh the mirror every night at 02:00
0 2 * * * champrep code clone --group acme --include-subgroups --dest "$HOME/src" --ssh --update >>"$HOME/src/.mirror.log" 2>&1

Scripting variant, listing what failed:

Terminal window
champrep code clone --membership --dest ~/src --ssh --update --json \
| jq -r '.[] | select(.status == "failed") | "\(.project): \(.error)"'

The JSON statuses are cloned, updated, up_to_date, no_upstream, skipped, failed (with "reason": "mismatch" for a clone of another repository), interrupted and not_started after Ctrl-C, and, with --dry-run, would_clone, would_update and would_skip.

champrep code clone never prompts, because several clones run at once. git runs with GIT_TERMINAL_PROMPT=0. SSH runs with BatchMode=yes, so it asks no password, passphrase or host-key question, unless you set your own GIT_SSH_COMMAND or core.sshCommand. Before a bulk SSH clone, do two things:

  1. Load your key in ssh-agent (ssh-add).
  2. Connect once by hand to accept the host key (git ls-remote git@code.champrep.com:acme/web.git HEAD).

A project that needs a credential git does not have fails, with could not read Username over HTTPS or Permission denied (publickey) over SSH. Set up the credentials above and run the command again.

Ctrl-C stops the run cleanly. No new clones start, the running ones are stopped (git removes a half-finished clone), and the summary shows what was done. Run the command again to continue: finished clones are skipped.

Only https:// and SSH addresses on the CHAMPREP Code host are cloned, and git runs with every other transport disabled.

List pipelines and check the latest one on a branch

Section titled “List pipelines and check the latest one on a branch”
Terminal window
champrep code pipelines ls acme/web --limit 10
champrep code pipelines ls acme/web --ref main --limit 1
champrep code pipelines ls acme/web --status failed

Scripting variant, printing the status of the newest pipeline on main:

Terminal window
champrep code pipelines ls acme/web --ref main --limit 1 --json | jq -r '.[0] | "\(.id) \(.status)"'

pipelines wait waits until a pipeline finishes, and its exit code is the outcome: 0 success; 1 failed, canceled, skipped, or stopped at a manual job; 8 still running when --timeout (default 60m) ran out.

After a push, wait for the pipeline of the commit you pushed:

Terminal window
git push
champrep code pipelines wait acme/web --sha "$(git rev-parse HEAD)" && ./deploy.sh

--sha waits for Code to create that commit’s pipeline, then for it to finish. --sha HEAD also works inside the repository. Avoid --ref main right after a push. It takes the newest pipeline on the branch at that moment, which can still be the previous commit’s pipeline if Code has not yet created the one for your push, and you would deploy on the wrong result.

Terminal window
champrep code pipelines wait acme/web --ref main # the newest pipeline on main now
champrep code pipelines wait acme/web 9921 --timeout 30m # one pipeline

Run a pipeline and wait for that one:

Terminal window
ID=$(champrep code pipelines run acme/web --ref main --yes --json | jq -r .id)
champrep code pipelines wait acme/web "$ID"

Progress and the final status line go to stderr. With --json, stdout holds the finished pipeline, and the exit code stays the same:

Terminal window
champrep code pipelines wait acme/web "$ID" --json | jq -r '"\(.status) \(.web_url)"'

A pipeline that reaches a manual job, such as a deploy you start by hand, stops there until a person acts. pipelines wait exits 1 with a message saying so. Start the job with champrep code jobs play, or pass --manual-ok to count the pipeline as finished (exit 0). A scheduled (delayed) job starts on its own, so the wait goes on through it.

To watch one job instead, follow its log. The command returns when the job finishes and exits 1 when the job failed or was canceled:

Terminal window
champrep code jobs log acme/web 4182 --follow
Terminal window
champrep code pipelines retry acme/web 9921 --yes # reruns the failed and canceled jobs
champrep code pipelines cancel acme/web 9921 --yes

Read a failed job’s log, follow a running job, rerun a job

Section titled “Read a failed job’s log, follow a running job, rerun a job”
Terminal window
champrep code jobs ls acme/web --status failed --limit 5 # newest failed jobs
champrep code jobs ls acme/web --pipeline 9921 --status failed # failed jobs of one pipeline
champrep code jobs log acme/web 4180 --tail 100 # end of a log of any size
champrep code jobs log acme/web 4182 --follow # stream until the job ends
champrep code jobs retry acme/web 4180 --yes # run a finished job again
champrep code jobs play acme/web 4190 --var DEPLOY=staging --yes # start a manual job

Scripting variant, printing the last 30 lines of every failed job in a pipeline:

Terminal window
for J in $(champrep code jobs ls acme/web --pipeline 9921 --status failed --json | jq -r '.[].id'); do
echo "=== job $J"
champrep code jobs log acme/web "$J" --tail 30
done
Terminal window
git push -u origin feature/login
champrep code mr create acme/web --source feature/login --target main \
--title "Add login page" --remove-source-branch --yes
champrep code mr show acme/web 12 # merge status and head pipeline
champrep code mr approve acme/web 12 --yes
champrep code mr merge acme/web 12 --auto --squash --yes # merges when the pipeline succeeds

Scripting variant, capturing the new merge request’s number:

Terminal window
IID=$(champrep code mr create acme/web --source feature/login --target main \
--title "Add login page" --yes --json | jq -r .iid)
champrep code mr merge acme/web "$IID" --auto --yes

What needs the web app. Merging or approving into a protected branch is a decision only you can take, signed in to CHAMPREP Code in the browser. The CLI then stops with needs your web session … (SESSION_REQUIRED) and exit code 1. Signing in to the CLI again does not change that. Open the merge request in the browser and merge or approve it there. Unprotected branches work from the CLI.

Runners: list, see who is online, tag, pause and resume

Section titled “Runners: list, see who is online, tag, pause and resume”
Terminal window
champrep code runners ls # project and group runners you manage
champrep code runners ls --project acme/web # runners the project can use (Maintainer)
champrep code runners ls --group acme # the group's runners (Owner)
champrep code runners ls --status online # who is online now
champrep code runners ls --status offline --active # offline but not paused: worth a look
champrep code runners show 41 # status, online, tags, paused, machines
champrep code runners update 41 --add-tag docker --remove-tag old --yes
champrep code runners update 41 --tags linux,arm64 --yes # replace the whole list
champrep code runners update 41 --pause --yes # stop taking new jobs
champrep code runners update 41 --resume --yes

--add-tag and --remove-tag read the runner’s tags and write the whole list back. If someone changes the tags between those two steps, their change is lost, so check with runners show when several people manage a runner.

Scripting variant, pausing every runner with a tag before maintenance:

Terminal window
champrep code runners ls --tag gpu --active --limit 500 --json | jq -r '.[].id' \
| xargs -I{} champrep code runners update {} --pause --yes

You need Maintainer to see and change a project’s runners, and Owner for a group’s runners. Instance runners are for instance administrators (runners ls --all).

Create a project or group runner from the CLI and connect a machine to it with champrep-code-runner. The token (ccrt_…) is printed once, on standard output, and never logged. Creating it always needs --yes.

Terminal window
champrep code runners create --project acme/web --description "build box" \
--tags linux,docker --yes --json \
| jq -r .token \
| champrep-code-runner register --url https://code.champrep.com --token-stdin \
--executor docker --docker-image alpine:3.24

Use --group acme instead of --project for a group runner (you need Owner). Add --no-untagged to take only tagged jobs, and --protected to run only protected branches and tags. You can also create the runner in the web app, under Settings > CI/CD > Runners of the project or group. See register a runner.

The CLI cannot reset a runner’s token or create instance runners. Do both in the web app.

Terminal window
champrep rf accounts show # the farm account, who it bills, the monthly ceiling
champrep rf usage # credits and minutes for the current period
champrep rf usage --period 2026-10 # a past month
champrep rf usage --json # { "balance": …, "usage": …, "period": "YYYY-MM" }
Terminal window
champrep rf connections ls
champrep rf pools ls
champrep rf pools show pol_01HZX9K4
champrep rf jobs ls --state waiting,held

Scripting variant, showing how busy each pool is:

Terminal window
champrep rf pools ls --json | jq -r '.pools[] | "\(.id) \(.state) \(.busy)/\(.max_concurrent)"'
Terminal window
champrep rf pools update pol_01HZX9K4 --max-concurrent 8 --min-idle 2 --yes # scale up
champrep rf pools update pol_01HZX9K4 --max-concurrent 2 --min-idle 0 --yes # scale down
champrep rf pools update pol_01HZX9K4 --pause --yes # maintenance
champrep rf pools update pol_01HZX9K4 --resume --yes
champrep rf pools create --connection con_01HZX7 --name Builds \
--class build-4 --max-concurrent 4 --timeout 2h --yes # a new pool

--min-idle keeps warm runners ready, so jobs start faster, but warm runners use credits. Your plan caps the classes and limits you can use.

Runner Farm runner tokens, connector secrets and pairing stay in the web app at https://runners.champrep.com. The CLI cannot reach them, for any key.

Terminal window
champrep qa repos available --provider code # CHAMPREP Code projects and their QA keys
REPO="code:$(champrep code projects show acme/web --json | jq -r .id)"
champrep qa repos activate "$REPO" --yes
Terminal window
champrep qa scan "$REPO" --ref main --watch --yes # exits 1 when the scan or its gate fails
champrep qa scans ls --repo "$REPO" --limit 5
Terminal window
champrep qa findings ls --repo "$REPO" --severity critical,high
champrep qa findings ls --severity high --type secret # leaked secrets, whole workspace
champrep qa findings show QA-0970

Scripting variant:

Terminal window
champrep qa findings ls --repo "$REPO" --severity critical,high --json | jq -r '.[] | "\(.qaId) \(.title)"'

champrep qa gates status exits 1 when the gate fails, so it can guard any pipeline step. In CHAMPREP Code (.chpcode-ci.yml):

qa-gate:
stage: test
image: alpine:3.20
variables:
QA_REPO: "code:7d0c5c6e-0b6a-4e2b-9a55-0f8e6c1d2a10"
before_script:
- apk add --no-cache curl
- curl -fsSL https://cli.champrep.com/install.sh | sh
- export PATH="$HOME/.local/bin:$PATH"
script:
# CHAMPREP_TOKEN is a masked, protected CI variable holding an API key
# with the qa:read scope.
- champrep qa gates status "$QA_REPO" --branch "$CI_COMMIT_REF_NAME"

The same job works in a GitLab .gitlab-ci.yml. To scan first and then gate, give the key qa:write as well and run:

script:
- champrep qa scan "$QA_REPO" --ref "$CI_COMMIT_REF_NAME" --watch --timeout 20m --yes

A scan uses your QA allowance, so many teams scan on the default branch and merge requests only, and check the gate everywhere else.

Which credential. Do not use champrep auth login in CI. Create a scoped API key while signed in to the CLI in a browser session, and store it as a masked, protected CI variable named CHAMPREP_TOKEN. The CLI uses that variable instead of the keychain.

Terminal window
champrep keys create --name "CI: acme/web" --scope code:read_api --scope qa:read --expires-in-days 90
What the job doesScopes
Read Code: projects, pipelines, job logs, runnerscode:read_api
Change Code: run pipelines, retry jobs, open and merge MRs, update runnerscode:api
Read Runner Farm / change poolsrunner_farm:read / runner_farm:write
Check QA gates and findings / start scans, activate repositoriesqa:read / qa:write

Grant only what the job needs. A key cannot reach CHAMPREP Code administration, Runner Farm credentials, or anything that needs your web session.

No prompts. Without a terminal, any command that changes something refuses unless you pass --yes (-y), and nothing is sent. Add --yes to every write in a script. champrep code clone never prompts and needs no --yes.

Machine-readable output. Add --json and parse it with jq. The exit code stays the same with --json. Do not parse the human-readable text.

Exit codes.

CodeMeaningTypical action in CI
0Success.Continue.
1Failure or refusal: a failing gate, a failed scan, a pipeline or followed job that did not succeed, a clone that failed, no access to the item, not on your plan, your role, a decision that needs your web session, or a missing --yes.Fail the job; read the message.
3Not signed in, or the key is invalid or revoked.Fix CHAMPREP_TOKEN.
4The key lacks a scope.Add the scope to the key.
5Rate limit or capacity.Retry later.
6Network failure.Retry.
7Gateway or service failure.Retry later.
8pipelines wait ran out of --timeout; the pipeline is still running.Wait again, or raise --timeout.

See the command reference and API keys for automation.