Vai al contenuto
CloseYourItdocsPagine

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 npm del tuo utente (per esempio quello di mise), non con sudo npm -g.

1. Crea il progetto e la chiave

  1. In CloseYourIt crea un progetto per l'app, per esempio web.
  2. Nelle impostazioni del progetto crea un token di ingest.
  3. Copia la publicKey e l'id del progetto. La publicKey non è segreta: è fatta per stare nel codice del browser. Il token segreto (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

  1. Nella pagina dell'errore premi Promuovi a ticket.
  2. Guarda l'anteprima: progetto, titolo, il punto del codice, quante volte è successo.
  3. 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.

  1. 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.
  2. Crea la App, poi genera una chiave privata e un client secret.
  3. Sul server aggiungi queste righe a /opt/closeyourit/.env, poi lancia closeyourit 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>
    
  4. Nel progetto web apri 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.

  1. Installa bubblewrap, socat e il portachiavi di sistema:
    sudo apt install bubblewrap socat gnome-keyring libsecret-tools
    
  2. 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
    
  3. 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
    
  4. In CloseYourIt apri Automator → Collega una macchina.
  5. Copia il comando e lancialo sulla macchina.
  6. Lancia automator doctor sulla 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.

  1. Apri Agenti e scegli la macchina.
  2. Premi Certifica host.
  3. 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

  1. Apri il ticket del passo 5.
  2. 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.

  1. Apri Approvazioni, oppure premi g e poi a.
  2. Premi Valuta sul piano.
  3. 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.