Skip to content
CloseYourItdocsPages

Documentation / Recipes / Recipes

From an error to a ticket worked by an agent

A browser error becomes a ticket, and an agent on your machine proposes the fix for you to approve.

An error in your web app becomes a ticket with one click. An agent, running on a Linux machine of yours, takes that ticket, writes a plan and the fix, and stops at every step that needs a decision: you approve the plan and the work.

Before you start you need:

  • the code of the app in a GitHub repository;
  • access to the server of the installation, to connect it to GitHub in step 6;
  • a Linux machine for the agent, with Codex installed and signed in and, if you want Claude to do the work, Claude Code installed and signed in. They are programs of OpenAI and Anthropic, each with its own subscription: install them following their own instructions. Install Codex with your user's npm (for example the one from mise), not with sudo npm -g.

1. Create the project and the key

  1. In CloseYourIt create a project for the app, for example web.
  2. In the project's settings create an ingest token.
  3. Copy the publicKey and the project id. The publicKey is not secret: it is made to live in browser code. Never put the secret token (cyi_…) in the browser.

2. Install the SDK

npm install @bussolabs/closeyourit-js

3. Configure it

Call init once, as early as possible in the page:

import * as CloseYourIt from "@bussolabs/closeyourit-js"

CloseYourIt.init({
  endpointUrl: "https://bugs.example.com",
  publicKey: "<public key of the token>",
  projectId: "<project id>",
  environment: "production",
  release: "[email protected]",
})

From now on unhandled exceptions and rejected Promises reach CloseYourIt by themselves, with the clicks, navigation and requests that came before.

4. See the error

To try it, throw an error in a page of the app, for example from a button:

throw new Error("Checkout total is NaN")

Open Errors: the error is there as one row. Open it to read the lines of code it went through and what happened before.

5. Turn the error into a ticket

  1. On the error page press Promote to ticket.
  2. Check the preview: project, title, the place in the code, how many times it happened.
  3. Press Create the ticket.

A ticket of type Bug is born, linked to the error. From the terminal the same step is cyi errors promote <id> --project web.

6. Connect the installation to GitHub

The agent works on the code of the repository and hands over the fix as a pull request. The installation reaches GitHub through its own GitHub App, created once. If the GitHub tab of the project already lists your repositories, skip to point 4.

  1. On GitHub open Settings → Developer settings → GitHub Apps → New GitHub App and fill in:
    • Callback URL: https://bugs.example.com/member/integrations/github/callback, and tick Request user authorization (OAuth) during installation;
    • Webhook URL: https://bugs.example.com/github/webhook, with a secret you generate;
    • repository permissions: Contents read and write, Pull requests read and write, Actions read, Environments and Secrets read and write, Metadata read;
    • events: Push, Create, Release, Pull request.
  2. Create the App, then generate a private key and a client secret.
  3. On the server add these lines to /opt/closeyourit/.env, then run closeyourit restart:
    GH_APP_ID=<the App ID>
    GH_APP_SLUG=<the name in the App address>
    GH_APP_PRIVATE_KEY=<the private key, on one line with \n>
    GH_APP_CLIENT_ID=<the Client ID shown on the App page>
    GH_APP_CLIENT_SECRET=<the client secret>
    GH_WEBHOOK_SECRET=<the webhook secret>
    
  4. In the web project open the GitHub tab, pick the repository of the app and press Link repository.

7. Connect a machine for the agent

The agent runs on a Linux machine of yours, with your subscription: the code stays there. The machine needs Linux x86_64 or arm64 with systemd 254 or newer, plus Codex and Claude Code as said at the start.

  1. Install bubblewrap, socat and the system keyring:
    sudo apt install bubblewrap socat gnome-keyring libsecret-tools
    
  2. On a server without a desktop, create the keyring's «login» collection, as the user that will run the agent:
    pkill -u "$(id -u)" gnome-keyring-d
    printf '\n' | gnome-keyring-daemon --unlock --components=secrets --daemonize
    
  3. On Ubuntu 24.04 and newer, allow once the isolation bubblewrap needs:
    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 open Automator → Connect a machine.
  5. Copy the command and run it on the machine.
  6. Run automator doctor on the machine: it says what is still missing.

On a machine with Codex only, also set AUTOMATOR_WORK_ENGINE=codex in the service environment.

8. Give the machine the go-ahead

A newly connected machine does not work until a person allows it.

  1. Open Agents and pick the machine.
  2. Press Certify host.
  3. In Details and settings check Who does the work and Who reviews the work. With two engines, let the other one review.

9. Let an agent take the ticket

  1. Open the ticket from step 5.
  2. In the AI agents box, under Who works it, pick Agents.

From the terminal: cyi tickets eligibility <code> --project web --allow. The agent waits if the ticket depends on unfinished work or has an open question that blocks it.

10. Approve the plan

The agent writes a plan first: what changes and why, the risks, and when the work can be called done. The plan is decided by the Project CTO or, if the project has none, by the Organization CTO: set one of the two if they are empty.

  1. Open Approvals, or press g then a.
  2. Press Review on the plan.
  3. Press Accept the plan. If something is wrong, Reject with a reason: a new version comes back.

11. Accept the work

The agent writes the fix and hands over a work report: what it did, which files changed, which tests ran.

  • If the automatic code checks pass and the reviewer accepts it, the work moves on by itself.
  • Otherwise it waits in Approvals for Accept the work or Reject.

After staging the release waits 2 hours. If no new error shows up on staging, it goes to production by itself.

12. Close the error

When the fix is in production, open the error, press Resolve and write the Cause and the Fix. If the same error comes back from an up-to-date release, CloseYourIt reopens it by itself.