Artifact e log: interfaccia e API

Ogni run lascia dietro di sé due tipi di residuo, che conviene non confondere. I log vengono prodotti automaticamente da ogni step e raccontano che cosa è successo. Gli artifact esistono solo se il workflow ha deciso di crearli, tipicamente con actions/upload-artifact, e contengono i file che vuoi rileggere dopo la fine del run: binari compilati, report di test, screenshot, dump. Hanno pagine diverse nell’interfaccia, endpoint diversi e regole di cancellazione solo in parte sovrapponibili. Il dominio Consume and troubleshoot workflows ti chiede di sapere dove stanno entrambi e come prenderli senza passare dal browser.

Dove stanno nell’interfaccia

Il punto di partenza è la tab Actions del repository. La colonna di sinistra elenca i workflow; scegliendone uno vedi i suoi run, e cliccando un run arrivi alla pagina di riepilogo. Gli artifact prodotti da quel run compaiono lì, in una sezione Artifacts: il nome è un link che avvia il download di uno zip, e accanto c’è l’icona del cestino per eliminarlo. Per scaricare serve accesso in lettura al repository, per cancellare serve accesso in scrittura.

I log stanno un livello più in basso, dentro il singolo job. Aprendo un job vedi l’output step per step; dall’icona a forma di ingranaggio scegli Download log archive e ottieni un archivio con i log testuali, fra cui un file system.txt per ogni job. Quel file è prezioso in diagnostica: per le condizioni if di job riporta tre righe, Evaluating con l’espressione scritta nel workflow, Expanded con i valori dei context sostituiti a runtime e Result con l’esito booleano. Attenzione al limite, perché è materiale tipico da domanda: quelle righe esistono solo per le condizioni a livello di job. Per capire perché uno step è stato saltato devi abilitare il debug logging.

Scaricare dalla riga di comando

Il comando di riferimento è gh run download. Passandogli l’identificativo del run scarica tutti gli artifact prodotti; con il flag -n ne scarichi uno solo, e ripetendo il flag ne scegli più di uno. Se ometti l’identificativo del run e indichi solo i nomi, la CLI cerca quegli artifact fra i run del repository, il che è comodo quando vuoi semplicemente l’ultimo build disponibile senza andare a caccia del numero.

Il comportamento di estrazione sorprende spesso: se chiedi più artifact, ciascuno finisce in una cartella che porta il suo nome; se ne chiedi uno solo, il contenuto viene estratto direttamente nella cartella corrente. Uno script che si aspetta sempre la sottocartella si rompe nel momento in cui il run produce un artifact solo.

Le REST API

Le API servono quando il download deve stare dentro un altro sistema, per esempio una pipeline di rilascio esterna. Gli endpoint di lettura sono GET /repos/OWNER/REPO/actions/artifacts per l’intero repository, con filtro per nome e paginazione, e GET /repos/OWNER/REPO/actions/runs/RUN_ID/artifacts per il singolo run; GET /repos/OWNER/REPO/actions/artifacts/ARTIFACT_ID restituisce i metadati di uno solo, incluso il campo expires_at.

Il download vero e proprio passa da GET /repos/OWNER/REPO/actions/artifacts/ARTIFACT_ID/zip, dove zip è il formato di archivio accettato. Questa chiamata non restituisce i byte: risponde con un redirect e mette nell’header Location un URL firmato di durata molto breve. In pratica devi seguire il redirect subito, quindi con curl ricordati --location e non riusare quell’URL più tardi. Lo stesso schema vale per i log completi del run, con GET /repos/OWNER/REPO/actions/runs/RUN_ID/logs.

Sul lato distruttivo hai DELETE /repos/OWNER/REPO/actions/artifacts/ARTIFACT_ID per il singolo artifact, DELETE /repos/OWNER/REPO/actions/runs/RUN_ID/logs per i soli log di un run e DELETE /repos/OWNER/REPO/actions/runs/RUN_ID per il run intero. Le cancellazioni rispondono con uno status di successo senza corpo e richiedono un token con permessi di scrittura. Dall’interfaccia il run si elimina dal menu a tre puntini accanto al run, voce Delete workflow run e conferma esplicita; si possono rimuovere solo run conclusi o comunque non recentissimi.

Retention e pulizia dello storage

La retention si imposta in Settings, sezione Actions, pagina General, campo Artifact and log retention. Lo stesso controllo esiste a livello di organizzazione e di enterprise, e il livello superiore fissa il tetto per quelli sotto. I repository pubblici hanno un tetto più basso di quelli privati e interni. Due dettagli che l’esame ama: abbassare il valore vale solo per artifact e log generati da lì in avanti, quelli già esistenti mantengono la scadenza con cui sono nati; e la chiave retention-days dell’action di upload può solo accorciare, mai superare il limite ereditato.

- uses: actions/upload-artifact@v4
  with:
    name: test-report
    path: reports/
    retention-days: 5

Restano due confusioni classiche da evitare. La prima: artifact e cache non sono la stessa cosa. La cache serve a materiale rigenerabile come le dipendenze, ha una pagina e API sue, e non si gestisce dalla sezione Artifacts. La seconda: dalla major 4 gli artifact sono immutabili, quindi non puoi caricarne un altro con lo stesso nome nello stesso run per aggiornarlo, devi cambiare nome. In compenso l’upload espone un digest SHA256 e il download lo verifica, segnalando l’anomalia se il contenuto non corrisponde. Infine, cancellare un run cancella anche i suoi artifact: se stai facendo pulizia per recuperare spazio, tieni conto che stai buttando via anche la cronologia diagnostica di quel run.