Skip to content

Runners

Review workflows run in the arnold-runner image (ghcr.io/phonepe/arnold-runner). The backend setting runner.mode (ARNOLD_RUNNER_MODE) decides how jobs reach a runner. Every mode uses the same image and the same job contract: a flat set of variables such as WORKFLOW, ARNOLD_RUN_ID, MR_LINK and EXECUTION_ID.

Mode How a job reaches a runner Runner credentials live in Good for
LOCAL (default) Jobs are queued in Arnold; worker processes long-poll and claim them Worker environment Docker Compose, Kubernetes, VMs
GITLAB Arnold triggers a pipeline in a runner project with the job as pipeline variables Runner project CI/CD variables Reusing GitLab CI capacity
GITHUB Arnold queues the job and dispatches a workflow with only the job number; the workflow claims it Runner repository secrets Reusing GitHub Actions capacity

In every mode the runner posts review comments to the forge directly and reports results to Arnold. It needs outbound access to the backend, the forge and the LLM endpoint, and no inbound access.

Runner API key

Runners authenticate to the backend with a shared API key sent as a bearer token. The backend entry needs these roles:

local.yml (default)
serviceCoreConfiguration:
  auth:
    apiKeys:
      - name: runner
        key: ${ARNOLD_RUNNER_API_KEY}
        roles: [runner_execute, analysis_callback_write, smart_diff_callback_write, review_feedback_write]

Set the same ARNOLD_RUNNER_API_KEY for the backend and every runner. Generate a strong value (openssl rand -hex 32); the example local-runner-key-change-me is for local use only.

Forge credentials for jobs

Forge Credential
GitHub With the GitHub App configured, each job carries a short-lived installation token for the PR's repository (SCM_GITHUB_TOKEN). Nothing to configure on runners
GitLab The runner's own GITLAB_ACCESS_TOKEN (api scope)

LOCAL

Workers poll POST /runner/v1/jobs/claim, send heartbeats while working, and post completion. A job whose worker stops heartbeating for runner.local.leaseSeconds (300) is requeued, up to runner.local.maxAttempts (2), then marked failed.

docker run --rm \
  -e ARNOLD_URL=https://arnold-api.example.com \
  -e ARNOLD_RUNNER_API_KEY=... \
  -e GITLAB_ACCESS_TOKEN=glpat-... \
  -e CLIO_HARNESS=opencode \
  -e CLIO_LLM_BASE_URL=https://api.openai.com/v1 \
  -e CLIO_LLM_API_KEY=sk-... \
  ghcr.io/phonepe/arnold-runner:latest worker --concurrency 2
Option Env Default Purpose
--concurrency N ARNOLD_RUNNER_CONCURRENCY 1 Jobs processed in parallel by this worker
--name ARNOLD_RUNNER_NAME hostname Worker name prefix used in job leases
--once Handle one claim per slot, then exit
ARNOLD_RUNNER_JOB_TIMEOUT 9900 s Hard limit per job, in seconds

Scale by running more workers. Each job clones repositories into a temporary directory and runs an agent, so allow roughly 1 CPU and 2 GB memory per concurrent job, plus disk for checkouts.

Without Docker: cd arnold-runner && pip install -r requirements.txt && npm i -g opencode-ai && python main.py worker.

GitLab CI

  1. Create a project for the runner, e.g. acme/arnold-runner, and add this .gitlab-ci.yml:

    .gitlab-ci.yml
    # Arnold runner pipeline for runner.mode: GITLAB.
    #
    # Put this file (or an `include:` of it) in the runner project's .gitlab-ci.yml. Arnold starts pipelines through the
    # pipeline trigger API and passes the job as pipeline variables (WORKFLOW, ARNOLD_RUN_ID, MR_LINK, ...).
    #
    # Configure these as masked + protected CI/CD variables in the runner project:
    #   ARNOLD_URL, ARNOLD_RUNNER_API_KEY   callback endpoint and runner API key (backend auth.apiKeys)
    #   GITLAB_ACCESS_TOKEN                 token used to read MRs and post review comments
    #   CLIO_LLM_BASE_URL, CLIO_LLM_API_KEY  OpenAI-compatible LLM endpoint (OpenCode and simple LLM calls)
    #   GITHUB_TOKEN                        only for the opt-in Copilot harness without Arnold execution keys
    #
    # The image is fixed here rather than read from a variable: anyone able to trigger the pipeline could otherwise point
    # it at an image of their choosing and receive the masked variables above. To use a mirror or a pinned version, edit
    # this line in your copy.
    
    arnold-runner:
      image: ghcr.io/phonepe/arnold-runner:latest
      rules:
        - if: '$CI_PIPELINE_SOURCE == "trigger" && $WORKFLOW'
      script:
        - python /app/main.py job
      timeout: 2h 45m
    
  2. Add masked, protected CI/CD variables: ARNOLD_URL, ARNOLD_RUNNER_API_KEY, GITLAB_ACCESS_TOKEN, CLIO_HARNESS, CLIO_LLM_BASE_URL, CLIO_LLM_API_KEY.

  3. Create a pipeline trigger token: Settings โ†’ CI/CD โ†’ Pipeline trigger tokens.
  4. Configure the backend:

    .env
    ARNOLD_RUNNER_MODE=GITLAB
    RUNNER_GITLAB_PROJECT_ID=123
    RUNNER_GITLAB_PROJECT_PATH=acme/arnold-runner
    RUNNER_GITLAB_REF=main
    RUNNER_GITLAB_TRIGGER_TOKEN=glptt-...
    

    The triggering GitLab is GITLAB_URL. In Docker Compose, also remove ARNOLD_RUNNER_MODE: LOCAL from the server service, or it overrides .env, and stop the local runner service.

Warning

Keep CI debug tracing off. Job variables can include short-lived execution keys for the Copilot harness.

GitHub Actions

  1. Create a private repository for the runner, e.g. acme/arnold-runner, and add this workflow as .github/workflows/arnold-runner.yml:

    .github/workflows/arnold-runner.yml
    # Arnold runner workflow for runner.mode: GITHUB.
    #
    # Copy to .github/workflows/arnold-runner.yml in the runner repository (keep that repository private). Arnold queues
    # the job and dispatches this workflow with only the job number; the workflow claims the job from Arnold with the
    # runner API key, so job details never appear in workflow inputs.
    #
    # Repository secrets:
    #   ARNOLD_URL, ARNOLD_RUNNER_API_KEY    callback endpoint and runner API key (backend auth.apiKeys)
    #   SCM_GITLAB_TOKEN                     token for GitLab-hosted merge requests (optional)
    #   SCM_GITHUB_TOKEN                     token for GitHub-hosted pull requests (optional)
    #   CLIO_LLM_BASE_URL, CLIO_LLM_API_KEY  OpenAI-compatible LLM endpoint
    name: arnold-runner
    
    on:
      workflow_dispatch:
        inputs:
          job:
            description: Arnold runner job number
            required: true
    
    permissions:
      contents: read
    
    concurrency:
      group: arnold-runner-${{ inputs.job }}
      cancel-in-progress: false
    
    jobs:
      run:
        runs-on: ubuntu-latest
        timeout-minutes: 165
        container:
          image: ghcr.io/phonepe/arnold-runner:latest
        steps:
          - name: Run Arnold job
            env:
              ARNOLD_URL: ${{ secrets.ARNOLD_URL }}
              ARNOLD_RUNNER_API_KEY: ${{ secrets.ARNOLD_RUNNER_API_KEY }}
              GITLAB_ACCESS_TOKEN: ${{ secrets.SCM_GITLAB_TOKEN }}
              GITHUB_TOKEN: ${{ secrets.SCM_GITHUB_TOKEN }}
              CLIO_LLM_BASE_URL: ${{ secrets.CLIO_LLM_BASE_URL }}
              CLIO_LLM_API_KEY: ${{ secrets.CLIO_LLM_API_KEY }}
              JOB: ${{ inputs.job }}
            run: |
              case "$JOB" in ''|*[!0-9]*) echo "invalid job number" >&2; exit 2 ;; esac
              python /app/main.py job --claim "$JOB"
    
  2. Add repository secrets: ARNOLD_URL, ARNOLD_RUNNER_API_KEY, CLIO_LLM_BASE_URL, CLIO_LLM_API_KEY, and SCM_GITLAB_TOKEN if you also review GitLab MRs.

  3. Create a token that can dispatch workflows in that repository: a fine-grained PAT with Actions: Read and write on it only.
  4. Configure the backend:

    .env
    ARNOLD_RUNNER_MODE=GITHUB
    RUNNER_GITHUB_REPOSITORY=acme/arnold-runner
    RUNNER_GITHUB_WORKFLOW=arnold-runner.yml
    RUNNER_GITHUB_REF=main
    RUNNER_GITHUB_TOKEN=github_pat_...
    # RUNNER_GITHUB_API_URL=https://github.example.com/api/v3   # GitHub Enterprise Server
    

The workflow input carries only the job number. The workflow claims the job from Arnold, so review details and tokens never appear in workflow inputs or logs.

Choosing a mode

  • Start with LOCAL. It has the lowest latency (no pipeline start-up) and the fewest moving parts.
  • Use GITLAB or GITHUB when reviews must run inside an existing CI trust boundary or you want CI to absorb the compute. Expect 20โ€“60 seconds of extra start-up per run.
  • GITLAB and GITHUB modes need the backend reachable from CI runners (ARNOLD_URL).