Connecting a tracker

Every tracker works the same way: connect it once under the project's Settings › Trackers, choose where new reports go, and from then on a report becomes a ticket there with one click, or on its own if Send instantly is on. Notion and Linear have pages of their own; the rest are below, the help desks after the issue trackers.

Using a tracker that is not here? Write to hello@brokenhere.com and we add it. Until then, every report waits in your Broken Here inbox with the same evidence.

How connecting works

Most trackers connect with one button. Connect Jira (or Linear, GitLab, ClickUp, Asana, Trello, monday.com) opens the tracker's own screen, you allow Broken Here, and you come back to that tracker's row to pick where tickets go, wherever you pressed it. Nothing to copy.

A key still works, under Use a key instead on the same row: for a workspace that does not allow outside apps. For some trackers the key has a box or two beside it (Jira's site, Trello's API key). We ask the tracker whether it accepts the key before storing anything:

• A key it refuses is not saved, and a key already saved stays in use.
• If the tracker cannot be reached, the key is saved and the row says it was not checked.
• Keys are stored encrypted and never shown again. Paste a new one to replace it. The boxes that are not secret, like a site or an email, stay filled in.

Once the key is in, the row offers a menu of where tickets can go (a project, a list, a board) and you pick the default one.

A report makes one ticket per tracker. The first tracker you connect sends every new report on its own; any later one starts with Send instantly off, so connecting a second never doubles every ticket.

What lands in the ticket

The same thing in every tracker: the reporter's own words, then Where (the URL and the element), Environment, JavaScript errors, Failed requests, Console warnings and errors, the screenshots, and a link back to the full report. Each tracker gets it in its own format: markdown where the tracker takes markdown, rich text where it takes HTML, and Atlassian's own document format for Jira. A ticket that would be longer than the tracker allows is cut by whole sections, with a line saying the rest is on the full report.

Screenshots are links through Broken Here rather than signed storage links, so they do not expire. In Jira, Asana, monday.com and the help desks that take HTML (Zendesk, Freshdesk) they are a Screenshot link rather than an image in the ticket.

GitHub Issues

Nothing is pasted. Issues open through the GitHub App, the same installation the coding agent uses, so there is one thing to install and one thing to uninstall.

1. On the GitHub Issues row, press Connect GitHub. GitHub asks which repositories to share; tick the one issues belong in.
2. Back on the row, choose the Default repository.

If the project already has GitHub connected for the coding agent, the row skips straight to the repository menu. Issues can go to a different repository than the one the agent works on.

Disconnecting GitHub under GitHub & coding agent, or uninstalling the app on GitHub, disconnects GitHub Issues too.

Jira

Press Connect Jira, allow Broken Here, and choose the default project. Or, with a key:

Jira Cloud, at your-site.atlassian.net.

1. Create an API token at id.atlassian.com › Security › API tokens. Use Create API token, not the one with scopes: a scoped token is refused at your site's own address.
2. On the Jira row, give your Jira site (acme, acme.atlassian.net or any address you open Jira at), the email of the Atlassian account the token belongs to, and the API token.
3. Choose the Default project. The menu lists the projects that account can create issues in.

Issues are opened as that account. Each is a Bug when the project has that type, a Task when it does not, and otherwise the project's first standard type. A project whose create screen requires a field of its own (a component, a custom field) refuses the issue, and the report says it was not sent.

GitLab

Press Connect GitLab, allow Broken Here, and choose the default project. Or, with a key:

1. Create a personal access token with the api scope under Preferences › Access tokens in GitLab.
2. On the GitLab row, paste it. On a self-managed GitLab, give its address too (https://gitlab.acme.com); it has to be reachable from the internet over https.
3. Choose the Default project. Projects with issues switched off are not offered.

ClickUp

Press Connect ClickUp, allow Broken Here, and choose the default list. Or, with a key:

1. In ClickUp, open Settings › Apps and generate your API token (pk_…).
2. Paste it on the ClickUp row.
3. Choose the Default list. The menu names each list with its space and folder, and its workspace when you are in more than one; lists you can only read are not offered.

The report becomes a task with the report as its description, in markdown.

Asana

Press Connect Asana, allow Broken Here, and choose the default project. Or, with a key:

1. Create a personal access token in Asana's developer console.
2. Paste it on the Asana row.
3. Choose the Default project, from every workspace the token can see.

The report becomes a task in that project, with the report as its description.

Trello

Press Connect Trello, allow Broken Here, and choose the default list. Or, with a key:

Trello's API takes two things: the API key of a Power-Up, and a token you grant it.

1. At trello.com/power-ups/admin, make a Power-Up (any name; it is only a holder for the key) and generate its API key.
2. Beside the key, press the Token link and allow it. Copy the token.
3. On the Trello row, paste the API key and the Token.
4. Choose the Default list, named with its board.

Cards open at the top of the list. Trello keeps at most 16,384 characters of a card's description, so a report from a very noisy page is cut shorter there than elsewhere, with a line saying the rest is on the full report.

monday.com

Press Connect monday.com, allow Broken Here, and choose the default board. Or, with a key:

1. In monday.com, open your avatar › Developers › API token, and copy it. (An admin can also find it under Administration › Connections › API.)
2. Paste it on the monday.com row.
3. Choose the Default board. Boards you can only view, and subitem boards, are not offered.

The report becomes an item named after it, with the report as its description. Where a board cannot take a description, it is posted as the item's first update instead.

Help desks

Zendesk, Intercom, Freshdesk, HubSpot, Front and Crisp take a report the way they take anything the team should look at. Two things are the same in all of them:

• Nobody outside your team is written to. A help desk emails the customer on a ticket, and the address a reporter types into the widget could be anybody's. So a report is never filed under it: it is filed under you (the account that connected), or under a contact made for reports with no address at all, and it lands as something internal (a private note, a back-office ticket, a discussion). The reporter's name is in the ticket; their address stays on the full report.
• Zendesk, Intercom, HubSpot and Front connect only with their button. Their terms do not let a product ask for your key, so there is no key to paste. Crisp connects with its button too, and keeps a key as the fallback. Freshdesk has no way for an outside product to connect other than a key, so it takes one.

Zendesk

1. On the Zendesk row, give your Zendesk address (acme, or acme.zendesk.com) and press Connect Zendesk.
2. Allow Broken Here on Zendesk's screen, signed in as an agent or admin.
3. Choose the Default group. The menu lists the groups you can assign a ticket to.

Each report is a ticket in that group, with the report as a private note, and you as the requester, so Zendesk's own notifications stay inside the team. A Zendesk connection that sends nothing for 90 days has to be connected again: that is as long as Zendesk lets it last unused.

Intercom

Press Connect Intercom, allow Broken Here, and choose the default ticket type. Only Back-office and Tracker types are offered: those are the ones Intercom keeps from customers. A type with a field of your own that must be filled in to create a ticket is not offered either, since a report cannot fill it.

Intercom will not open a ticket without a contact, so every report's ticket goes on one lead named Broken Here, with no address, made on the first report.

Freshdesk

1. In Freshdesk, open your profile picture › Profile settings and copy your API key.
2. On the Freshdesk row, give your Freshdesk address (acme or acme.freshdesk.com, never a custom domain: Freshdesk's API does not answer there) and paste the key.
3. Choose the Default group.

Each report is a ticket in that group, filed under your name, so the only person Freshdesk writes to about it is you.

HubSpot

Press Connect HubSpot, allow Broken Here, and choose the default ticket pipeline. Each report is a ticket in the pipeline's first open stage, with the report as its description and no contact on it.

Front

Press Connect Front (a Front admin has to allow it) and choose the default inbox. Each report is a discussion there, Front's internal conversation, which only your team sees.

Crisp

1. On the Crisp row, press Connect Crisp. Crisp opens the page for installing Broken Here; your Crisp workspace's owner installs it.
2. Crisp then shows Broken Here's page inside Crisp (Settings › Plugins › Broken Here). Press Link to Broken Here.
3. Broken Here opens in a new tab: choose the project and press Link. The workspace is then the only destination.

Or, with a key, under Use a token key instead: in Crisp, open Settings › Workspace settings › Advanced configuration and generate an API token (only the owner can), copy the Workspace ID from Setup instructions, and paste all three.

Each report is a conversation in your Crisp inbox from Broken Here, titled with the report, with the report itself as a private note. No address is set on it, so Crisp has nobody to email.

When a send fails

A tracker refusing is ordinary: a token expires, somebody leaves, a project is renamed. The report is safe either way. The report's Tracker panel says which of three it was (the key was refused, the destination is gone, or the tracker could not be reached), with a link to the row that fixes it, and Send tries again. A report sent on its own by Send instantly that could not be filed says so in the inbox too.