@andrian.yablonskyy/thub-coordinator 1.1.11 → 1.1.13

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.' },

package/views/help/_quick-start.pug

@@ -14,7 +14,7 @@
       strong Install a Client
       |  on each lab machine, with the same join key (#[a(href="#client-setup") Client setup]):
       +code('Lab machine (Ubuntu 26.04)').
-        sudo apt install -y nodejs npm docker.io      # + stlink-tools openocd for HW
+        sudo apt install -y nodejs npm                # + your jobs' tools: stlink-tools openocd, git, docker.io…
         sudo npm i -g @andrian.yablonskyy/thub-client
         nano ~/.config/thub/client.json               # coordinatorUrl, type, joinKey
         sudo systemctl enable --now thub-client@client

package/views/help/_troubleshooting.pug

@@ -8,7 +8,9 @@
       ['Name already in use (`409`)', 'Another live Client holds that name. Rename one of them in its config or from the runner card. A name held by an `OUT_OF_SERVICE` runner is reclaimed automatically.'],
       ['The job is rejected with `422`', 'No registered Client can ever match its type, labels, group or client. Compare `thub resources` with your `--type` and `--label`s; your group (set on the dashboard, see `thub whoami`) must have a Client of that kind.'],
       ['The job stays `QUEUED`', 'Matching Clients are all `BUSY`, locked (`local`), in `MAINTENANCE` or offline, or the job is pinned with `--client`. It times out after `--timeout`.'],
-      ['`ERROR` during prepare', 'The clone, download or DUT image pull failed; the job log names the reason. For git, check the Client user\'s keys and `known_hosts` (`ssh -T git@<host>` as that user). For images, check the Client user\'s `docker login`.'],
+      ['`ERROR` during prepare', 'A download failed; the job log names the URL and the reason.'],
+      ['A git clone or docker pull in the command fails', 'They run in your `--command`, with the credentials you pass as `--env` (see Using git / Using Docker). `git` or `docker` must be installed on that Client host; the Client itself needs neither. Try the command with `--dry-run` to see its environment.'],
+      ['`--git-repo` / `--docker-image`: unknown option, or the job is refused', 'They were removed: clone the repository and run containers in `--command`, passing tokens with `--env`. An older Agent that still sends them is refused with that message; update it (`thub self-update`).'],
       ['Permission denied on `/dev/ttyUSB*` or `docker.sock`', 'Docker or the device groups were added after the Client was installed. Re-run `sudo npm i -g @andrian.yablonskyy/thub-client` so the unit gets the `dialout`/`plugdev`/`docker` groups, then restart.'],
       ['A configured device is shown as missing', 'Check the `devpath` with `udevadm info -a -n <dev>`, then `thub-client udev --print`; restart the Client to regenerate the udev rules.'],
       ['Job `LOST`', 'The Client missed 3 heartbeats (network, reboot, crash). With `requeueOnLost` the job is retried once on another Client.'],

package/views/help/index.pug

@@ -11,8 +11,8 @@ block content
       { id: 'agent-setup', label: 'Agent setup' },
       { id: 'client-setup', label: 'Client setup' },
       { id: 'client-machines', label: 'Client machines (HW / SW)' },
-      { id: 'docker', label: 'Docker registry' },
-      { id: 'git', label: 'Git repositories' },
+      { id: 'docker', label: 'Using Docker' },
+      { id: 'git', label: 'Using git' },
       { id: 'agent-cli', label: 'Agent CLI reference' },
       { id: 'env', label: 'Environment variables' },
       { id: 'ci', label: 'CI/CD (GitHub Actions)' },

package/views/index.pug

@@ -49,6 +49,7 @@ block scripts
   script(src="/js/resource-card.js")
   script(src="/js/remove-resource.js")
   script(src="/js/client-config.js")
+  script(src="/js/tag-picker.js")
   script(src="/js/usb-scan.js")
   script(src="/js/usb-parse.js")
   script(src="/js/usb-import.js")

package/views/mixins/client-config.pug

@@ -183,19 +183,35 @@ mixin groupsPane(r, returnTo, groupsById)
         data-confirm-tone="primary"
       )
         input(type="hidden" name="returnTo" value=returnTo)
-        fieldset(disabled=!canEdit || r.config_support !== 'file')
-          .list-group.mb-2
-            each g in all
-              label.list-group-item.d-flex.gap-2.align-items-start
-                input.form-check-input.flex-shrink-0.mt-1(type="checkbox" name="groups" value=g.id checked=r.group_ids.includes(g.id))
-                span
-                  span.fw-medium= g.name
-                  if g.comment
-                    span.small.text-body-secondary= ` — ${g.comment}`
-            each id in unknown
-              label.list-group-item.d-flex.gap-2.align-items-start
-                input.form-check-input.flex-shrink-0.mt-1(type="checkbox" name="groups" value=id checked)
-                span.text-body-secondary (a deleted group)
+        - const editable = canEdit && r.config_support === 'file'
+        fieldset(disabled=!editable)
+          //- Chips for its groups, a search box to add more (public/js/tag-picker.js):
+          //- each chip carries its hidden `groups` input; ✕ removes it.
+          .thub-tags.mb-2(data-tag-picker data-tag-name="groups" data-options=JSON.stringify(all.map((g) => ({ value: g.id, label: g.name, hint: g.comment || '' }))))
+            .thub-tags-box.form-control(data-tag-box)
+              each id in r.group_ids
+                span.thub-tag(data-tag=id)
+                  span= groupsById[id] ? groupsById[id].name : '(a deleted group)'
+                  input(type="hidden" name="groups" value=id)
+                  if editable
+                    button.thub-tag-remove(type="button" data-tag-remove aria-label=`Remove ${groupsById[id] ? groupsById[id].name : 'deleted group'}`)
+                      i.bi.bi-x
+              if editable
+                input.thub-tags-input(
+                  type="text"
+                  data-tag-input
+                  placeholder="Add a group…"
+                  aria-label=`Add a group to ${r.name}`
+                  role="combobox"
+                  aria-autocomplete="list"
+                  aria-expanded="false"
+                  aria-controls=`${p}-groups-menu`
+                  autocomplete="off"
+                  spellcheck="false"
+                )
+            ul.dropdown-menu.thub-tags-menu(id=`${p}-groups-menu` role="listbox" data-tag-menu)
+            if !r.group_ids.length && !editable
+              span.small.text-body-secondary none
           .form-text An agent given a group (on Users or CI tokens) runs its jobs only on Clients in it; an agent without one, on any Client.
           if canEdit && r.config_support === 'file'
             .d-flex.justify-content-end.mt-3

package/views/mixins/resource.pug

@@ -135,12 +135,12 @@ mixin capDevice(d, detail)
       ) missing
 
 //- What the Client reported it can drive at registration (HW: udev
-//- devices; SW: nothing of its own — it runs each job's DUT image).
+//- devices; SW: nothing of its own — a job's command brings what it runs).
 mixin capabilitiesList(caps)
   if !caps
     span.text-body-secondary —
   else if caps.sw
-    span.text-body-secondary Runs each job's own DUT image (--docker-image), 2 CPUs / 2 GB
+    span.text-body-secondary Runs each job's command — nothing of its own to drive
   else if caps.hw
     - const kinds = [['stlinks', 'ST-Link'], ['uarts', 'UART'], ['usbs', 'USB']]
     - const empty = kinds.every(([k]) => !(caps.hw[k] || []).length)
@@ -332,7 +332,7 @@ mixin resourceCard(r, groupsById, returnTo)
                 data-bs-target=`#rc-${r.id}-usb`
                 aria-controls=`rc-${r.id}-usb`
                 aria-selected="false"
-              ) Connected USB devices
+              ) USB devices
             
           .tab-content
             .tab-pane.fade.show.active(id=`rc-${r.id}-details` role="tabpanel" aria-labelledby=`rc-${r.id}-details-tab` tabindex="0" data-live=`rc-details-${r.id}`)
@@ -346,7 +346,7 @@ mixin resourceCard(r, groupsById, returnTo)
             .tab-pane.fade.thub-usb-pane(id=`rc-${r.id}-usb` role="tabpanel" aria-labelledby=`rc-${r.id}-usb-tab` tabindex="0")
               +usbScanPane(r)
 
-//- "Connected USB devices" (resource card tab): the Client's `lsusb`, run
+//- "USB devices" (resource card tab): the Client's `lsusb`, run
 //- only on Refresh (admins; public/js/usb-scan.js fetches and fills it in).
 mixin usbScanPane(r)
   - const offline = r.status === 'OUT_OF_SERVICE' || !r.last_heartbeat_at

package/views/resources/list.pug

@@ -67,6 +67,7 @@ block scripts
   script(src="/js/resource-card.js")
   script(src="/js/remove-resource.js")
   script(src="/js/client-config.js")
+  script(src="/js/tag-picker.js")
   script(src="/js/usb-scan.js")
   script(src="/js/usb-parse.js")
   script(src="/js/usb-import.js")