---
title: "Issue trackers"
description: "File Faylee recordings as issues in Linear, GitHub, Jira, GitLab, Azure DevOps, ClickUp, Notion, Asana or Trello, and keep comments and status in step."
canonical: https://faylee.app/docs/integrations/issue-trackers
---

# Issue trackers

Connect your issue tracker and any recording can become an issue in a few seconds. Faylee drafts the issue from the capture, with the steps to reproduce, the errors, the failed requests and the environment, and adds a link back to the recording. Once the issue exists, comments can travel both ways, and closing the issue shows on the recording.

Faylee works with Linear, GitHub, Jira, GitLab (GitLab.com and self-hosted), Azure DevOps, ClickUp, Notion, Asana and Trello. A workspace can connect more than one.

## Connecting a tracker

A workspace admin connects a tracker under **Settings**, **Integrations**, in the **Issue trackers** group. See [Integrations overview](https://faylee.app/docs/integrations/overview.md) for the two ways to connect and how to tell that a connection works.

Each connection files into one place, which you choose while connecting:

| Tracker | Where issues go | Fields when connecting with keys |
|---|---|---|
| Linear | A team | Personal API key, Team key (the prefix of the team's issue ids, such as `ENG`), Webhook signing secret (optional) |
| GitHub | A repository | Access token (fine-grained, with read and write access to Issues), Repository (such as `acme/web`) |
| Jira | A project | Site, Account email, API token, Project key, Issue type (optional, Bug when left empty) |
| GitLab | A project | Access token (personal or project token with the `api` scope), Project (such as `acme/web`), GitLab address (only for self-hosted GitLab) |
| Azure DevOps | A project, as work items | Organization (such as `https://dev.azure.com/acme`), Project, Personal access token (Work Items, Read & write), Work item type (optional, Bug when left empty) |
| ClickUp | A list, as tasks | Personal API token, List ID (the number at the end of the list's URL), Webhook signing secret (optional) |
| Notion | A database, as pages | Integration secret, Database ID (the 32 characters in the database's URL), Title property (optional, Name when left empty) |
| Asana | A project, as tasks | Personal access token, Project ID (the number in the project's URL) |
| Trello | A list, as cards | API key, Token, List ID, API secret (optional) |

With one-click connect you don't type these in. You sign in to the tracker, then pick the team, repository, project, list or database from the choices Faylee loads.

## Filing from the viewer

On a recording's page, **Send to app** in the header shows the marks of the apps your workspace connected. Open it and pick a tracker under **Create an issue in**. Any member of the workspace can file an issue.

The **Create an issue** dialog has:

- **Tracker**, when your workspace connected more than one.
- **Title**, from the recording's title, or the assistant's title when the recording has none.
- **Assignee**, **Priority** and **Labels**, when the tracker offers them. See [Fields](#fields).
- **Description**, drafted from the capture. You can edit it before you file. See [The issue body](#the-issue-body).

**Create issue** files it. A link to the recording is added at the end of the description.

Issues already filed from a recording are listed at the top of **Send to app** under **Linked issues**, with a count on the button. A closed issue is shown struck through and marked closed.

Workspace admins also see **Connect an app…** at the bottom of the menu, which opens the Integrations page.

## Filing from the extension

You can file an issue at the moment you share a capture from the extension. In the review tab, **Share as** lists **Link you can share**, **Share via email**, and one entry for each connected tracker, such as **Linear issue**. Pick a tracker and the button becomes **Share and create Linear issue**.

Faylee uploads the recording, then files the issue with the title you gave it and a description drafted from the capture. The issue starts with the fields you last used with that tracker.

After sharing, the review tab tells you what happened:

- A link to the new issue, such as **Filed ENG-142**.
- "The tracker is not answering. Faylee keeps trying and links the issue once it exists."
- "The recording is shared, but the issue was not filed", with the tracker's reason.

Admins also see trackers the workspace hasn't connected yet in **Share as**. Picking one opens the Integrations page in the web app.

## Fields

Faylee loads the choices each tracker offers and shows only the fields it supports.

| Tracker | Assignee | Priority | Labels |
|---|---|---|---|
| Linear | Team members | Urgent, High, Medium, Low | Team labels |
| GitHub | People who can be assigned in the repository | | Repository labels |
| Jira | People who can be assigned in the project | Jira's priorities | |
| GitLab | Project members | | Project labels |
| Azure DevOps | | 1 (highest) to 4 (lowest) | |
| ClickUp | List members | Urgent, High, Normal, Low | |
| Notion | | | |
| Asana | Workspace members | | |
| Trello | Board members | | Board labels with a name |

Faylee keeps these choices cached and refreshes them in the background, so the dialog opens without waiting on the tracker.

## Remembered destinations

Faylee remembers the last five trackers you filed in and the fields you used with each, such as the assignee and labels. When you file again with the same tracker, those fields start filled in. The extension also starts **Share as** at the tracker you filed in last.

This memory is per person, so your choices don't change anyone else's.

## The issue body

The description is written in Markdown from the capture. Sections that have nothing to say are left out.

| Section | What it holds |
|---|---|
| What went wrong | What the reporter wrote |
| Summary, Actual behavior, Expected behavior | The assistant's findings, when it has read the recording |
| Likely cause (suggested by Claude) | The assistant's reading of the cause |
| Steps to reproduce | Numbered steps from the reporter's clicks, typing and navigation |
| Errors | Up to five uncaught errors and `console.error` messages |
| Failed requests | Up to five, with method, URL, status and time, and the reason when CORS or a GraphQL error caused it |
| Failed connections | WebSocket and EventSource connections that failed |
| Pages visited | Each page with the time it was opened, when there was more than one |
| Linked sessions | Sessions from LogRocket, Fullstory, Sentry Replay, PostHog or Datadog RUM that the page had open |
| Environment | When it was recorded (UTC), browser, operating system, device, viewport, screen, network, battery and incognito |

After the sections come the first page's address and the link to the recording:

```markdown
Page: https://shop.example.com/checkout

Recording: https://app.faylee.app/s/AbC123xYz0
```

Times the assistant cites are written as they appear in the player, such as `(at 0:12.4)`.

Trackers that don't take Markdown get the same content in their own format: Jira's document format, Notion blocks, and HTML in Azure DevOps.

## Two-way sync

Once an issue is linked, Faylee keeps the recording and the issue in step.

**From Faylee to the tracker.** A comment on the recording is posted to every linked issue, with the author's name, the time on the recording it points at, and a link to that moment. This works with every tracker.

**From the tracker to Faylee.** Comments on the issue show up as comments on the recording, under the commenter's name in the tracker, and notify people the way any comment does. Closing the issue marks it closed on the recording, and reopening it clears that. This works with Linear, GitHub, Jira, GitLab, ClickUp and Trello. Azure DevOps, Notion and Asana don't send changes back.

Comments Faylee posted carry `(via Faylee)`, so they are never copied back again.

| Tracker | What counts as closed |
|---|---|
| Linear | The issue moves to a completed or canceled state |
| GitHub | The issue is closed |
| Jira | The issue's status is in the Done category |
| GitLab | The issue is closed |
| ClickUp | The task moves to a closed status |
| Trello | The card is archived |

### Setting up the webhook

The tracker tells Faylee about comments and status changes through a webhook.

With one-click connect, Faylee adds the webhook itself when you finish setup and removes it when you disconnect. There is nothing to set up.

With keys, the tracker's card shows **Sync comments and status back**, with the webhook address to add in the tracker and what to subscribe to:

| Tracker | Where to add it | Events | Secret |
|---|---|---|---|
| Linear | Settings, API, Webhooks | Comments and Issues | Copy the webhook's signing secret from Linear into the connection's **Webhook signing secret** |
| GitHub | The repository's Settings, Webhooks, as JSON | Issues and Issue comments | Paste the **Signing secret** from the card as the webhook's Secret |
| Jira | System, Webhooks | Comment created and Issue updated | Paste the **Signing secret** from the card as the webhook's Secret |
| GitLab | The project's Settings, Webhooks | Comments and Issues events | Paste the **Signing secret** from the card as the Secret token |
| ClickUp | A webhook created for the address | `taskCommentPosted` and `taskStatusUpdated` | Copy the secret ClickUp returns into the connection's **Webhook signing secret** |
| Trello | A webhook on the board (`idModel` is the board id) | Created with the webhook | Add the **API secret** to the connection so Faylee can check the webhook comes from Trello |

Faylee turns away webhooks it can't verify. When it does, the card says when and why. See [Rejected webhooks](https://faylee.app/docs/integrations/overview#rejected-webhooks).

## When a tracker is down

If the tracker times out, returns a server error or asks Faylee to slow down, the issue isn't lost. It waits as pending, and **Send to app** shows "Filing in Linear, retrying…". Faylee tries again with growing gaps between attempts and links the issue once the tracker accepts it.

If the tracker is still down after the retries, the menu shows "Could not file in Linear" with the reason.

If the tracker refuses the issue outright, for example because a token was revoked or a field isn't allowed, you see its reason right away and nothing is left behind. Fix the cause and file again.

## Per-tracker notes

- **GitHub.** One-click connect installs Faylee's GitHub App on the repositories you choose. Disconnecting uninstalls it.
- **GitLab.** One-click connect is for GitLab.com. For a self-hosted GitLab, use **Use an API key** and fill in **GitLab address**.
- **Jira.** With one-click connect, Faylee learns your Jira site while you sign in and adds a webhook for the project you pick. With keys, you also give the site address and your account email.
- **Azure DevOps.** One-click connect signs in with a Microsoft work account. Some companies only allow apps an Entra admin approved, in which case that admin approves Faylee once. A Bug keeps the report in Repro Steps, and other work item types in Description.
- **Notion.** Share the database with the integration in Notion, or Faylee can't see it. The one-click setup lists the databases you shared while connecting.
- **Trello.** The one-click setup lists every open list on your open boards, named by board.

## Related

- [Integrations overview](https://faylee.app/docs/integrations/overview.md)
- [Slack](https://faylee.app/docs/integrations/slack.md)
- [The assistant](https://faylee.app/docs/viewer/assistant.md)
- [Comments and triage](https://faylee.app/docs/viewer/collaboration.md)