# Issue triage

> MergeHarbor reads new issues in Jira, Azure Boards, Linear, Asana, GitHub and GitLab and keeps one helpful comment on each, with possible duplicates, questions, acceptance criteria, triage suggestions and likely root causes.

When someone files an issue, MergeHarbor can read it and leave **one comment** on it. If the issue is triaged again, the same comment is updated, never repeated.

Issue triage works with Jira (Cloud and Data Center/Server), Azure Boards (Azure DevOps Services and Server), Linear and Asana through your [integrations](https://mergeharbor.com/docs/integrations), and with GitHub Issues and GitLab Issues on repositories you have connected.

## What the comment covers

Turn each part on or off for the whole organization or for one project.

- **Possible duplicates**: similar open or closed issues in the same project, with a link, how similar they are and why.
- **Questions to clarify**: what is missing, phrased as questions to the reporter, such as steps to reproduce, environment, expected and actual behaviour, or scope.
- **Proposed acceptance criteria**: testable criteria, written as a checklist or as Given/When/Then if your project already uses that. Pull requests that link the issue are checked against them.
- **Triage suggestions**: priority, labels and component from your tracker's existing values, the likely code area, suggested owners from CODEOWNERS and recent authors, and a size from S to XL with the reason.
- **Likely root cause** (off by default): for bug reports, the probable cause with file and line pointers.

Suggestions are only suggestions. Nothing changes on the issue until someone selects **Apply suggestions** in MergeHarbor, unless you turn on auto-apply for a project. For a likely root cause with a proposed change, **Open fix PR** opens a pull request against your default branch after you confirm.

## Turn it on

1. Open **Triage** in the sidebar, then **Settings**.
2. Turn on issue triage for the organization, or add the projects you want.
3. Choose the parts of the comment you want and a monthly credit cap per project.
4. For Jira, Azure Boards, Linear and Asana, create a webhook and paste its URL (and secret) into the tracker. For Azure Boards, add a **Web Hooks** service hook for **Work item created** and enter the secret as the basic authentication password. Also subscribe the webhook to new comments (Jira **Comment created**, Linear **Comments**, Azure Boards **Work item commented on**) so a discussion re-triages the issue. Without a webhook, MergeHarbor checks for new issues every few minutes.

For GitHub Issues, the MergeHarbor GitHub App needs the **Issues** and **Issue comment** events and write access to issues. GitLab project webhooks include issue events.

You can also triage any issue by pasting its link in **Triage**, or with `triage <issue link>` in Slack, Microsoft Teams or Google Chat.

## What triage reads

Before it writes anything, triage reads what the issue links to: links in the description
and comments, remote links, attachments, linked issues, the parent and sub-tasks. It reads
Confluence pages (and their child pages), Figma frames, Notion, Google Drive and OneDrive
documents, other issues, Sentry and Datadog errors, pull requests, commits and code links
on your connected repositories, and public web pages. Chat conversations (Slack, Teams,
Google Chat) are never read.

Each link is read with your own connection and its limits. A link MergeHarbor cannot
read (no access, not found, too slow or too large) is skipped with the reason, and
triage carries on. The issue page shows every source under **Sources read**, filling in
while triage runs. Questions a linked page already answers are not asked: the answer is
shown with a citation such as [S1], which links to the page.

Reading costs nothing. A triage stays 1 credit up to 16,000 tokens of linked text; you
can raise the budget under **Triage settings → Linked sources**, at 1 more credit per
further 16,000 tokens used.

By default, documents triage reads are used for that triage, reused for 10 minutes, and
deleted within 24 hours. An administrator can turn on **Keep linked documents in the
knowledge base** (under **Triage settings** or **Memory → Knowledge base**): documents
are then kept for reuse by later triage and deleted a chosen number of days (1–365,
default 30) after their last use. Turning it off deletes the stored documents at once.
Either change is recorded in the audit log.

## Cost

Issue triage is off until you turn it on.

- A triage uses **1 credit**. Looking for a likely root cause adds **2 credits**, is only done for bug reports, and is charged even when no root cause is found.
- Each project has a **monthly credit cap**. When it is reached, issues are skipped until the next month.
- New comments re-triage an issue, 10 minutes after the first one, so a whole discussion is one run. Triaging an unchanged issue again costs nothing.
- Issues opened by bots and very short issues are skipped.

Credits used appear on each issue, per project in **Triage**, and in **Billing → Usage**.

## Permissions

| Action                             | Permission                       |
| ---------------------------------- | -------------------------------- |
| See triaged issues                 | `pulls.read` (organization-wide) |
| Triage an issue, apply suggestions | `pulls.review`                   |
| Open a fix pull request            | `pulls.fix`                      |
| Change settings and webhooks       | `settings.manage`                |