# Sentry

Install the Sentry integration, link a Sentry project to a project, turn errors into tasks and resolve them in Sentry when the work is done.

Sentry is a service that records the errors people run into on your website or app: what broke, how often, and for how many people. The Taskstand integration for Sentry shows those errors (Sentry calls them issues) inside the project you do the work in, next to its tasks and commits, and lets you turn an issue into a task. When the task is completed, Taskstand resolves the issue in Sentry for you.

## What the integration does

- **Shows your Sentry issues in Taskstand**, on the **Code** page of the project they belong to.
- **Turns an issue into a task**, or links it to a task that already exists.
- **Keeps Sentry up to date.** You can resolve, ignore or reopen an issue from Taskstand, and completing a task resolves the open issues linked to it.
- **Reopens work when an error comes back.** If a resolved issue returns (a regression), its completed tasks open again in Taskstand.
- **Tells you what is new**, with a red count on the **Code** button, next to the project in the sidebar (on its folder while that is folded shut) and on the dashboard. It counts the open issues you have not dealt with yet (see **The Code page** below), and clicking it on the dashboard takes you there. Tasks you have not read get a blue number of their own next to it, see [Tasks](<https://taskstand.com/help/tasks>). New issues also raise the attention meter on the dashboard, a little less than a late task.

Sentry tells Taskstand straight away when an issue appears or changes status. The counts (events, users, last seen) are read again when somebody opens the **Code** page and the last read is more than ten minutes old, and once a day for every linked project.

## Requirements

| What | Needed |
|---|---|
| Sentry | An organisation on sentry.io, the hosted Sentry service. A self-hosted Sentry cannot be linked. |
| Permission in Sentry | The person who installs the integration must be allowed to install integrations in the Sentry organisation. In Sentry that is usually the Owner or Manager role. |
| Plan in Taskstand | The plan of the **project owner** must carry Sentry: Plus, Pro or Business, and the free trial. See [Plans and limits](<https://taskstand.com/help/plans-and-limits>). |
| Role in Taskstand | Only the **Owner** of a project installs the integration and links Sentry projects to it. |

Who sees the issues in Taskstand:

| Role on the project | Sees Sentry issues | Can change them |
|---|---|---|
| Owner | Yes | Yes |
| Manager | Yes | Yes |
| Team member | Yes | Yes |
| Client, Reader, Restricted | No | No |

The installation belongs to the Taskstand account that installed it. Only that person links the projects of that Sentry organisation, and only onto projects they own. If another Taskstand account already connected the same Sentry organisation, ask that person to link the project, or remove the app in Sentry and install it again.

## Install the integration

Always start the installation from Taskstand. An installation that starts in Sentry's own integration directory cannot be matched to your account and is refused.

1. Open the project and click the gear icon (**Project settings**), then **Code**.
2. In the block **Errors from Sentry**, click **Connect Sentry**. Sentry opens.
3. Sign in to Sentry if asked, choose the organisation, look at the permissions and approve the installation.
4. Sentry sends you back to the **Code** settings of your project, where Taskstand says **Sentry is connected. Pick the project to link.**

Finish the trip within half an hour. If you see **This Sentry connection was not started here**, the link ran out, was already used, or was started from Sentry itself: start again with **Connect Sentry**. If Sentry now lists the app as installed, remove it there first.

To connect a second Sentry organisation, use **Connect it** after **Another Sentry organisation?** in the same block.

## Link a Sentry project

A Sentry project is the place in Sentry that collects the errors of one website or app. After the installation you pick which of them belongs to this Taskstand project.

1. In **Project settings**, **Code**, click **Pick a Sentry project**.
2. If you connected more than one organisation, choose it under **Sentry organisation**.
3. Choose the project under **Which Sentry project?** and click **Link**.
4. Taskstand says **The issues are on their way.** The open issues seen in the last 90 days arrive within moments.

Good to know:

- A Taskstand project can have up to five Sentry projects. Use **Link another Sentry project** to add one.
- One Sentry project can be linked to several Taskstand projects, for example when one app serves more than one client project.
- Each linked Sentry project shows its name, its organisation and when it was last read. The circular arrow button (**Read this project again**) reads it again right away.
- If a link stops working, it says so in the settings with the reason, and the project settings show a red dot on **Code**.

## Using Sentry issues in Taskstand

### The Code page

Once a Sentry project is linked, the project bar shows a **Code** button. It opens a page with the issues (**Sentry issues**) and, if a GitHub repository is linked too, the commits. On a smaller screen, **Commits** and **Sentry issues** switch between the two.

Each issue shows its title, the place in the code, its Sentry id (a link that opens the issue in Sentry), the number of events and users, when it was last seen, and the tasks it is linked to. A coloured dot shows the level. An open issue you have not dealt with yet carries a **New** label and counts in the red number on the **Code** button, in the sidebar and on the dashboard. It stays new until you do something with it:

- **Mark as seen** in the menu next to the issue takes it out of new for you. Your colleagues still see it as new.
- **Mark all as seen** above the list does that for every open issue of the project at once.
- Making a task of the issue, or linking it to a task, takes it out of new for everybody on the project, because somebody has it on their list now.

An issue that comes back after being resolved or ignored is new again, for everybody.

Narrow the list with:

- the search field **Search the error or its id**
- the status: **Open** (the default), **Resolved**, **Ignored** or **All issues**
- the level: **All levels**, **Fatal**, **Error**, **Warning**, **Info** or **Debug**
- the Sentry project, when more than one is linked

The circular arrow button next to **Last read** (**Read the issues again**) fetches the latest counts from Sentry while you wait.

### Turn an issue into a task

1. Click the **+** button on the issue (**Make a task of this**).
2. The form **Make a task of this issue** is filled in with the title of the error, and a description with a link to the issue, the whole error message, the file and function it happened in, and how often and for how many users it happened.
3. Read it and change what you like. An error message can hold text anybody typed into your site, so nothing becomes a task without somebody reading it first.
4. Pick the **Section**, put **Labels** on it if you like (click one the project has, or type a new one and press Enter), and click **Make task**. A new label is only made when you save.

The task is linked to the issue straight away.

### Link an issue to an existing task

Open the task and find **Sentry issues** in the task details. Click **Link a Sentry issue**, search for the error or its id, and click it. The **x** button (**Unlink this issue**) takes it off again. You need to be allowed to edit the task.

### Resolve, ignore or reopen an issue

Click the **...** button on an issue:

- **Resolve** marks it resolved in Sentry.
- **Ignore** archives it in Sentry until it gets worse, the same as Sentry's own Archive button. If it starts hitting many more people, Sentry opens it again by itself.
- **Reopen** appears on a resolved or ignored issue and opens it again.

Taskstand asks Sentry first and then shows what Sentry answers, so the list never says something Sentry did not accept. This menu is not available on an archived project.

### Complete the task, resolve the issue

When you complete a task with open Sentry issues linked to it, Taskstand resolves those issues in Sentry. The task says so before you complete it: **Completing this task resolves its open issues in Sentry. If the error comes back, the task opens again.**

- An issue that is also linked to another task that is still open stays open until that task is completed too.
- Reopening the task afterwards leaves the issue resolved in Sentry.

### When an error comes back

If an issue that was resolved or ignored becomes open again in Sentry (a regression, an escalation, or somebody reopening it), Taskstand reopens the completed tasks linked to it. The task history shows that Sentry reopened it and which issue came back. Archived tasks and tasks in an archived project stay as they are.

### Handing a task to an AI agent

When you copy a task for an AI coding agent, its Sentry issues travel along, and the prompt tells the agent not to resolve anything in Sentry itself: Taskstand does that when the task is completed. See [Hand a task to an AI agent](<https://taskstand.com/help/ai-agent-prompt>).

## What Taskstand changes in Sentry

Taskstand writes only these things to Sentry:

| When | What changes in Sentry |
|---|---|
| Somebody chooses **Resolve**, **Ignore** or **Reopen** in Taskstand | The status of that issue, plus a note on the issue such as "Resolved in Taskstand by Anna de Vries." |
| Somebody completes a task that has open issues linked | Those issues are resolved, with a note naming the person, the task reference, its title and its link |
| Right after the installation | Taskstand confirms to Sentry that the installation arrived |

Sentry shows the Taskstand app as the one who changed the status in the issue history. The note says which person did it, in that person's language. Taskstand does not create, edit, merge or delete issues, and changes nothing in your projects, teams, alerts or settings in Sentry.

## Permissions and data

The integration asks Sentry for **Issue & Event: Read & Write**, and receives Sentry's notifications about issues and about the integration being removed.

What Taskstand reads from Sentry:

- the name and region of your organisation, and its list of projects, to show the project picker
- per issue: its title, the place in the code, its level, its status, its Sentry id, the number of events and users, when it was first and last seen, and its link in Sentry

What Taskstand does not store: stack traces, the events themselves, breadcrumbs, or the details of the people who ran into an error. The user count is only a number.

How Taskstand handles the issue text:

- Issue text is written by the software your customers use, and can contain anything a visitor typed. Taskstand shows it as plain text and never as a link or formatting, except the link to the issue in Sentry itself.
- An issue becomes a task only when a member chooses to make one, after reading the form.
- Only the Owner, Managers and Team members of the project see the issues.
- The notes Taskstand posts in Sentry can hold the name of a task and a link to it. Everybody in your Sentry organisation can read them.

If the plan of the project owner no longer carries Sentry, the links stay but nothing new is read, the issues are no longer shown and completing a task no longer changes Sentry. The owner can still unlink.

## Uninstall

### In Sentry

1. In Sentry, open **Settings** for your organisation and go to **Integrations**.
2. Open the Taskstand integration.
3. Click **Uninstall** and confirm.

Sentry then stops sending issues to Taskstand and Taskstand can no longer read or change anything. In Taskstand, the linked Sentry projects show **Switched off** in the project settings, and the **Code** page says the project no longer updates. The issues already read and their links to tasks stay, so you keep the history. Installing the app again for the same organisation with **Connect Sentry** switches the links back on.

### In Taskstand

- **Unlink** (the **x** next to a linked Sentry project in **Project settings**, **Code**) takes one Sentry project off this project. Its issues are removed from the project, and so are their links to tasks. The tasks themselves stay.
- **Disconnect** next to **Connected organisation** removes the whole Sentry organisation from your account. Its Sentry projects are unlinked from every project of yours, and their issues go with them. The app stays installed in Sentry until you remove it there too.

To remove everything, disconnect the organisation in Taskstand and uninstall the app in Sentry.

## Support

Questions about the integration, or something that does not work as described here? Write to [support@taskstand.app](mailto:support@taskstand.app). Tell us the name of your Sentry organisation and the project, and what you expected to happen.