Esegui i tuoi test da CI/CD

La schermata CI/CD di Studio genera il file della pipeline per GitHub Actions o GitLab CI. Questa guida illustra cosa esegue il file, i tre ambienti in cui può essere eseguito il job, i segreti, il file XML JUnit e le evidenze che produce, e gli errori che si possono verificare su una macchina CI.

Il file della pipeline

Nella schermata CI/CD, scegli GitHub Actions o GitLab CI, i browser, i controlli e dove eseguire il job, poi genera il file. Studio convalida prima il file localmente e consente di eseguirne il commit e il push dalla stessa schermata. Da un terminale, nexus init --ci github o nexus init --ci gitlab genera lo stesso file.

Con più browser, GitHub esegue un job per browser, con fail-fast: false, e ciascuno aggiunge --project=<browser>. I controlli che scegli aggiungono --visual, --a11y, --chaos=, --loop= o --no-retry.

Codici di uscita e XML JUnit

nexus ci esegue i test che specifichi (TC1,TC2) oppure --all, e termina con codice 0 se i test vengono superati, 1 in caso di errore e 2 se non è stato eseguito nulla o il comando era errato. Scrive il file XML JUnit in evidence/ci/junit.xml; --junit=<path> lo scrive in un'altra posizione.

Dove viene eseguito il job: tre opzioni

Ogni opzione richiede una macchina con un'attivazione: il motore non esegue suite su una macchina che ne è priva, e ogni macchina attivata viene conteggiata nel tuo piano (piani e macchine). Un runner ospitato nel cloud, runs-on: ubuntu-latest, avvia una nuova macchina virtuale per ogni job, quindi non conserva mai l'attivazione; usa un runner persistente su una tua macchina.

Opzione A: un runner autogestito sulla macchina di Studio

1. Sul PC o mini PC con Windows 11 su cui Nexus Studio è installato e attivato, registra un runner: su GitHub, nelle Impostazioni del repository, Azioni, Runner, Nuovo runner autogestito; su GitLab, in Impostazioni, CI/CD, Runner.
2. Nella schermata CI/CD, scegli La mia macchina. Il file riporterà quindi runs-on: [self-hosted] su GitHub o tags: [self-hosted] su GitLab.
3. Esegui il runner con l'utente Windows che ha attivato Studio. Il motore legge l'attivazione dal profilo di quell'utente, in .sentinel-studio\license.json, quindi un servizio runner eseguito con un altro account non trova alcuna attivazione.

Il processo usa l'attivazione di questa macchina: una sola attivazione per macchina, già conteggiata nel tuo piano, e nessuna chiave nella pipeline. Usa un runner autogestito solo con un repository privato, come avverte Studio: in un repository pubblico, chiunque apra una richiesta di integrazione può eseguire codice sulla tua macchina.

Opzione B: un runner su un VPS, in un contenitore

Un VPS con Ubuntu 24.04 LTS x86_64, Docker Engine e Compose v2, accessibile tramite autenticazione con chiave SSH. Conta come una macchina del tuo piano.

1. Nella schermata CI/CD, scegli La mia macchina + Docker. Oltre al file della pipeline, Studio scrive docker-compose.sentinel-runner.yml, Dockerfile.runner e i due script di avvio del runner nell'area di lavoro. Dockerfile.runner parte da mcr.microsoft.com/playwright:v1.62.1-noble.
2. La schermata mostra i comandi da incollare in una sessione SSH sul VPS, non nel terminale di Studio. Per GitHub recupera un token di registrazione, valido per 1 ora, e imposta REPO_URL, RUNNER_TOKEN e RUNNER_NAME; per GitLab, GITLAB_URL e GITLAB_RUNNER_TOKEN. Poi:

docker compose -f docker-compose.sentinel-runner.yml up -d --build sentinel-runner
docker compose -f docker-compose.sentinel-runner.yml up -d sentinel-runner-gitlab

La prima riga è per GitHub, la seconda per GitLab. All'interno di un contenitore Linux la licenza identifica la macchina tramite /etc/machine-id: monta quello dell'host in sola lettura, /etc/machine-id:/etc/machine-id:ro, e conserva su un volume la cartella .sentinel-studio della directory home del runner, così l'attivazione viene mantenuta anche dopo una ricompilazione. Esegui l'attivazione una sola volta, manualmente, con nexus license activate e la tua chiave, mai dal file della pipeline.

Attualmente l'immagine del runner viene creata sul VPS a partire da Dockerfile.runner. Il repository non ha ancora un registro dei contenitori: un'immagine pubblicata su GitHub Container Registry, quella eseguita dall'ambiente di esecuzione VPS di Studio, sarà disponibile con la prossima versione.

Opzione C: il processo CI avvia un'esecuzione su un host tramite SSH

Il job resta leggero, su qualsiasi runner, e le suite vengono eseguite su un host di tua proprietà, con l'area di lavoro e il motore in un percorso su quell'host, come previsto dall'ambiente di esecuzione SSH di Studio. La schermata CI/CD non genera questo job; queste sono le opzioni usate dall'ambiente di esecuzione SSH di Studio:

ssh -o BatchMode=yes -o StrictHostKeyChecking=yes -o ConnectTimeout=8 <user>@<host> "cd <path> && node bin/nexus.js ci --all"
scp -r -o BatchMode=yes -o StrictHostKeyChecking=yes <user>@<host>:<path>/evidence ./evidence

• Solo autenticazione tramite chiave. BatchMode=yes non richiede mai una password. Scrivi la chiave privata da un segreto CI in un file leggibile solo dal job ed eliminalo al termine del job.
• StrictHostKeyChecking=yes. La chiave dell'host deve essere già presente nel file known_hosts del runner: conserva la riga della chiave pubblica dell'host in una variabile CI e scrivila nel file prima del primo comando ssh. Non impostare mai questa opzione su no.
• Il codice di uscita viene restituito. ssh termina con il codice del comando remoto, quindi il passaggio fallisce se la suite fallisce, e scp recupera le evidenze, incluso il file XML JUnit, per il passaggio dedicato agli artefatti.
• L'host verifica la propria licenza e conta come una macchina del tuo piano.

Segreti

• Conserva token, URL dei webhook e chiavi private SSH come segreti CI: su GitHub in Impostazioni, Segreti e variabili, Actions, oppure con gh secret set <KEY>; su GitLab come variabili mascherate in Impostazioni, CI/CD, Variabili. Mai nel repository, nel file della pipeline o in un registro.
• Il flusso di lavoro GitHub generato legge solo le chiavi di integrazione, da secrets.<KEY>, e solo nei passaggi Nexus: TELEGRAM_*, SLACK_ENABLED, SLACK_WEBHOOK_URL, JIRA_* e le opzioni di attivazione delle notifiche. La schermata CI/CD elenca un comando gh secret set per ciascuna; gh richiede il valore e non viene visualizzato nulla.
• La chiave di licenza non va inserita nella CI. Attiva un runner persistente una sola volta, manualmente: la chiave viene inviata una volta e non viene conservata. Se il tuo processo richiede comunque la chiave nel sistema CI, conservala solo come segreto mascherato; nessuna parte della pipeline generata la legge.
• Non stampare mai un segreto in un passaggio. Il motore rimuove i segreti dal testo che archivia come evidenza, ad esempio dai messaggi di errore JUnit e dai registri; non li rimuove dall'output della console del job e il servizio CI maschera solo i valori memorizzati come segreti.

XML JUnit ed evidenze come artefatti

• GitHub carica evidence/ come nexus-evidence, un nexus-evidence-<browser> per browser quando si usa una matrice, sia che l'esecuzione riesca sia che fallisca. Il file XML JUnit si trova al suo interno, in evidence/ci/junit.xml.
• GitLab conserva evidence/ e pubblica evidence/ci/junit.xml come rapporto JUnit, così i test non riusciti vengono mostrati nella richiesta di unione.
• Da Studio, la schermata CI/CD può avviare l'esecuzione di un flusso di lavoro GitHub e scaricarne le evidenze in evidence/ci-remote/run-<id> nell'area di lavoro.
• Dove risiede la copia. Un artefatto è una copia delle evidenze, incluse schermate e registri, nello spazio di archiviazione del tuo servizio CI; se il servizio è in hosting, si tratta di hardware di terzi. Imposta il periodo di conservazione degli artefatti consentito dalle tue policy, oppure conserva le evidenze sul tuo runner e carica solo evidence/ci/junit.xml.

Risoluzione dei problemi

SEAT_LIMIT su un runner ospitato nel cloud o effimero

Ogni nuova macchina virtuale è una nuova macchina ai fini della licenza, quindi un runner effimero richiederebbe un'attivazione per ogni job. Quando tutte le macchine del tuo piano sono attive, l'attivazione viene rifiutata con SEAT_LIMIT: “Tutte le macchine del tuo piano sono in uso. Disattivane una nel tuo account.” Usa un runner persistente su infrastruttura propria (opzione A o B) e disattiva le macchine che non usi più nella sezione Licenza & macchine del tuo account (altre informazioni su SEAT_LIMIT).

Il runner è rimasto offline per giorni

La licenza di una macchina deve essere convalidata almeno ogni 7 giorni. Trascorso questo periodo, sono concessi altri 4 giorni con un avviso, poi si passa alla modalità di sola lettura: le suite non vengono eseguite finché una verifica non va a buon fine, mentre le evidenze restano consultabili. Quando il runner torna online, nexus license renew ripete la verifica (lavorare offline).

“no /etc/machine-id” in un contenitore

Il contenitore non dispone di un ID macchina che la licenza possa leggere. Monta quello dell'host: -v /etc/machine-id:/etc/machine-id:ro, oppure inserisci la stessa riga sotto volumes: nel file compose.

Il processo termina con il codice 2

Non è stato eseguito nulla: nessun test corrispondeva agli ID, oppure il comando era errato. Controlla gli ID passati a nexus ci, in tc_ids su GitHub o TC_IDS su GitLab.

Verifica della chiave dell'host non riuscita

StrictHostKeyChecking=yes ha rifiutato un host non presente in known_hosts, o la cui chiave è cambiata. Aggiungi la chiave dell'host da una fonte attendibile, dopo averne verificato l'impronta sull'host stesso. Non disattivare la verifica.