La CI della tua PR
Come Narsil Check segue i passi di GitHub Actions della pull request della sessione con la CLI gh, ogni 10 secondi mentre un run è in corso, e si ferma quando finisce.
Cosa fa
Quando la sessione ha una pull request aperta, la sezione Entorno mostra una chiusura CI sotto l’interruttore del Remote Control. Segue il run di GitHub Actions del commit più recente della pull request, passo per passo, così puoi guardare i controlli senza aprire il browser.
L’intestazione della chiusura dice a colpo d’occhio a che punto è la CI:
| Intestazione | Significato |
|---|---|
CI · 2/4 · Typecheck |
In corso: due passi su quattro fatti, Typecheck in esecuzione adesso. |
CI · pasó |
Superata. |
CI · falló |
Fallita. |
CI · esperando el CI del último push |
In attesa: il tuo branch ha un commit che nessun run ha ancora preso in carico. |
CI · sin ejecuciones |
Nessun run per questo branch. |
CI · sin leer |
Non letta: gh non ha potuto rispondere, e il motivo appare sotto. |
Aperta, elenca i passi con un segno nei colori di Narsil:
✓verde: fatto.✗rosso: fallito, annullato, scaduto, in attesa di un’azione o non avviato.◐giallo: in esecuzione.○grigio: in coda o in attesa.–grigio: saltato o neutro.
I passi di servizio di GitHub stesso (Set up job, Complete job, Post …) vengono lasciati fuori, perché non dicono niente sul progetto. Con più workflow, il nome di ogni run fa da intestazione ai suoi passi; con più job, ogni job appare con il proprio segno.
Mentre un run è in corso, la chiusura interroga di nuovo ogni 10 secondi, e smette di interrogare appena la CI finisce. La chiusura resta come l’hai lasciata: l’avvio della sessione non la reimposta, e il commento del codice dice che mantiene come l’hai lasciata tra le sessioni (la prima guida spiega cosa dicono i tipi al riguardo). Mentre è chiusa, non viene interrogato niente.
Come funziona dentro
Quale pull request, quale repository
La chiusura della CI non cerca da sola una pull request. Usa quella che l’app desktop ha associato alla sessione, letta nelle guide precedenti tramite $.mcp.call('ccd_pr', 'get_status', { session_id: 'self' }). parsePr in hooks/session.ts conserva, per una pull request aperta, il suo url, il suo repository (prRepo, proprietario e nome, come acme/shop) e il suo branch di testa (prHead).
La chiusura viene disegnata solo quando view.prUrl è impostato. Quindi esiste solo nell’app desktop, dove esiste ccd_pr; la tabella delle superfici del README dice lo stesso.
Interrogare gh
La parte pura vive in hooks/ci.ts: costruisce i comandi e legge il loro output. Il modulo degli hook li esegue in readCi, in hooks/register.tsx.
Prima, i run del branch:
export function runListArgv(repo: string, branch: string): string[] {
return [
'gh',
'run',
'list',
'--repo',
repo,
'--branch',
branch,
'--json',
RUN_FIELDS,
'--limit',
'20',
]
}
RUN_FIELDS è 'databaseId,headSha,workflowName,status,conclusion'. gh elenca prima i più recenti, quindi latestRuns prende il commit del primo run (headSha) come il più recente, tiene solo i run di quel commit, e ne tiene uno per nome di workflow. I run dei commit più vecchi non si mescolano mai con quello attuale.
Poi, per ognuno di quei run, i suoi job e i suoi passi:
export function runViewArgv(repo: string, id: number): string[] {
return ['gh', 'run', 'view', String(id), '--repo', repo, '--json', 'jobs']
}
jobsOf legge il nome, lo stato, la conclusione e i passi di ogni job, e scarta i passi di servizio con un’unica espressione regolare, NOISE = /^(Set up job|Complete job|Post .+)$/.
Gli stati della CI sono quelli di GitHub: uno status (queued, in_progress, completed) e, una volta completato, una conclusion. markOf trasforma quella coppia in un segno e un colore, e l’elenco delle conclusioni di fallimento (FAILED) è lo stesso ovunque: nel segno di un passo, nell’intestazione (ciLabel) e nel segno della chiusura stessa (ciMark).
$.process.run, come lo usa il codice
I tipi della 2.1.325 descrivono $.process.run(argv, init) come l’esecuzione di “a command on the host by its argument vector (no shell)” (un comando sull’host tramite il suo vettore di argomenti, senza shell), che risolve { exitCode, stdout, stderr } “once it exits, any exit code” (una volta terminato, con qualsiasi codice di uscita). Il timeout è di 30 secondi per impostazione predefinita e di dieci minuti al massimo; Narsil Check passa GH_MS, 30 secondi. Viene respinto quando il comando non può avviarsi o è ancora in esecuzione allo scadere del timeout. I tipi segnano anche l’intero sostantivo process come “CLI only” (solo CLI).
Ne seguono due cose, e il codice le gestisce entrambe:
- Un’uscita diversa da zero è una risposta, non un’eccezione.
readCicontrollalist.exitCode !== 0e tiene lo stderr dighcome errore, o “gh terminó con el código N” (“gh è terminato con il codice N”) quando lo stderr è vuoto. - Un
ghmancante è un’eccezione. La chiamata viene respinta, ilcatchattorno areadCitiene il messaggio, e la chiusura lo dice.
Dato che il vettore di argomenti non ha shell, i nomi del repository e del branch arrivano a gh come argomenti semplici: non c’è niente da mettere tra virgolette o da sottoporre a escape.
C’è un motivo per eseguire gh invece di chiamare l’API HTTP di GitHub dalla mod: gh porta l’accesso della persona stessa, così la mod non tiene mai un token di GitHub. Un commento in hooks/register.tsx dà un motivo correlato per eseguire git direttamente in “Actualizar rama”: “The mod runs git itself, so the app asks no permission.” (la mod esegue git da sola, così l’app non chiede nessun permesso).
Aspettare un push
Subito dopo git push, GitHub potrebbe non aver avviato un run per il nuovo commit, e l’elenco mostra ancora il run del commit precedente, magari già verde. Mostrare “superata” in quel momento sarebbe sbagliato.
Quindi, quando il branch su cui sei è il branch di testa della pull request, readCi esegue anche git rev-parse @{upstream}. Se il commit upstream non è il commit dei run elencati, un push più recente non ha ancora un run, e la vista viene segnata come isWaiting: l’intestazione dice “esperando el CI del último push” e il segno è giallo.
Ogni 10 secondi, e poi basta
L’interrogazione periodica è watchCi, un ciclo:
let ciWatch = 0
async function watchCi($: EngineInterface): Promise<void> {
const id = ++ciWatch
let waits = 0
for (;;) {
const view = await read($, session)
if (!view.prUrl || !(await read($, isCiOpen))) return
await update($, ci, (current) =>
current.status === 'ready' ? current : { ...current, status: 'loading' },
)
let next = await readCi($, view)
if (id !== ciWatch) return
// A push no workflow answers (a repository with no CI for it) stops waiting.
if (next.isWaiting && ++waits > CI_WAIT_POLLS) next = { ...next, isWaiting: false }
await update($, ci, () => next)
if (next.error || !(next.isWaiting || isGoing(next.runs))) return
await $.clock.sleep(CI_POLL_MS)
if (id !== ciWatch) return
}
}
È citato da narsil-check (GPL-3.0-or-later). Ogni riga è una regola:
- Nessuna pull request, o la chiusura chiusa: fermati. Non viene interrogato niente mentre non stai guardando.
- Tieni l’ultima risposta mentre ricarichi. Una vista che è già
readyresta com’è durante la lettura successiva, così i passi non sfarfallano. - Una sola osservazione alla volta. Ogni chiamata prende un nuovo
id. Un’osservazione più recente (dalla lettura successiva della sessione, da una pull request trovata in ritardo, o dall’apertura della chiusura) fa fermare quella vecchia al suo controllo successivo. - Un push a cui nessuno risponde chiude l’attesa.
CI_WAIT_POLLSvale 12, quindi dopo circa due minuti un repository senza workflow per quel push smette di aspettare. - Fermati su un errore, o quando niente è in esecuzione e niente è atteso.
isGoingè vero finché lo stato di qualche run non ècompleted. - Altrimenti aspetta
CI_POLL_MS, 10 secondi, con$.clock.sleep. I tipi lo descrivono come qualcosa che risolve “aftermsmilliseconds” (dopomsmillisecondi).
I tipi offrono anche $.clock.every(ms, fn), che chiama fn a ogni periodo finché non viene annullato. Il ciclo con sleep ha una proprietà adatta a questo caso: la lettura successiva inizia solo dopo che la precedente è finita, così le chiamate lente a gh non si sovrappongono mai, e il ciclo finisce da solo sulla condizione che ha appena letto.
L’osservazione viene avviata con void watchCi($) dopo una lettura completa della sessione, dopo una pull request trovata in ritardo, e quando apri la chiusura. Non viene mai attesa da un hook.
Quando gh manca o non ha l’accesso
Entrambi i casi finiscono allo stesso modo. La vista riceve un error, l’intestazione dice CI · sin leer, il segno è ○ grigio, e la chiusura aperta mostra in rosso “No pude leer el CI con gh: …” (“non ho potuto leggere la CI con gh: …”) seguito dal motivo: il messaggio del motore quando gh non ha potuto avviarsi, o lo stderr di gh stesso quando è stato eseguito e ha rifiutato, come fa quando non ha l’accesso. Il ciclo si ferma sull’errore; la lettura successiva della sessione o l’apertura della chiusura riprova.
Sui permessi, il README dice solo che gh deve essere installato e con l’accesso effettuato (“con gh instalado y con sesión iniciada”). Né il README né il codice elencano scope per leggere la CI. La nota del README sul permesso workflow riguarda il push di modifiche a .github/workflows via HTTPS, una funzionalità diversa.
Come è stata chiesta all’IA
La richiesta originale per la chiusura della CI non è stata registrata. Nessuno dei log di task pubblici di narsil-check (odd/tasks/*.md) la copre.
Ricostruzione dalla cronologia dei commit
Da git log -- hooks/ci.ts, con i commit correlati a hooks/register.tsx e hooks/session.ts:
7d91264(2026-11-07) “feat: add an Auto-fix switch to Entorno for the session’s open pull request” (aggiunge a Entorno un interruttore Auto-fix per la pull request aperta della sessione). La sessione viene a sapere per la prima volta della sua pull request qui, tramiteccd_pr.8af1f0e(2026-11-07) “feat: show the PR’s CI step by step in a collapsible fold under Remote Control” (mostra la CI della PR passo per passo in una chiusura comprimibile sotto il Remote Control). L’interohooks/ci.tsarriva in questo solo commit. Il suo messaggio: “Reads the newest commit’s GitHub Actions runs on the PR’s head branch with gh, lists each job’s steps without GitHub’s bookkeeping ones, and polls every 10 seconds while a run goes or a push waits for one. The fold keeps its open state across sessions.” (legge con gh i run di GitHub Actions del commit più recente sul branch di testa della PR, elenca i passi di ogni job senza quelli di servizio di GitHub, e interroga ogni 10 secondi mentre un run è in corso o un push ne aspetta uno. La chiusura mantiene il suo stato di apertura tra le sessioni). Cambia anche lashapedell’atom della sessione per i nuovi campi della pull request.90c40f9(2026-11-07) “fix: read the session’s pull request again when the app binds it after the turn ends” (rilegge la pull request della sessione quando l’app la associa dopo la fine del turno). Senza di esso, una pull request aperta in un turno non mostrava nessuna CI fino alla lettura successiva.f091e0b(2026-11-07) “fix: retry only the pull request read and stop the retries when the session ends” (ripete solo la lettura della pull request e ferma i tentativi quando la sessione finisce).
Lo schema è diverso da quello delle guide precedenti: la chiusura della CI è arrivata completa in un solo commit, sopra l’infrastruttura della pull request del giorno prima, e le correzioni che sono seguite riguardavano il trovare la pull request, non la CI in sé.
Un prompt che puoi usare
Il prompt seguente è stato scritto per questa guida come suggerimento. Non è il prompt dell’autore.
Nella mia mod di Claude Code
my-panel, aggiungi una chiusura “CI” per la pull request aperta della sessione, di cui ho già il repository (acme/shop) e il branch di testa. Eseguigh run list --repo <repo> --branch <branch> --json databaseId,headSha,workflowName,status,conclusion --limit 20con$.process.run(timeout di 30 s), tieni solo i run dell’headShadella prima riga, uno per workflow, poigh run view <id> --repo <repo> --json jobsper ciascuno. Nascondi i passiSet up job,Complete jobePost …. Mostra ogni passo con ✓ verde, ✗ rosso, ◐ giallo per in corso, ○ grigio per in coda e – grigio per saltato. Tratta un’uscita diversa da zero come un errore con lo stderr di gh, e anche un rifiuto (gh mancante) come un errore; mostralo nella chiusura. Interroga in un ciclo con$.clock.sleep(10_000)solo mentre la chiusura è aperta e un run non è completato, e altrimenti fermati; dai a ogni osservazione un id così una più recente la sostituisce. Testa i parser come funzioni pure con JSON di gh sintetico, e il ciclo conmock.clock.
Il codice minimo
Questa è una versione ridotta dell’idea, scritta per questa guida e verificata con i tipi di Claude Code 2.1.325. È adattata da hooks/ci.ts e hooks/register.tsx in narsil-check (GPL-3.0-or-later). Segue un solo workflow e lascia fuori l’attesa di un push.
Il tipo dello stato, in types/index.d.ts:
export type Step = { name: string; status: string; conclusion: string }
export type Ci = { steps: Step[]; isGoing: boolean; error?: string }
declare module 'claude-code' {
interface PluginState {
'my-panel': { ci: Ci }
}
}
La parte del modulo degli hook, hooks/register.tsx:
import { atom, read, update } from 'claude-code'
import type { EngineInterface } from 'claude-code'
import type { Ci, Step } from '../types'
const ci = atom({ plugin: 'my-panel', key: 'ci' } as const, { steps: [], isGoing: false } as Ci)
const NOISE = /^(Set up job|Complete job|Post .+)$/
async function gh($: EngineInterface, argv: string[]): Promise<string> {
const ran = await $.process.run(['gh', ...argv], { timeoutMs: 30_000 })
if (ran.exitCode !== 0) throw new Error(ran.stderr.trim() || `gh ended with code ${ran.exitCode}`)
return ran.stdout
}
async function readCi($: EngineInterface, repo: string, branch: string): Promise<Ci> {
try {
const fields = 'databaseId,headSha,status,conclusion'
const runs = JSON.parse(
await gh($, [
'run',
'list',
'--repo',
repo,
'--branch',
branch,
'--json',
fields,
'--limit',
'1',
]),
)
if (!Array.isArray(runs) || runs.length === 0) return { steps: [], isGoing: false }
const run = runs[0] as { databaseId: number; status: string }
const viewed = JSON.parse(
await gh($, ['run', 'view', String(run.databaseId), '--repo', repo, '--json', 'jobs']),
)
const steps: Step[] = (viewed.jobs ?? [])
.flatMap((job: { steps?: Step[] }) => job.steps ?? [])
.filter((step: Step) => !NOISE.test(step.name))
return { steps, isGoing: run.status !== 'completed' }
} catch (err) {
return { steps: [], isGoing: false, error: err instanceof Error ? err.message : String(err) }
}
}
let watch = 0
export async function watchCi($: EngineInterface, repo: string, branch: string): Promise<void> {
const id = ++watch
for (;;) {
const next = await readCi($, repo, branch)
if (id !== watch) return
await update($, ci, () => next)
if (next.error || !next.isGoing) return
await $.clock.sleep(10_000)
if (id !== watch) return
}
}
export const MARK = (s: Step) =>
s.status !== 'completed'
? s.status === 'in_progress'
? { mark: '◐', color: '#F5B400' }
: { mark: '○', color: '#8A90A6' }
: s.conclusion === 'success'
? { mark: '✓', color: '#22B573' }
: s.conclusion === 'skipped'
? { mark: '–', color: '#8A90A6' }
: { mark: '✗', color: '#F0435A' }
Avvialo con void watchCi($, 'acme/shop', 'feat/login').catch(() => undefined) da un hook, senza mai attenderlo, e disegna i passi nell’hook ui.render del pannello con read($, ci), un Text per passo nel suo colore MARK, e l’errore in rosso quando c’è. La versione ridotta di MARK tratta come fallimento qualsiasi conclusione completata diversa da success o skipped; markOf di Narsil Check nomina quelle di fallimento (FAILED) e mostra anche neutral in grigio.
Errori comuni e come testarlo
Questi vengono dal codice e dai commit di Narsil Check:
- Mescolare i commit.
gh run listrestituisce run di più commit. Tieni solo i run del commit più recente, uno per workflow, come falatestRuns. - Annunciare un successo subito dopo un push. L’elenco può ancora mostrare il run verde del commit precedente. Confronta il commit upstream con l’
headShadei run, e smetti di aspettare dopo un limite (CI_WAIT_POLLS), altrimenti un repository senza CI per quel push aspetta per sempre. - Trattare il codice di uscita come un’eccezione.
$.process.runrisolve con qualsiasi codice di uscita. ControllaexitCode, e tieni lo stderr come motivo. - Interrogare per sempre. Fermati quando niente è in esecuzione, quando la chiusura è chiusa e su un errore. Il ciclo di Narsil Check ritorna in ognuno di questi casi.
- Due osservazioni insieme. Ogni lettura della sessione può avviare un’osservazione. Dai a ciascuna un id e lascia vincere la più recente.
- Attendere l’osservazione in un hook. Il
$.clock.sleepdi un hook consuma il budget di quell’hook, come dicono i tipi; avvia l’osservazione convoid. - Mostrare i passi di servizio di GitHub. I passi
Set up jobePost …nascondono quelli che contano.
Per testare, tests/ci.test.tsx controlla le funzioni pure con JSON di gh sintetico: “the newest commit’s runs, one per workflow, newest first” (i run del commit più recente, uno per workflow, prima i più recenti), “a run’s steps leave out GitHub’s own bookkeeping” (i passi di un run lasciano fuori quelli di servizio di GitHub), “each step shows as done, failed, going, waiting or skipped” (ogni passo appare come fatto, fallito, in corso, in attesa o saltato) e “the fold’s line says how far the CI is” (la riga della chiusura dice a che punto è la CI). tests/session.test.tsx testa la chiusura nel pannello: risponde a gh tramite un hook on('process.run', ...) con chiave sul vettore di argomenti unito, e fa avanzare il tempo con mock.clock e clock.advance(10_000) in “the CI fold, under Remote Control, shows the PR’s run step by step and follows it until it ends” (la chiusura della CI, sotto il Remote Control, mostra il run della PR passo per passo e lo segue finché non finisce). “a CI gh cannot read says why in its fold” (una CI che gh non riesce a leggere dice perché nella sua chiusura) risponde a ogni comando con codice di uscita 1 e si aspetta CI · sin leer e la riga rossa.
Per andare oltre
- L’interruttore Auto-fix subito sotto la chiusura (guide precedenti) attiva il monitor della CI dell’app desktop stessa per la stessa pull request, che risveglia la sessione quando la CI fallisce; la chiusura mostra la CI, l’interruttore agisce su di essa.
ciLabelconta i passi fatti in tutti i job e i run, e nomina il passo in esecuzione adesso, quindi spesso basta la sola intestazione mentre la chiusura resta chiusa.- La chiusura legge i campi JSON di
gh, non il suo output testuale, così un cambiamento nella formulazione dighnon la rompe.
Per andare oltre: come lo fa la mod vera
Questi file fanno parte delle mod originali, pubblicate con licenza GPL v3. Il codice citato in questa pagina viene da lì e mantiene quella licenza.
Questa guida ti è stata utile?
Tutte le guide sono gratuite. Se questa ti ha fatto risparmiare tempo, puoi offrirmi un caffè.
Offrimi un caffè