Documentazione / Ricette / Ricette
Dall'errore al ticket lavorato da un agente
Un errore del browser diventa un ticket, e un agente sulla tua macchina propone la correzione da approvare.
Un errore della tua app web diventa un ticket con un clic. Un agente, che gira su una tua macchina Linux, prende quel ticket, scrive un piano e la correzione, e si ferma a ogni passaggio che chiede una decisione: approvi tu il piano e il lavoro.
Prima di cominciare ti servono:
- il codice dell'app in un repository GitHub;
- l'accesso al server dell'installazione, per collegarla a GitHub al passo 6;
- una macchina Linux per l'agente, con Codex installato e con l'accesso fatto e, se vuoi che lavori Claude, Claude Code installato e con l'accesso fatto. Sono programmi di OpenAI e di Anthropic, ognuno con il suo abbonamento: installali seguendo le loro istruzioni. Installa Codex con
npmdel tuo utente (per esempio quello dimise), non consudo npm -g.
1. Crea il progetto e la chiave
- In CloseYourIt crea un progetto per l'app, per esempio
web. - Nelle impostazioni del progetto crea un token di ingest.
- Copia la
publicKeye l'id del progetto. LapublicKeynon è segreta: è fatta per stare nel codice del browser. Iltokensegreto (cyi_…) non va mai nel browser.
2. Installa l'SDK
npm install @bussolabs/closeyourit-js
3. Configuralo
Chiama init una volta, il prima possibile nella pagina:
import * as CloseYourIt from "@bussolabs/closeyourit-js"
CloseYourIt.init({
endpointUrl: "https://bugs.example.com",
publicKey: "<chiave pubblica del token>",
projectId: "<id del progetto>",
environment: "production",
release: "[email protected]",
})
Da qui le eccezioni non gestite e le Promise rifiutate arrivano a CloseYourIt da sole, con i clic, la navigazione e le richieste che le hanno precedute.
4. Guarda l'errore
Per provare, lancia un errore in una pagina dell'app, per esempio da un pulsante:
throw new Error("Checkout total is NaN")
Apri Errori: l'errore è lì, in una riga. Aprilo per leggere le righe di codice da cui è passato e cosa è successo prima.
5. Trasforma l'errore in ticket
- Nella pagina dell'errore premi Promuovi a ticket.
- Guarda l'anteprima: progetto, titolo, il punto del codice, quante volte è successo.
- Premi Crea il ticket.
Nasce un ticket di tipo Bug, collegato all'errore. Dal terminale lo stesso passo è cyi errors promote <id> --project web.
6. Collega l'installazione a GitHub
L'agente lavora sul codice del repository e consegna la correzione come pull request. L'installazione arriva a GitHub con una GitHub App sua, creata una volta. Se la scheda GitHub del progetto mostra già i tuoi repository, salta al punto 4.
- Su GitHub apri Settings → Developer settings → GitHub Apps → New GitHub App e compila:
- Callback URL:
https://bugs.example.com/member/integrations/github/callback, e spunta Request user authorization (OAuth) during installation; - Webhook URL:
https://bugs.example.com/github/webhook, con un segreto che generi tu; - permessi sul repository: Contents lettura e scrittura, Pull requests lettura e scrittura, Actions lettura, Environments e Secrets lettura e scrittura, Metadata lettura;
- eventi: Push, Create, Release, Pull request.
- Callback URL:
- Crea la App, poi genera una chiave privata e un client secret.
- Sul server aggiungi queste righe a
/opt/closeyourit/.env, poi lanciacloseyourit restart:GH_APP_ID=<l'ID della App> GH_APP_SLUG=<il nome nell'indirizzo della App> GH_APP_PRIVATE_KEY=<la chiave privata, su una riga con \n> GH_APP_CLIENT_ID=<il Client ID mostrato nella pagina della App> GH_APP_CLIENT_SECRET=<il client secret> GH_WEBHOOK_SECRET=<il segreto del webhook> - Nel progetto
webapri la scheda GitHub, scegli il repository dell'app e premi Aggancia repo.
7. Collega una macchina per l'agente
L'agente gira su una tua macchina Linux, con il tuo abbonamento: il codice resta lì. La macchina ha bisogno di Linux x86_64 o arm64 con systemd 254 o più recente, più Codex e Claude Code come detto all'inizio.
- Installa
bubblewrap,socate il portachiavi di sistema:sudo apt install bubblewrap socat gnome-keyring libsecret-tools - Su un server senza interfaccia grafica, crea la raccolta «login» del portachiavi, con l'utente che farà girare l'agente:
pkill -u "$(id -u)" gnome-keyring-d printf '\n' | gnome-keyring-daemon --unlock --components=secrets --daemonize - Su Ubuntu 24.04 e successivi, sblocca una volta l'isolamento che serve a
bubblewrap:sudo tee /etc/apparmor.d/bwrap >/dev/null <<'PROFILE' abi <abi/4.0>, include <tunables/global> profile bwrap /usr/bin/bwrap flags=(unconfined) { userns, include if exists <local/bwrap> } PROFILE sudo apparmor_parser -r /etc/apparmor.d/bwrap - In CloseYourIt apri Automator → Collega una macchina.
- Copia il comando e lancialo sulla macchina.
- Lancia
automator doctorsulla macchina: dice cosa manca ancora.
Su una macchina con solo Codex, imposta anche AUTOMATOR_WORK_ENGINE=codex nell'ambiente del servizio.
8. Dai il via libera alla macchina
Una macchina appena collegata non lavora finché una persona non lo permette.
- Apri Agenti e scegli la macchina.
- Premi Certifica host.
- In Dettagli e impostazioni controlla Chi fa il lavoro e Chi rilegge il lavoro. Con due motori conviene che rilegga l'altro.
9. Lascia il ticket a un agente
- Apri il ticket del passo 5.
- Nel riquadro Agenti, alla voce Chi lo lavora, scegli Agenti.
Dal terminale: cyi tickets eligibility <codice> --project web --allow. L'agente aspetta se il ticket dipende da un lavoro non finito o ha una domanda aperta che lo blocca.
10. Approva il piano
L'agente scrive prima un piano: cosa cambia e perché, i rischi, e quando il lavoro si potrà dire finito. Sul piano decide il CTO del progetto oppure, se il progetto non ne ha uno, il CTO dell'organizzazione: impostane uno se sono vuoti.
- Apri Approvazioni, oppure premi
ge poia. - Premi Valuta sul piano.
- Premi Approva il piano. Se qualcosa non va, Respingi con un motivo: torna una versione nuova.
11. Approva il lavoro
L'agente scrive la correzione e consegna un resoconto: cosa ha fatto, quali file sono cambiati, quali test sono girati.
- Se i controlli automatici del codice passano e chi rilegge lo accetta, il lavoro va avanti da solo.
- Altrimenti aspetta in Approvazioni un Approva il lavoro o un Respingi.
Dopo lo staging il rilascio aspetta 2 ore. Se in staging non compaiono errori nuovi, va in produzione da solo.
12. Chiudi l'errore
Quando la correzione è in produzione, apri l'errore, premi Risolvi e scrivi la Causa e il Rimedio. Se lo stesso errore torna da una release aggiornata, CloseYourIt lo riapre da solo.