@andrian.yablonskyy/thub-coordinator 1.0.36 → 1.0.38

package/views/help/_client-setup.pug

@@ -0,0 +1,122 @@
++section('client-setup', 'Client setup', 'motherboard')
+  p.
+    A Client (#[code thub-client]) is a daemon on a lab machine. One #[strong instance] owns one DUT slot. A machine with
+    several boards runs several instances (#[code dut0], #[code dut1], …), each with its own config file.
+    Clients register themselves with the shared join key; there's no admin step.
+
+  h3.h6 1. Install
+  +code('Lab machine, as the user the Client should run as (via sudo)').
+    # Node.js and HW tools (stlink-tools/openocd only for HW Clients)
+    sudo apt install -y nodejs npm stlink-tools openocd usbutils
+    # Docker: needed on SW Clients, and on HW Clients whose jobs use docker.
+    # Install it BEFORE thub-client so the service gets the docker group.
+    sudo apt install -y docker.io
+    sudo npm i -g @andrian.yablonskyy/thub-client
+  p.small.
+    This creates #[code ~/.config/thub/client.json] and #[code ~/var/lib/thub/client] for the user who ran
+    #[code sudo], and installs the #[code thub-client@.service] systemd unit running as that user, with the
+    #[code dialout], #[code plugdev] and #[code docker] groups. It also installs the root helpers that
+    apply self-updates and scheduled reboots.
+
+  h3.h6 2. Configure and start
+  .row.g-3
+    .col-md-6
+      +code('SW Client — ~/.config/thub/client.json').
+        {
+          "coordinatorUrl": "#{coordinatorUrl}",
+          "name": "lab-sw-01",
+          "type": "sw",
+          "labels": [],
+          "groups": [],
+          "joinKey": "<the Coordinator's clientJoinKey>",
+          "varDir": "/home/thub/var/lib/thub/client"
+        }
+    .col-md-6
+      +code('HW Client — ~/.config/thub/client.json').
+        {
+          "coordinatorUrl": "#{coordinatorUrl}",
+          "name": "lab-hw-01",
+          "type": "hw",
+          "labels": ["board:nucleo-f401re", "uart", "stlink"],
+          "groups": ["<group id>"],
+          "joinKey": "<the Coordinator's clientJoinKey>",
+          "varDir": "/home/thub/var/lib/thub/client",
+          "hw-devices": {
+            "stlinks": [{ "index": 1, "devpath": "3.3.4.3.1" }],
+            "uarts":   [{ "index": 1, "devpath": "3.3.3.2", "baudRate": 115200 }],
+            "usbs":    [{ "index": 1, "devpath": "3.2.4" }]
+          }
+        }
+  +code('Start it and follow the log').
+    sudo systemctl enable --now thub-client@client
+    journalctl -u thub-client@client -f
+
+  h3.h6 Config reference
+  .table-responsive
+    table.table.table-sm.small
+      thead
+        tr
+          th Field
+          th Required
+          th Meaning
+      tbody
+        tr
+          td: code coordinatorUrl
+          td Yes
+          td The Coordinator's #[code publicUrl].
+        tr
+          td: code type
+          td Yes
+          td #[code hw] (physical DUT) or #[code sw] (DUT image in Docker).
+        tr
+          td: code joinKey
+          td Yes
+          td Must equal the Coordinator's #[code clientJoinKey]. Or set #[code THUB_CLIENT_JOIN_KEY].
+        tr
+          td: code name
+          td No
+          td Resource name. Under systemd, the instance name (#[code thub-client@dut1] → #[code dut1]) is used unless an admin renames it on the dashboard.
+        tr
+          td: code labels
+          td No
+          td Matched against a job's #[code --board]/#[code --label]. Use #[code board:<name>] for the board.
+        tr
+          td: code groups
+          td No
+          td Group ids (from #[a(href="/groups") Groups]) this Client belongs to, for #[code thub run --group].
+        tr
+          td: code varDir
+          td No
+          td State directory: tokens, the client id, job workspaces, sockets. Keep the installer's default under systemd.
+        tr
+          td: code hw-devices.stlinks / uarts / usbs
+          td HW
+          td Up to 8 of each. An entry is a udev index #[code N] (→ #[code /dev/thub/dut<N>-stlink|uart|usb]), a path, or an object with #[code index]/#[code path], #[code devpath] (USB port), #[code serial] (ST-Link) and #[code baudRate] (UART, default 115200).
+        tr
+          td: code heartbeatIntervalSec / longPollWaitSec
+          td No
+          td 10 s / 30 s by default.
+        tr
+          td: code clientId
+          td No
+          td An explicit identity UUID (or #[code THUB_CLIENT_ID]). Normally generated once and kept in #[code .client-id].
+  p.small.
+    SW Clients have no settings of their own: they run whatever DUT image a job brings (#[code --docker-image]).
+    Admins can also edit an HW Client's devices from its resource card (#[strong ST-Link | UART | DUT USB]
+    tabs). #[strong Connected USB devices → Import to config] fills them from the host's #[code lsusb].
+
+  h3.h6 Several DUT slots on one machine
+  +code('One instance per slot').
+    thub-client register --name dut1 --type hw    # creates ~/.config/thub/dut1.json, starts thub-client@dut1
+    nano ~/.config/thub/dut1.json                 # set that slot's hw-devices
+    sudo systemctl restart thub-client@dut1
+    thub-client deregister --name dut1            # when the slot goes away
+
+  h3.h6 Controlling a Client
+  +code('As the Client\'s user (not with sudo)').
+    thub-client status
+    thub-client lock --reason "debugging I2C"     # BUSY (local): nothing gets scheduled here
+    thub-client unlock
+    thub-client restart
+    thub-client --config ~/.config/thub/dut1.json status    # a specific instance
+    thub-client udev --print                                # the udev rules this config generates

package/views/help/_coordinator.pug

@@ -0,0 +1,134 @@
++section('coordinator', 'Coordinator setup', 'hdd-network')
+  p.
+    One Coordinator serves the whole network. It's a single Node.js process with SQLite, which is
+    enough for tens of Clients and hundreds of jobs a day. Run it on a small Linux VM (Ubuntu recommended)
+    with Node.js 20+ (24 LTS recommended), reachable over HTTPS by the Agents and Clients.
+
+  h3.h6 1. Install as a systemd service
+  +code('Coordinator host').
+    sudo apt install -y nodejs npm
+    sudo npm i -g @andrian.yablonskyy/thub-coordinator
+  p.small.
+    #[code sudo npm i -g] does the whole setup for the user who ran #[code sudo]. It creates
+    #[code ~/.config/thub/coordinator.json] (with a random #[code sessionSecret]) and
+    #[code ~/var/lib/thub] (database, artifacts, avatars). It installs, enables and starts
+    #[code thub-coordinator.service], plus the root helper behind the navbar's #[strong Update app] button.
+
+  h3.h6 2. Configure
+  p.small.
+    Edit #[code ~/.config/thub/coordinator.json], then #[code sudo systemctl restart thub-coordinator].
+    Logs: #[code journalctl -u thub-coordinator -f].
+  +code('~/.config/thub/coordinator.json').
+    {
+      "listen": "127.0.0.1:8080",
+      "publicUrl": "#{coordinatorUrl}",
+      "trustProxy": "loopback",
+      "dataDir": "/home/thub/var/lib/thub",
+      "sessionSecret": "<long random string>",
+      "clientJoinKey": "<output of: thub-admin join-key generate>",
+      "heartbeat": { "intervalSec": 10, "missedLimit": 3, "sweepIntervalSec": 5 },
+      "scheduler": { "assignAckTimeoutSec": 15, "requeueOnLost": true, "maxQueuedPerAgent": 20, "tickIntervalSec": 10 },
+      "jobs": { "defaultTimeoutSec": 1800, "maxTimeoutSec": 14400 },
+      "retention": { "logRetentionDays": 14, "artifactRetentionDays": 30, "jobRetention": "forever" },
+      "artifacts": { "maxUploadMb": 512, "linkTtlHours": 168 },
+      "updates": { "checkIntervalMin": 15, "registry": null }
+    }
+  .table-responsive
+    table.table.table-sm.small
+      thead
+        tr
+          th Field
+          th Meaning
+      tbody
+        tr
+          td: code listen
+          td Address the Node.js process binds to. Keep it on #[code 127.0.0.1] behind a reverse proxy.
+        tr
+          td: code publicUrl
+          td The URL Agents, Clients and job links use, e.g. #[code https://thub.example.com].
+        tr
+          td: code trustProxy
+          td Which proxies' #[code X-Forwarded-For] to trust for a Client's external address: #[code loopback] (default), a CIDR such as #[code "10.0.0.0/8"], a hop count, or #[code false].
+        tr
+          td: code sessionSecret
+          td Signs dashboard sessions and artifact download links. Keep it secret and never use the #[code change-me-…] placeholder.
+        tr
+          td: code clientJoinKey
+          td The shared secret Clients self-register with. Unset or #[code null] turns registration off (#[code 503]).
+        tr
+          td: code heartbeat.*
+          td Clients heartbeat every #[code intervalSec]. After #[code missedLimit] misses a resource goes #[code OUT_OF_SERVICE] and its job becomes #[code LOST].
+        tr
+          td: code scheduler.*
+          td #[code assignAckTimeoutSec]: how long an assignment waits for the Client to accept. #[code requeueOnLost]: retry a #[code LOST] job once. #[code maxQueuedPerAgent]: queue limit per agent.
+        tr
+          td: code jobs.*
+          td Default and maximum job timeout, in seconds.
+        tr
+          td: code retention.*
+          td #[code jobRetention]: #[code 1w], #[code 2w], #[code 1m], #[code 3m], #[code 6m] or #[code forever]. Older finished jobs, their logs and artifacts are deleted hourly.
+        tr
+          td: code updates.*
+          td How often to check npm for new versions (#[code 0] turns the periodic check off), and an optional private registry.
+  p.small.
+    Resolution order: #[code THUB_COORDINATOR_CONFIG] (a path) → #[code ~/.config/thub/coordinator.json] → the bundled
+    default. These environment variables override the file: #[code THUB_LISTEN], #[code THUB_PUBLIC_URL],
+    #[code THUB_DATA_DIR], #[code THUB_SESSION_SECRET] and #[code THUB_CLIENT_JOIN_KEY].
+
+  h3.h6 3. HTTPS reverse proxy
+  p.small.
+    Expose only port 443. Log streams use Server-Sent Events, so the proxy must not buffer responses.
+  .row.g-3
+    .col-md-6
+      +code('Caddyfile').
+        thub.example.com {
+          reverse_proxy 127.0.0.1:8080 {
+            flush_interval -1
+          }
+        }
+    .col-md-6
+      +code('nginx').
+        location / {
+          proxy_pass http://127.0.0.1:8080;
+          proxy_set_header Host $host;
+          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+          proxy_set_header X-Forwarded-Proto $scheme;
+          proxy_http_version 1.1;
+          proxy_buffering off;          # SSE log streams
+          proxy_read_timeout 1h;
+          client_max_body_size 512m;    # artifacts.maxUploadMb
+        }
+
+  h3.h6 4. Users, agents and the join key
+  p.small.
+    #[code thub-admin] works directly on the database. Run it on the Coordinator host as the service user.
+  +code('Coordinator host').
+    thub-admin create-admin alice 's3cret' --role admin     # or --role viewer (read-only dashboard)
+    thub-admin join-key generate                            # → clientJoinKey here, joinKey on every Client
+    thub-admin agent add ci-firmware --kind ci              # CI token: job ids A-00001…
+    thub-admin agent add alice-laptop --kind cli            # developer token: job ids M-00001…
+    thub-admin group add ci-nightly --comment "nightly pool" # → a group id for thub run --group
+    thub-admin resource maintenance <resourceId> --on
+    thub-admin jobs reset --yes                             # cancel every active job
+    thub-admin jobs clean --yes --before "01/09/2026 00:00:00"
+  +note('warning').
+    Forgot the admin password? Start the Coordinator once with #[code THUB_BOOTSTRAP_ADMIN_PASSWORD=…]
+    (and optionally #[code THUB_BOOTSTRAP_ADMIN_USER], default #[code admin]). The password is reset on
+    #[em every] start while the variable is set, so unset it once you're signed in again.
+
+  h3.h6 Running from a checkout / DEV mode
+  +code('Repository checkout').
+    git clone --recurse-submodules git@github.com:andrianyablonskyy/thub.git && cd thub && npm install
+    THUB_BOOTSTRAP_ADMIN_PASSWORD=admin ./bin/coordinator
+    # Dashboard without hardware: virtual agent, two virtual Clients and demo jobs
+    DEV_MODE=1 THUB_BOOTSTRAP_ADMIN_PASSWORD=admin npm run coordinator
+  p.small.text-body-secondary.
+    In DEV mode the agent token is #[code agt_dev-virtual-agent-token], which is public. Never set
+    #[code DEV_MODE] on a real Coordinator.
+
+  h3.h6 Updates
+  p.small.mb-0.
+    The Coordinator checks npm for new Coordinator, Agent and Client versions. Admins update the Coordinator
+    with #[strong Update app] in the navbar, and Agents and Clients from the #[a(href="/admin/agents") Agents]
+    and #[a(href="/resources") Resources] pages. Clients install an update only between jobs.
+    Manual alternatives: #[code thub-admin self-update], #[code thub self-update] and #[code thub-client self-update].

package/views/help/_docker.pug

@@ -0,0 +1,124 @@
++section('docker', 'Docker registry integration', 'box-seam')
+  p.
+    A job can use Docker in two different ways. Keep them apart, because they log in and run differently:
+  .row.g-3.mb-3
+    .col-md-6
+      .card.h-100
+        .card-body.small
+          h3.h6 #[code --docker-image]: the DUT
+          p.mb-0.
+            SW jobs only. The Client pulls the image and runs it as the job's #[strong DUT container]
+            (an emulator the tests talk to), sandboxed, next to your command. The pull uses the
+            #[strong Client host's] Docker login, made once by the service user.
+    .col-md-6
+      .card.h-100
+        .card-body.small
+          h3.h6 #[code docker …] inside #[code --command]
+          p.mb-0.
+            Any job type, on a host with Docker. Your command logs in, pulls and runs containers
+            itself, e.g. to run the tests #[em inside] an image. Credentials come from the job
+            (#[code --env]) and are scoped to the job.
+
+  h3.h6 Log in to a registry on the Client host (for --docker-image)
+  p.small.
+    #[code --docker-image] is pulled with #[code docker pull] as the Client's service user, from the registry the reference names
+    (Docker Hub for a short name such as #[code python:3.14]). Log in once per host, as that user:
+  +code('Client host').
+    # the user that runs thub-client (the one who ran sudo npm i -g), e.g. thub:
+    sudo -u thub docker login registry.lab.local:5000
+    sudo -u thub docker login ghcr.io -u <github-user>        # password: a PAT with read:packages
+    sudo -u thub docker pull registry.lab.local:5000/dut-emulator:2026.08   # check it works
+  p.small.
+    A plain-HTTP registry must be listed in the Docker daemon's #[code insecure-registries]:
+  +code('/etc/docker/daemon.json').
+    { "insecure-registries": ["registry.lab.local:5000"] }
+  p.small.
+    Then run #[code sudo systemctl restart docker]. An image that can't be pulled ends the job as #[code ERROR]
+    during #[em prepare], naming the registry and Docker's reason. An image already on the host isn't pulled again.
+
+  h3.h6 How the Client starts the DUT container
+  p.small.
+    You don't pass #[code docker run] parameters for the DUT. The Client always starts it like this (image default command,
+    sandboxed), and removes it and its network when the job ends:
+  +code('What the Client runs (equivalent)').
+    docker pull registry.lab.local:5000/dut-emulator:2026.08
+    docker network create --driver bridge thub-job-<jobId>
+    docker run -d --name thub-<jobId> --network thub-job-<jobId> \
+      --memory 2g --cpus 2 --read-only \
+      -v <workDir>/<jobId>/downloads:/downloads:ro \
+      -p 127.0.0.1::5555 registry.lab.local:5000/dut-emulator:2026.08
+  ul.small
+    li The image must #[strong start the DUT by itself] (its #[code CMD]/#[code ENTRYPOINT]) and should listen on port #[strong 5555].
+    li The job's #[code --download-file] files are mounted read-only at #[code /downloads] (e.g. the firmware to emulate).
+    li The command reaches it at #[code $THUB_DUT_HOST] (#[code 127.0.0.1:<port>]) and by name as #[code $THUB_DUT_CONTAINER].
+    li Its output is shipped as the #[code emulator] log stream. Its root filesystem is read-only: don't install or clone into it.
+    li #[code thub run --dry-run] prints the exact docker commands a job would run, without running anything.
+
+  h3.h6 Execute commands in the DUT container
+  +code('SW job: talk to the DUT').
+    thub run --type sw \
+      --docker-image registry.lab.local:5000/dut-emulator:2026.08 \
+      --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.elf \
+      --command 'docker exec "$THUB_DUT_CONTAINER" /opt/emu/status &&
+                 docker logs "$THUB_DUT_CONTAINER" | tail -n 20 &&
+                 ./ci/test.sh --dut "$THUB_DUT_HOST"' \
+      --wait
+
+  h3.h6 Log in and pull inside a job (credentials scoped to the job)
+  p.small.
+    Pass the credentials as #[code --env] (masked everywhere, dropped when the job ends). Set #[code DOCKER_CONFIG] to the
+    job's work directory so the login is deleted with the workspace instead of staying in the service user's
+    #[code ~/.docker] for every later job:
+  +code('Any job type').
+    export DOCKER_PASSWORD=…        # from your CI secret store, never on the command line
+    thub run --type hw \
+      --env DOCKER_REGISTRY=registry.lab.local:5000,DOCKER_USER=ci --env DOCKER_PASSWORD \
+      --command 'export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
+                 echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
+                 docker pull "$DOCKER_REGISTRY/team/test-runner:1.4"' \
+      --wait
+
+  h3.h6 Run the tests inside a container (docker run parameters)
+  p.small.
+    The command always starts on the Client host, in #[code $THUB_WORK_DIR] (the #[code --git-repo] checkout). Mount it,
+    hand over the variables the tests need with #[code -e NAME], and use #[code --rm]:
+  +code('Tests in an image').
+    thub run --type sw \
+      --env DOCKER_REGISTRY=registry.lab.local:5000,DOCKER_USER=ci --env DOCKER_PASSWORD \
+      --env TARGET=staging \
+      --git-repo git@github.com:yourorg/web-ui-tests.git main \
+      --command 'export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
+                 echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
+                 docker run --rm \
+                   -v "$THUB_WORK_DIR:/work" -w /work \
+                   -e TARGET -e THUB_SUITE -e THUB_JOB_ID \
+                   --network host \
+                   "$DOCKER_REGISTRY/python:3.14" ./run-tests.sh --junit results/junit.xml' \
+      --wait
+  table.table.table-sm.small
+    thead
+      tr
+        th docker run option
+        th Why
+    tbody
+      tr
+        td: code --rm
+        td Removes the container when the tests end.
+      tr
+        td: code -v "$THUB_WORK_DIR:/work" -w /work
+        td The checkout and downloads, and the #[code results/] and #[code artifacts/] folders, which the Client uploads.
+      tr
+        td: code -e NAME
+        td Passes a job variable (#[code --env], #[code THUB_*], #[code JOB_*]) into the container.
+      tr
+        td: code --network host
+        td Lets the container reach the DUT at #[code $THUB_DUT_HOST] (#[code 127.0.0.1:<port>]).
+      tr
+        td: code --device /dev/thub/dut1-uart
+        td HW: gives the container the DUT's UART (#[code "$THUB_DUT_UART"]). Use #[code --privileged] only if you must.
+      tr
+        td: code --user "$(id -u):$(id -g)"
+        td Files written to #[code /work] stay owned by the Client user, so the workspace can be cleaned up.
+  +note('info').
+    Docker access is effectively root access on that host. The Client host must have Docker and the service user must be in the
+    #[code docker] group. The resource card's #[strong Capabilities] show whether a Client can use Docker, and why not.

package/views/help/_env.pug

@@ -0,0 +1,127 @@
++section('env', 'Environment variables on the Client', 'braces')
+  p.
+    #[code --command] runs on the Client with the service's own environment (#[code PATH], #[code HOME], …) plus three sets of
+    variables. Every value is a string. A variable whose option wasn't given is #[strong unset], so use
+    #[code ${VAR:-default}] in shell. A repeatable option gives one combined variable plus #[code NAME_1], #[code NAME_2], …
+    (1-based, in the order given).
+
+  h3.h6 Set by the Client: #[code THUB_*]
+  -
+    const thubVars = [
+      ['THUB_JOB_ID', 'The job id, e.g. M-00125'],
+      ['THUB_WORK_DIR', 'The directory the command runs in: the --git-repo checkout, else empty. results/ and artifacts/ in it are uploaded'],
+      ['THUB_SUITE', '--suite (default: default)'],
+      ['THUB_GIT_COMMIT', 'The exact commit checked out for --git-repo'],
+      ['THUB_DOWNLOADS_DIR', 'Where the --download-file files are'],
+      ['THUB_DOWNLOADS / THUB_DOWNLOAD_<n>', 'Local paths of the downloads: all, one per line / each one'],
+      ['THUB_META_<KEY>', '--meta values; camelCase keys become SNAKE_CASE (ciJobId → THUB_META_CI_JOB_ID)'],
+      ['THUB_DUT_STLINK / _<n>', 'HW: ST-Link serials (device path if the serial couldn\'t be read); unsuffixed = the first'],
+      ['THUB_DUT_UART / _<n>', 'HW: UART device paths (/dev/thub/dut<N>-uart); unsuffixed = the first'],
+      ['THUB_DUT_USB / _<n>', 'HW: DUT USB device paths'],
+      ['THUB_DUT_HOST', 'SW with --docker-image: 127.0.0.1:<port> of the DUT container\'s port 5555'],
+      ['THUB_DUT_CONTAINER', 'SW with --docker-image: the DUT container\'s name (docker exec / docker logs)']
+    ]
+  .table-responsive
+    table.table.table-sm.small
+      tbody
+        each v in thubVars
+          tr
+            td(style="width: 34%"): code= v[0]
+            td= v[1]
+
+  h3.h6 Job parameters: #[code JOB_*]
+  p.small Each #[code thub run] option that reaches the Client, as given:
+  -
+    const jobVars = [
+      ['JOB_TYPE', '--type', 'hw or sw'],
+      ['JOB_BOARD', '--board', 'the board name'],
+      ['JOB_LABEL / JOB_LABEL_<n>', '--board, --label', 'all labels, comma-separated / each'],
+      ['JOB_GROUP', '--group', 'the group id'],
+      ['JOB_CLIENT', '--client', 'this Client\'s name'],
+      ['JOB_USER', '--user', 'as given'],
+      ['JOB_COMMAND', '--command', 'the command itself'],
+      ['JOB_DOWNLOAD_FILE / _<n>', '--download-file', 'the URLs (the local files are THUB_DOWNLOAD_<n>)'],
+      ['JOB_DOCKER_IMAGE', '--docker-image', 'the image reference'],
+      ['JOB_GIT_REPO_URL', '--git-repo <url>', 'the repository URL'],
+      ['JOB_GIT_BRANCH', '--git-repo <url> <ref>', 'branch, tag or commit as given (unset = default branch)'],
+      ['JOB_GIT_DEPTH', '--depth', 'commits fetched (1 by default, 0 = full)'],
+      ['JOB_GIT_OPTIONS', '--git-options', 'as given'],
+      ['JOB_SUITE', '--suite', 'as given, default when not'],
+      ['JOB_ARG / JOB_ARG_<n>', '--arg', 'all, space-separated / each (also "$@")'],
+      ['JOB_TIMEOUT', '--timeout', 'seconds'],
+      ['JOB_PRIORITY', '--priority', '0–100'],
+      ['JOB_META_<KEY>', '--meta key=value', 'the value'],
+      ['<NAME>', '--env NAME=value', 'your own variables, under the names you chose']
+    ]
+  .table-responsive
+    table.table.table-sm.small
+      thead
+        tr
+          th Variable
+          th From
+          th Value
+      tbody
+        each v in jobVars
+          tr
+            td: code= v[0]
+            td: code.text-nowrap= v[1]
+            td= v[2]
+  p.small.
+    #[code --url], #[code --token], #[code --wait], #[code --detach], #[code --json] and #[code --dry-run] only affect the Agent and
+    have no variable. The Client's own git commands also get #[code GIT_TERMINAL_PROMPT=0] and #[code GIT_ALLOW_PROTOCOL=http:https:ssh:git].
+
+  h3.h6 Your own variables: #[code --env]
+  ul.small
+    li #[code --env NAME=value[,NAME=value]], repeatable. A comma starts a new variable only when #[code NAME=] follows it, so values may contain commas.
+    li #[code --env NAME] alone takes the value from the Agent's environment. That keeps secrets off the command line, out of shell history and out of CI logs.
+    li Any names except #[code THUB_*], #[code JOB_*], #[code GIT_TERMINAL_PROMPT] and #[code GIT_ALLOW_PROTOCOL].
+    li They apply to every command the Client runs for the job: the #[code --git-repo] git commands and #[code --command].
+    li
+      | Every value is treated as a secret. It's sent only to the Client running the job, shown as #[code ***] by the API,
+      | #[code thub status --json] and #[code --dry-run], and wiped from the Coordinator's database when the job ends.
+      | The dashboard lists only the names.
+  +note('warning').
+    The command's own output #[strong is] the job log, which is stored and visible on the dashboard. Never #[code echo] a
+    secret, and avoid #[code set -x] in scripts that use one.
+
+  h3.h6 Using them in your scripts
+  +code('ci/test.sh (shell)').
+    #!/bin/sh
+    set -eu
+    echo "Job $THUB_JOB_ID on $(hostname), suite ${THUB_SUITE}, commit ${THUB_GIT_COMMIT:-n/a}"
+
+    # optional parameters with defaults
+    TARGET="${TARGET:-staging}"
+    BRANCH="${JOB_GIT_BRANCH:-main}"
+
+    # every downloaded file
+    printf '%s\n' "$THUB_DOWNLOADS" | while read -r f; do echo "downloaded: $f"; done
+
+    # HW: flash through the first ST-Link, talk to the second UART
+    st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000
+    python3 -m pytest tests/ --uart "${THUB_DUT_UART_2:-$THUB_DUT_UART}" --junitxml=results/junit.xml
+
+    # CI metadata passed with --meta ciJobId=… / --meta sha=…
+    echo "CI run ${THUB_META_CI_JOB_ID:-local}, sha ${THUB_META_SHA:-unknown}"
+  +code('conftest.py (Python)').
+    import os
+
+    DUT_HOST  = os.environ.get("THUB_DUT_HOST", "127.0.0.1:5555")   # SW DUT container
+    UARTS     = [v for k, v in sorted(os.environ.items()) if k.startswith("THUB_DUT_UART_")]
+    FIRMWARE  = os.environ.get("THUB_DOWNLOAD_1")
+    RESULTS   = os.path.join(os.environ.get("THUB_WORK_DIR", "."), "results")
+    API_TOKEN = os.environ["API_TOKEN"]                              # from --env API_TOKEN
+  +code('Into a container: -e NAME copies a variable from the job').
+    docker run --rm -v "$THUB_WORK_DIR:/work" -w /work \
+      -e THUB_JOB_ID -e THUB_SUITE -e TARGET -e API_TOKEN \
+      python:3.14 ./run-tests.sh
+  +code('Submitting the job that feeds these').
+    export API_TOKEN=…
+    thub run --type hw --board nucleo-f401re \
+      --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
+      --git-repo git@github.com:yourorg/firmware-tests.git main \
+      --env TARGET=production --env API_TOKEN \
+      --meta ciJobId="$GITHUB_RUN_ID" --meta sha="$GITHUB_SHA" \
+      --suite smoke --command ./ci/test.sh --wait
+  p.small.text-body-secondary.mb-0.
+    Tip: #[code thub run … --dry-run] lists every variable the command would get on the chosen Client, with #[code --env] values as #[code ***].

package/views/help/_git.pug

@@ -0,0 +1,129 @@
++section('git', 'Git repository integration', 'git')
+  p.
+    #[code --git-repo] makes the Client clone a repository before the job runs. #[code --command] then runs inside the checkout
+    (#[code $THUB_WORK_DIR]). Typically the repository holds the test scripts. The firmware comes as a #[code --download-file]
+    or is built by the command.
+
+  h3.h6 1. Create a test repository
+  +code('Your machine').
+    mkdir firmware-tests && cd firmware-tests && git init -b main
+    mkdir -p ci
+    cat > ci/test.sh <<'EOF'
+    #!/bin/sh
+    set -eu
+    echo "job $THUB_JOB_ID, suite $THUB_SUITE, commit $THUB_GIT_COMMIT"
+    mkdir -p results
+    pytest --junitxml=results/junit.xml tests/     # results/*.xml is uploaded and summarized
+    EOF
+    chmod +x ci/test.sh
+    git add . && git commit -m "TestHub entry point"
+    git remote add origin git@github.com:yourorg/firmware-tests.git
+    git push -u origin main
+  p.small.
+    The exit code of #[code --command] is the verdict. JUnit files under #[code results/] or #[code artifacts/] are uploaded
+    as artifacts and summed into the job's test counts. Any other file there is uploaded too.
+
+  h3.h6 2. Give Clients read access: SSH deploy key (recommended)
+  p.small.
+    git never prompts on a Client (#[code GIT_TERMINAL_PROMPT=0]), so credentials must already be on the Client host,
+    owned by the #[strong Client's service user]. Create a key on each Client host (or one shared key per lab):
+  +code('Client host, as the Client\'s user').
+    ssh-keygen -t ed25519 -N "" -C "thub-client@$(hostname)" -f ~/.ssh/thub_deploy
+    cat ~/.ssh/thub_deploy.pub          # → add as a read-only deploy key (below)
+    # trust the git server's host key now: the service can't answer prompts
+    # (and can't write ~/.ssh under systemd)
+    ssh-keyscan github.com bitbucket.org gitlab.com >> ~/.ssh/known_hosts
+    # use the key for that server
+    cat >> ~/.ssh/config <<'EOF'
+    Host github.com
+      IdentityFile ~/.ssh/thub_deploy
+      IdentitiesOnly yes
+    EOF
+    chmod 600 ~/.ssh/config
+    ssh -T git@github.com                # "…successfully authenticated…"
+  table.table.table-sm.small
+    thead
+      tr
+        th Git server
+        th Where to add the public key
+    tbody
+      tr
+        td GitHub
+        td Repository → Settings → Deploy keys → Add deploy key (leave “Allow write access” off). For many repositories, use a machine user's SSH key instead.
+      tr
+        td GitLab
+        td Project → Settings → Repository → Deploy keys.
+      tr
+        td Bitbucket
+        td Repository settings → Security → Access keys.
+      tr
+        td Gitea / self-hosted
+        td Repository → Settings → Deploy Keys, or the machine user's SSH keys.
+  p.small.
+    Without #[code ~/.ssh/config], pick the key per job with #[code --git-options] (stored with the job, so reference a key
+    #[em file], never inline a secret):
+  +code('Per-job SSH key / port').
+    thub run --type sw \
+      --git-repo ssh://git@git.lab.local:2222/qa/tests.git main \
+      --git-options '-c core.sshCommand="ssh -i ~/.ssh/thub_deploy -o IdentitiesOnly=yes"' \
+      --command ./ci/test.sh --wait
+
+  h3.h6 HTTPS with a token
+  p.small.
+    For #[code https://] repositories, either store a credential helper for the Client's user on the host
+    (#[code git config --global credential.helper store]), or pass the token #[strong per job] as a secret. #[code --env]
+    variables reach the Client's own git commands, and git reads config from #[code GIT_CONFIG_COUNT]/#[code _KEY_n]/#[code _VALUE_n]:
+  +code('Token per job, never stored').
+    # GitHub: user x-access-token; GitLab: oauth2; Bitbucket: x-token-auth
+    export GIT_CONFIG_VALUE_0="Authorization: Basic $(printf 'x-access-token:%s' "$GH_TOKEN" | base64 | tr -d '\n')"
+    thub run --type sw \
+      --git-repo https://github.com/yourorg/private-tests.git main \
+      --env GIT_CONFIG_COUNT=1,GIT_CONFIG_KEY_0=http.extraHeader --env GIT_CONFIG_VALUE_0 \
+      --command ./ci/test.sh --wait
+  p.small.
+    Don't put a token in the URL, #[code --git-options], #[code --command] or #[code --meta]: those are stored with the job
+    and visible to anyone who can read it. Only #[code --env] values are masked.
+
+  h3.h6 3. Clone options: ref, branch, tag, commit, depth
+  +code('--git-repo <url> [<branch>|<tag>|<commit>] [--depth <n>]').
+    --git-repo git@github.com:yourorg/tests.git                   # default branch, depth 1
+    --git-repo git@github.com:yourorg/tests.git develop           # a branch
+    --git-repo git@github.com:yourorg/tests.git v1.4.0            # a tag
+    --git-repo git@github.com:yourorg/tests.git a1b2c3d           # a commit (may be abbreviated)
+    --git-repo git@github.com:yourorg/tests.git main --depth 50   # last 50 commits
+    --git-repo git@github.com:yourorg/tests.git main --depth 0    # full history (git describe, changelogs)
+  table.table.table-sm.small
+    tbody
+      tr
+        th Transports
+        td #[code https://], #[code http://], #[code ssh://], #[code git://], #[code user@host:path]. #[code file://] and #[code ext::] are refused.
+      tr
+        th Default ref
+        td The repository's default branch.
+      tr
+        th Depth
+        td Default #[code 1]. #[code 0] = full history. If the server can't do shallow fetches (or the commit is abbreviated), the Client falls back to a full fetch.
+      tr
+        th Exact commit
+        td Logged, and passed to the command as #[code $THUB_GIT_COMMIT]. The requested ref is #[code $JOB_GIT_BRANCH].
+      tr
+        th Extra git options
+        td #[code --git-options] is inserted between #[code git] and its subcommand on every git call, e.g. #[code '-c http.sslVerify=false'] or #[code '-c core.sshCommand="…"'].
+  +code('What the Client runs (see it with --dry-run)').
+    git -C &lt;work> init -q
+    git -C &lt;work> remote add origin &lt;url>
+    git -C &lt;work> fetch -q --depth 1 origin &lt;ref>
+    git -C &lt;work> checkout -q --detach FETCH_HEAD
+    git -C &lt;work> rev-parse HEAD
+
+  h3.h6 Submodules, LFS and cloning inside a container
+  p.small.
+    The Client checks out only the repository itself. Do anything more in the command, which runs in the checkout with the same #[code --env] variables:
+  +code('Submodules / LFS').
+    thub run --type sw --git-repo git@github.com:yourorg/tests.git main \
+      --command 'git submodule update --init --recursive --depth 1 && git lfs pull && ./ci/test.sh' --wait
+  +code('Clone yourself, e.g. inside a container (JOB_GIT_* carry the --git-repo values)').
+    thub run --type sw --git-repo git@github.com:yourorg/tests.git main --depth 1 \
+      --command 'docker run --rm -v "$HOME/.ssh:/root/.ssh:ro" -e JOB_GIT_REPO_URL -e JOB_GIT_BRANCH -e JOB_GIT_DEPTH \
+                   --entrypoint sh alpine/git -c "git clone --depth \$JOB_GIT_DEPTH --branch \$JOB_GIT_BRANCH \$JOB_GIT_REPO_URL /src && ls /src"' \
+      --wait

package/views/help/_mixins.pug

@@ -0,0 +1,24 @@
+//- Help page building blocks. Code blocks are plain text: escape `<` as
+//- `&lt;` inside them (`>` and `&&` are fine). public/js/help.js adds a copy
+//- button to each, which copies the decoded text.
+mixin code(caption)
+  figure.thub-code.mb-3
+    if caption
+      figcaption.thub-code-caption= caption
+    pre
+      code
+        block
+
+//- One section of the help page: an anchor for the table of contents and a
+//- heading. `data-help-section` is what the filter box searches.
+mixin section(id, heading, icon)
+  section.thub-help-section.mb-5(id=id data-help-section)
+    h2.h4.border-bottom.pb-2.mb-3
+      if icon
+        i.bi.me-2.text-body-secondary(class=`bi-${icon}`)
+      = heading
+    block
+
+mixin note(tone)
+  .alert.small.py-2(class=`alert-${tone || 'info'}`)
+    block