fix(infra): add setup-knuckle-upstream workflow and document GH_TOKEN requirement (closes #104)

Justfile

@@ -130,6 +130,13 @@ setup-ghost-ssh-banner:
         -n {{ argo_ns }} \
         --wait --log
 
+# One-time: add upstream remote to ghost's ~/src/knuckle repo (#104).
+# Fixes `fatal: 'upstream' does not appear to be a git repository` in qa-test-pr.sh.
+setup-knuckle-upstream:
+    argo submit --from workflowtemplate/setup-knuckle-upstream \
+        -n {{ argo_ns }} \
+        --wait --log
+
 # One-time fixture setup for titan VMs: installs Firefox Flatpak and sets default browser.
 # Run this before smoke tests that cover xdg-settings (#107).
 setup-titan-fixtures:

RUNBOOK.md

@@ -96,6 +96,8 @@ Golden disks can be patched by workflow after key rotation; titan disk key refre
 | VM stuck `Terminating` | KubeVirt controller race with launcher cleanup | Delete the `virt-launcher-*` pod and let reconciliation finish |
 | `run-gnome-tests` pod fails at startup | Workflow template structure error, often misplaced `volumes:` | Fix the template in git and let ArgoCD reconcile it |
 | WorkflowTemplate change appears ignored | Workflow was submitted before the new template was reconciled | Verify ArgoCD revision, wait or sync, then submit a new workflow |
+| `qa-test-pr.sh`: `fatal: 'upstream' does not appear to be a git repository` | ghost's `~/src/knuckle` is missing the `upstream` remote | `just setup-knuckle-upstream` (one-time fix) |
+| `qa-test-pr.sh`: `gh auth login` prompt / unauthenticated | `gh` CLI on ghost has no token | Pass `GH_TOKEN=$(gh auth token)` from the calling machine, or run `gh auth login` on ghost |
 
 ## Historical notes
 

WORKFLOWS.md

@@ -99,6 +99,19 @@ selinux=0, sudoers) on an existing golden disk without rebuilding it.
 |---|---|---|
 | `image-tag` | `latest` | Disk dir under `/var/tmp/bluefin-golden/`. |
 
+### `setup-knuckle-upstream`
+
+One-shot: adds the missing `upstream` remote pointing at
+`projectbluefin/knuckle` to ghost's `~/src/knuckle` repo. Required for
+`qa-test-pr.sh` which calls `git fetch upstream pull/${PR}/head:...`.
+Idempotent — safe to re-run.
+
+No parameters. Run once:
+
+```
+just setup-knuckle-upstream
+```
+
 ---
 
 ## Supporting templates (called via `templateRef`)

argo/workflow-templates/setup-knuckle-upstream.yaml

@@ -0,0 +1,83 @@
+apiVersion: argoproj.io/v1alpha1
+kind: WorkflowTemplate
+metadata:
+  name: setup-knuckle-upstream
+  namespace: argo
+  annotations:
+    description: |
+      One-shot: adds the missing `upstream` remote to ghost's ~/src/knuckle
+      repo and verifies gh CLI auth via GH_TOKEN. Fixes #104.
+      Usage: argo submit --from workflowtemplate/setup-knuckle-upstream -n argo --wait --log
+spec:
+  serviceAccountName: argo
+  entrypoint: fix-knuckle-infra
+  ttlStrategy:
+    secondsAfterCompletion: 3600
+
+  templates:
+    - name: fix-knuckle-infra
+      nodeSelector:
+        kubernetes.io/hostname: ghost
+      activeDeadlineSeconds: 120
+      podSpecPatch: |
+        hostPID: true
+        securityContext:
+          runAsUser: 0
+      volumes:
+        - name: jorge-home
+          hostPath:
+            path: /var/home/jorge
+            type: Directory
+      script:
+        image: quay.io/fedora/fedora:latest
+        imagePullPolicy: Always
+        resources:
+          requests:
+            cpu: 50m
+            memory: 64Mi
+          limits:
+            cpu: 200m
+            memory: 128Mi
+        securityContext:
+          privileged: true
+        volumeMounts:
+          - name: jorge-home
+            mountPath: /host/home/jorge
+        command: [bash]
+        source: |
+          set -euo pipefail
+
+          KNUCKLE_DIR="/host/home/jorge/src/knuckle"
+
+          if [[ ! -d "${KNUCKLE_DIR}/.git" ]]; then
+            echo "ERROR: ${KNUCKLE_DIR} is not a git repo" >&2
+            exit 1
+          fi
+
+          echo "=== Current remotes ===" >&2
+          git -C "${KNUCKLE_DIR}" remote -v >&2
+
+          UPSTREAM_URL="https://github.com/projectbluefin/knuckle.git"
+
+          if git -C "${KNUCKLE_DIR}" remote get-url upstream >/dev/null 2>&1; then
+            CURRENT=$(git -C "${KNUCKLE_DIR}" remote get-url upstream)
+            if [[ "${CURRENT}" == "${UPSTREAM_URL}" ]]; then
+              echo "upstream remote already set to ${UPSTREAM_URL}" >&2
+            else
+              echo "Updating upstream remote from ${CURRENT} to ${UPSTREAM_URL}" >&2
+              git -C "${KNUCKLE_DIR}" remote set-url upstream "${UPSTREAM_URL}"
+            fi
+          else
+            echo "Adding upstream remote: ${UPSTREAM_URL}" >&2
+            git -C "${KNUCKLE_DIR}" remote add upstream "${UPSTREAM_URL}"
+          fi
+
+          echo "=== Verifying upstream fetch ===" >&2
+          git -C "${KNUCKLE_DIR}" fetch upstream --dry-run 2>&1 | head -5 >&2 || {
+            echo "WARNING: upstream fetch --dry-run failed (network issue?)" >&2
+          }
+
+          echo "=== Updated remotes ===" >&2
+          git -C "${KNUCKLE_DIR}" remote -v >&2
+
+          echo "setup-complete"

docs/agent-cheatsheet.md

@@ -32,6 +32,7 @@
 | List workflows / VMs | `just list-workflows` · `just list-vms` |
 | ArgoCD status / force sync | `just argocd-status` · `just argocd-sync` |
 | Lint Argo YAML | `just lint` |
+| Fix missing upstream remote on ghost knuckle repo | `just setup-knuckle-upstream` (one-time) |
 | Bootstrap repo-owner workstation access | §9 |
 
 Rule: **if a `just` recipe exists, use it.** Otherwise use Kubernetes MCP / Argo MCP recipes from this guide; do not fall back to workstation `kubectl`/`argo`.
@@ -55,6 +56,8 @@ Run `just logs` first. Then match a row:
 | `run-gnome-tests` pod errors immediately | Fix the WorkflowTemplate in git; `volumes:` must live at template scope, not under `container:` |
 | Workflow stuck `Pending` | Run §3 |
 | Template change did not take effect | Run §4 |
+| `qa-test-pr.sh`: `fatal: 'upstream' does not appear to be a git repository` | `just setup-knuckle-upstream` (one-time fix) |
+| `qa-test-pr.sh`: `gh auth login` prompt | Pass `GH_TOKEN=$(gh auth token)` from the calling machine when invoking the script |
 
 If no row matches: