@andrian.yablonskyy/thub-coordinator 1.1.12 → 1.1.13

package/views/help/_agent-cli.pug

@@ -23,20 +23,15 @@
         ['--client <name|id>', 'Only this Client; waits for it even if others are idle.', '--client lab-hw-01']
       ] },
       { title: 'What to run', rows: [
-        ['--command <string>', 'Required. Run with sh -c in the work directory. Exit code 0 = PASSED.', "--command './ci/test.sh'"],
+        ['--command <string>', 'Required. Run with sh -c in the work directory. Exit code 0 = PASSED. It clones repositories and runs containers itself (see Using git / Using Docker).', "--command './ci/test.sh'"],
         ['--arg <value>', 'Argument for the command, as "$@" (repeatable).', '--arg --junit --arg -v'],
         ['--suite <name>', 'Passed as THUB_SUITE (default: default).', '--suite smoke'],
         ['--download-file <url>', 'File downloaded before the command (repeatable, http(s), no credentials). THUB_DOWNLOAD_1…', '--download-file https://…/app.bin'],
-        ['--git-repo <url> [ref]', 'Repository cloned first; the command runs in it.', '--git-repo git@github.com:org/tests.git v1.4.0'],
-        ['--depth <n>', 'Commits to fetch with --git-repo (default 1, 0 = full).', '--depth 0'],
-        ['--git-options <string>', 'Extra git options between git and its subcommand. Stored with the job.', '--git-options \'-c core.sshCommand="ssh -i ~/.ssh/k"\''],
-        ['--docker-image <ref>', 'SW only: DUT container image, pulled with the Client host’s Docker login.', '--docker-image registry.lab:5000/emu:1'],
-        ['--env <vars>', 'NAME=value[,NAME=value] for git and the command (repeatable). --env NAME takes the value from your shell. Masked, dropped at job end.', '--env TARGET=staging --env API_TOKEN']
+        ['--env <vars>', 'NAME=value[,NAME=value] for the command (repeatable): how data and secrets reach the job (git tokens, registry passwords). --env NAME takes the value from your shell. Masked, dropped at job end.', '--env TARGET=staging --env API_TOKEN']
       ] },
       { title: 'Job settings', rows: [
         ['--timeout <dur>', 'e.g. 30m, 1h (default 30m, capped by the Coordinator).', '--timeout 1h'],
         ['--priority <n>', '0–100. Defaults: ci 50, cli 60.', '--priority 80'],
-        ['--user <name>', 'Free-text owner label. Default: THUB_USER / config.', '--user alice'],
         ['--meta <key=value>', 'Metadata stored on the job (repeatable). The command sees THUB_META_<KEY>.', '--meta ciJobId=$GITHUB_RUN_ID'],
         ['--dry-run', 'Schedule for real, but only log what the Client would run.', '--dry-run']
       ] },
@@ -74,12 +69,13 @@
   +code('Flash and test a board, fail CI on failure').
     thub run --type hw --label board:nucleo-f401re \
       --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
-      --git-repo https://github.com/yourorg/firmware-tests.git v1.4.0 \
-      --command 'st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh "$@"' \
+      --env GH_TOKEN \
+      --command 'git clone --depth 1 --branch v1.4.0 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" . &&
+                 st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh "$@"' \
       --arg --junit --timeout 45m --wait
-  +code('Reproduce a failure on the exact bench, labeled with your name').
-    thub run --type hw --label board:nucleo-f401re --client lab-hw-01 --user "$USER" \
-      --download-file "$IMAGE_URL" --git-repo "$TESTS_REPO" --command ./ci/test.sh
+  +code('Reproduce a failure on the exact bench (the job carries your username)').
+    thub run --type hw --label board:nucleo-f401re --client lab-hw-01 \
+      --download-file "$IMAGE_URL" --env GH_TOKEN --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@$TESTS_REPO" . && ./ci/test.sh'
     # Ctrl-C detaches; the job keeps running. Re-attach:
     thub status M-00126
   +code('Verify a download before using it').
@@ -87,14 +83,14 @@
       --command 'echo "8f15bf27…  $THUB_DOWNLOAD_1" | sha256sum -c && ./flash.sh "$THUB_DOWNLOAD_1"' --wait
   +code('Secrets and parameters').
     export API_TOKEN=…
-    thub run --type sw --git-repo "$TESTS_REPO" \
+    thub run --type sw \
       --env TARGET=staging,LOG_LEVEL=debug --env API_TOKEN \
       --command './run-tests.sh --target "$TARGET"' --suite regression --wait
   +code('Preview exactly what would run (nothing is executed)').
-    thub run --type sw --docker-image alpine --git-repo https://example.invalid/tests.git main \
+    thub run --type sw --download-file https://example.invalid/app.bin \
       --command ./ci/test.sh --dry-run --wait
   +code('Scripting: submit, poll, read the result').
-    JOB=$(thub run --type sw --git-repo "$TESTS_REPO" --command ./ci/test.sh --detach --json | jq -r .jobId)
+    JOB=$(thub run --type sw --command ./ci/test.sh --detach --json | jq -r .jobId)
     while thub status "$JOB" --json > job.json; [ $? -eq 5 ]; do sleep 10; done
     jq -r '"\(.state) exit=\(.exit_code) tests=\(.summary.total // 0) failed=\(.summary.failed // 0)"' job.json
   +code('Lists').

package/views/help/_agent-setup.pug

@@ -42,7 +42,6 @@
   +code('Save the settings once').
     thub config set url   #{coordinatorUrl}
     thub config set key   thk_…
-    thub config set user  "Your Name"      # optional: job owner label
   p.small.
     These are saved in #[code ~/.config/thub/agent.json]. Which runner group your jobs run in isn't an Agent
     setting: an admin or maintainer sets it for your user on the dashboard (#[code thub whoami] shows it). Order of precedence: flags (#[code --url], #[code --key]) →
@@ -59,9 +58,6 @@
       tr
         td: code THUB_KEY
         td Your access key, or a CI token in a pipeline. Keep it in your CI's secret store. (#[code THUB_TOKEN], #[code --token] and a saved #[code token] still work: the old names.)
-      tr
-        td: code THUB_USER
-        td Default #[code --user]
       tr
         td: code THUB_NO_SELF_UPDATE=1
         td Don't install admin-requested Agent updates on this machine

package/views/help/_ci.pug

@@ -33,8 +33,9 @@
               npx -y @andrian.yablonskyy/thub-agent run \
                 --type hw --label board:nucleo-f401re \
                 --download-file "${{ needs.build.outputs.image_url }}" \
-                --git-repo "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY.git" "$GITHUB_SHA" \
-                --command 'st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/hw-tests.sh' \
+                --env GH_TOKEN="${{ secrets.TESTS_READ_TOKEN }}",SHA="$GITHUB_SHA",REPO="$GITHUB_REPOSITORY" \
+                --command 'git init -q . && git fetch -q --depth 1 "https://x-access-token:$GH_TOKEN@github.com/$REPO.git" "$SHA" && git checkout -q FETCH_HEAD &&
+                           st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/hw-tests.sh' \
                 --suite smoke --timeout 30m --wait \
                 --meta runUrl="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
   ul.small.mb-0

package/views/help/_client-machines.pug

@@ -26,8 +26,8 @@
         .card-body.small
           ul.mb-0
             li Any Linux host: bare metal, a VM (Proxmox, VMware, Hyper-V, KVM) or a cloud instance.
-            li Docker Engine (#[code docker.io]), with the Client's service user in the #[code docker] group (the installer arranges this).
-            li Each job's DUT container is limited to 2 CPUs and 2 GB RAM. Size the VM for one job plus your test tools: 4 vCPU, 8 GB RAM and 40 GB+ disk for images and workspaces is a good start.
+            li Whatever your jobs' commands use: git, Docker Engine (#[code docker.io]; install it before the Client so its service user gets the #[code docker] group), an emulator. The Client itself needs none of them.
+            li Size the VM for one job plus your test tools: 4 vCPU, 8 GB RAM and 40 GB+ disk for images and workspaces is a good start.
             li For KVM-accelerated emulators (QEMU) inside a VM, turn on #[strong nested virtualization].
             li No USB or udev setup.
 
@@ -52,8 +52,9 @@
   +code('A typical HW job').
     thub run --type hw --label board:nucleo-f401re \
       --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
-      --git-repo https://github.com/yourorg/firmware-tests.git v1.4.0 \
-      --command 'st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh' \
+      --env GH_TOKEN \
+      --command 'git clone --depth 1 --branch v1.4.0 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" . &&
+                 st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh' \
       --wait
 
   +note('warning').
@@ -62,26 +63,26 @@
 
   h3.h6 Preparing an SW machine (real or virtual)
   +code('SW machine / VM').
-    sudo apt install -y nodejs npm docker.io
+    sudo apt install -y nodejs npm         # + git, docker.io, … if your jobs' commands use them
     sudo npm i -g @andrian.yablonskyy/thub-client
     nano ~/.config/thub/client.json        # "type": "sw", coordinatorUrl, joinKey
     sudo systemctl enable --now thub-client@client
-    # a private registry for DUT images? log in once, as the Client's user:
-    docker login registry.lab.local:5000
   p.small.
     To scale out, clone the VM template. In the clone, #[strong before its first start], run
     #[code rm -f ~/var/lib/thub/client/*/.client-id ~/var/lib/thub/client/*.token] and give it its own #[code name].
     Otherwise both VMs register as the same runner.
   +code('A typical SW job').
     thub run --type sw \
-      --docker-image registry.lab.local:5000/dut-emulator:2026.08 \
-      --git-repo git@github.com:yourorg/firmware-tests.git main \
-      --command 'make test DUT="$THUB_DUT_HOST"' --wait
+      --env GH_TOKEN --env DOCKER_PASSWORD \
+      --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" . &&
+                 export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
+                 echo "$DOCKER_PASSWORD" | docker login registry.lab.local:5000 -u ci --password-stdin &&
+                 docker run --rm -v "$PWD:/work" -w /work registry.lab.local:5000/dut-emulator:2026.08 make test' --wait
 
   h3.h6 Checklist for any Client machine
   ul.small.mb-0
     li Correct time (NTP). Timestamps are anchored to the Coordinator's clock, but TLS needs a sane clock.
     li Outbound HTTPS to the Coordinator; test it with #[code curl -sI #{coordinatorUrl}/login].
-    li The Client's service user has SSH keys and git credentials for private repos (#[a(href="#git") Git repositories]) and Docker logins for private registries (#[a(href="#docker") Docker registry]).
+    li Whatever tools your jobs' commands use (git, docker, a flasher) are installed. Their credentials come with each job as #[code --env] (#[a(href="#git") Using git], #[a(href="#docker") Using Docker]), not from the host.
     li Under systemd, the service can only write to its state directory. Jobs write to #[code $THUB_WORK_DIR], not to #[code ~].
     li Optional: a nightly reboot from the runner card's #[strong Reboot] tab (cron, host-local time). It waits for running jobs.

package/views/help/_client-setup.pug

@@ -8,8 +8,8 @@
   +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.
+    # Optional — the Client doesn't need it. Only if your jobs' commands run 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.
@@ -66,7 +66,7 @@
         tr
           td: code type
           td Yes
-          td #[code hw] (physical DUT) or #[code sw] (DUT image in Docker).
+          td #[code hw] (physical DUT) or #[code sw] (software-only: jobs run just their command).
         tr
           td: code joinKey
           td Yes
@@ -100,7 +100,7 @@
           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]).
+    SW Clients have no settings of their own: a job's #[code --command] starts whatever it needs (a container, an emulator).
     Admins can also edit an HW Client's devices from its runner card (#[strong ST-Link | UART | DUT USB]
     tabs). The tabs show the config the Client runs, as it reported it at its last start, or a saved
     change it hasn't applied yet. #[strong USB devices → Import to config] fills them from the host's #[code lsusb].

package/views/help/_docker.pug

@@ -1,99 +1,24 @@
-+section('docker', 'Docker registry integration', 'box-seam')
++section('docker', 'Using Docker in a job', '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.
+    The Client doesn't pull images or start containers itself and doesn't need Docker. A job that needs a container runs
+    #[code docker] in its #[code --command], on a Client host that has Docker (the runner card's #[strong Capabilities] tab says
+    whether it does). Registry credentials come from the job as #[code --env]: masked everywhere, dropped when the job ends.
 
-  h3.h6 Log in to a registry on the Client host (for --docker-image)
+  h3.h6 Log in, pull and run, credentials scoped to the job
   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:
+    Point #[code DOCKER_CONFIG] at the job's directory so the login is deleted with the job 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 \
+                   -v "$THUB_WORK_DIR:/work" -w /work --user "$(id -u):$(id -g)" \
                    -e TARGET -e THUB_SUITE -e THUB_JOB_ID \
-                   --network host \
-                   "$DOCKER_REGISTRY/python:3.14" ./run-tests.sh --junit results/junit.xml' \
+                   "$DOCKER_REGISTRY/team/test-runner:1.4" ./run-tests.sh --junit results/junit.xml' \
       --wait
   table.table.table-sm.small
     thead
@@ -106,19 +31,31 @@
         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, where the Client reads JUnit XML for the test counts.
+        td The work directory, where the Client reads JUnit XML under #[code results/] and #[code artifacts/] for the test counts.
       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>]).
+        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.
       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.
+
+  h3.h6 An emulator as the DUT
+  p.small.
+    Start it in the background in the command, talk to it, and stop it whatever the result:
+  +code('SW job with an emulator container').
+    thub run --type sw \
+      --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.elf \
+      --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 &&
+                 dut="thub-$THUB_JOB_ID" && trap "docker rm -f $dut >/dev/null" EXIT &&
+                 docker run -d --name "$dut" -p 127.0.0.1:5555:5555 -v "$THUB_DOWNLOADS_DIR:/downloads:ro" \
+                   "$DOCKER_REGISTRY/dut-emulator:2026.08" &&
+                 ./ci/test.sh --dut 127.0.0.1:5555' \
+      --wait
   +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 runner card's #[strong Capabilities] tab shows whether a Client can use Docker, and why not.
+    Docker access is effectively root access on that host. The service user needs the #[code docker] group: install Docker
+    before the Client (#[code sudo npm i -g …] adds the group), or re-run the install afterwards.

package/views/help/_env.pug

@@ -10,17 +10,14 @@
     const thubVars = [
       ['THUB_JOB_ID', 'The job id, e.g. M-00125'],
       ['THUB_ARTIFACTS_FILE', 'Where the command may list the artifacts it published elsewhere: a JSON array of {"name", "size", "link", "timestamp"}, shown on the job page'],
-      ['THUB_WORK_DIR', 'The directory the command runs in: the --git-repo checkout, else empty. JUnit XML in results/ or artifacts/ gives the test counts; deleted when the job ends'],
+      ['THUB_WORK_DIR', 'The directory the command runs in, empty at the start (clone into it if you need a repository). JUnit XML in results/ or artifacts/ gives the test counts; deleted when the job ends'],
       ['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)']
+      ['THUB_DUT_USB / _<n>', 'HW: DUT USB device paths']
     ]
   .table-responsive
     table.table.table-sm.small
@@ -38,14 +35,9 @@
       ['JOB_LABEL / JOB_LABEL_<n>', '--label', 'all labels, comma-separated / each'],
       ['JOB_GROUP', '(dashboard)', 'the submitting agent\'s group, if it has one'],
       ['JOB_CLIENT', '--client', 'this Client\'s name'],
-      ['JOB_USER', '--user', 'as given'],
+      ['JOB_USER', '(your key)', 'the submitting user\'s username, or the CI token\'s name'],
       ['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'],
@@ -74,8 +66,8 @@
   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 Any names except #[code THUB_*] and #[code JOB_*].
+    li They're how every piece of data and every secret reaches the job: a git token for its #[code git clone], a registry password for its #[code docker login], an API key for its tests.
     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.
@@ -88,11 +80,11 @@
   +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}"
+    echo "Job $THUB_JOB_ID on $(hostname), suite ${THUB_SUITE}"
 
     # optional parameters with defaults
     TARGET="${TARGET:-staging}"
-    BRANCH="${JOB_GIT_BRANCH:-main}"
+    BRANCH="${BRANCH:-main}"          # from --env BRANCH=…
 
     # every downloaded file
     printf '%s\n' "$THUB_DOWNLOADS" | while read -r f; do echo "downloaded: $f"; done
@@ -106,7 +98,6 @@
   +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")
@@ -119,9 +110,10 @@
     export API_TOKEN=…
     thub run --type hw --label 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 \
+      --env TARGET=production,BRANCH=main --env API_TOKEN --env GH_TOKEN \
       --meta ciJobId="$GITHUB_RUN_ID" --meta sha="$GITHUB_SHA" \
-      --suite smoke --command ./ci/test.sh --wait
+      --suite smoke \
+      --command 'git clone --depth 1 --branch "$BRANCH" "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" . &&
+                 ./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

@@ -1,130 +1,43 @@
-+section('git', 'Git repository integration', 'git')
++section('git', 'Using git in a job', '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.
+    The Client doesn't clone anything itself and doesn't need git installed for its own sake. A job that needs a repository
+    clones it in #[code --command], into its work directory (#[code $THUB_WORK_DIR], where the command starts), with the
+    credentials passed as #[code --env]. #[code --env] values are masked everywhere and dropped when the job ends. Anything
+    else (the URL, the command, #[code --meta]) is stored with the job and visible to anyone who can read it, so never put a
+    token there.
 
-  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 summed into
-    the job's test counts. Nothing is uploaded: the workspace is deleted when the job ends, so publish anything you need to keep
-    from the command itself (e.g. #[code curl -T report.html "$ARTIFACTORY/…"] with a token passed as #[code --env]).
-
-  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').
+  h3.h6 HTTPS with a token (recommended)
+  +code('Token from your CI secret store').
+    export GH_TOKEN=…      # GitHub: a fine-grained PAT with read access; GitLab: oauth2 token; Bitbucket: x-token-auth
     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
+      --env GH_TOKEN \
+      --command 'git clone --depth 1 --branch main "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" . &&
+                 ./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.
+    The token appears only inside the command's environment. To keep it out of #[code .git/config] as well, pass it as a header:
+    #[code git -c http.extraHeader="Authorization: Bearer $GH_TOKEN" clone …].
 
-  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 SSH with a key from the job
+  +code('Private key as --env (base64), used for this job only').
+    export DEPLOY_KEY_B64="$(base64 &lt; ~/.ssh/thub_deploy | tr -d '\n')"
+    thub run --type hw --label board:nucleo-f401re \
+      --env DEPLOY_KEY_B64 \
+      --command 'umask 077 && echo "$DEPLOY_KEY_B64" | base64 -d > "$THUB_WORK_DIR/../key" &&
+                 GIT_SSH_COMMAND="ssh -i $THUB_WORK_DIR/../key -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new" \
+                   git clone --depth 1 git@github.com:yourorg/firmware-tests.git . &&
+                 ./ci/test.sh' \
+      --wait
+  p.small.
+    The job directory, key included, is deleted when the job ends. Add the public key as a read-only deploy key: GitHub,
+    Repository → Settings → Deploy keys; GitLab, Settings → Repository → Deploy keys; Bitbucket, Repository settings → Access keys.
 
-  h3.h6 Submodules, LFS and cloning inside a container
+  h3.h6 Branch, tag, commit, submodules, LFS
+  +code('All in the command').
+    git clone --depth 1 --branch v1.4.0 "$REPO" .                            # a branch or tag
+    git init -q . && git remote add origin "$REPO" && git fetch -q --depth 1 origin a1b2c3d && git checkout -q FETCH_HEAD   # a commit
+    git submodule update --init --recursive --depth 1 && git lfs pull        # submodules / LFS
   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
+    Pass the repository and ref as #[code --env REPO=…,REF=…] (or #[code --meta]) so the same command works for every branch.
+    The exit code of #[code --command] is the verdict; JUnit files under #[code results/] or #[code artifacts/] are summed into
+    the job's test counts. Nothing is uploaded: publish what you need to keep from the command (#[code curl -T …] with a token in #[code --env]).

package/views/help/_overview.pug

@@ -39,7 +39,7 @@
   ol.small
     li #[code thub run …] submits a job spec (type, labels, command, inputs) with your access key (or a pipeline's CI token).
     li The Coordinator queues it (#[code QUEUED]) and the scheduler assigns it to an idle Client whose type, labels and group match.
-    li The Client accepts it, clones #[code --git-repo], downloads #[code --download-file] files and prepares the DUT (#[code PREPARING]).
+    li The Client accepts it, downloads #[code --download-file] files and prepares the DUT (#[code PREPARING]).
     li It runs #[code --command] with #[code sh -c], and output streams live to the Agent and the dashboard (#[code RUNNING]).
     li The exit code is the verdict: #[code 0] = #[code PASSED], anything else = #[code FAILED]. The Client reports the JUnit test counts; the job's files stay on the Client and are deleted with its workspace.
     li The Agent exits with the verdict code, so a CI step passes or fails with it.
@@ -102,7 +102,7 @@
   -
     const useCases = [
       { icon: 'cpu', title: 'Hardware-in-the-loop CI', text: 'Every push builds firmware in the cloud, then a GitHub Actions test job runs `thub run --type hw --wait`: a lab Client flashes a real board through ST-Link, captures its UART, runs the tests and fails the pipeline on a non-zero exit.' },
-      { icon: 'pc-display', title: 'Emulator (SW) test farms', text: 'SW Clients on real or virtual Linux machines run each job’s DUT image (QEMU, Renode, a simulator) in a sandboxed Docker container. The tests talk to it at $THUB_DUT_HOST. Scale out by adding VMs.' },
+      { icon: 'pc-display', title: 'Emulator (SW) test farms', text: 'SW Clients on real or virtual Linux machines run each job’s command, which starts its emulator (QEMU, Renode, a simulator) — in Docker if it likes — and tests it. Scale out by adding VMs.' },
       { icon: 'person-workspace', title: 'Remote access for developers', text: 'Developers reproduce a CI failure on the exact bench it happened on (`--client lab-hw-01`) from home, with the same command CI ran, and stream the board’s console live.' },
       { icon: 'lock', title: 'Shared benches without collisions', text: 'The scheduler hands out one job per bench. An engineer who needs a board by hand runs `thub-client lock` so nothing is scheduled there until `unlock`.' },
       { icon: 'collection', title: 'Dedicated pools', text: 'Groups and labels (`board:nucleo-f401re`, `uart`) route jobs to the right hardware, e.g. a nightly pool separate from the PR pool.' },