---
title: "Issue tracking"
description: "Keep an incident's actions and follow-ups in step with issues in Linear or Jira, both ways, and choose when a new item gets an issue."
canonical: https://firefight.app/docs/workspace/issue-tracking
---

# Issue tracking

Firefight can keep an incident's actions and follow-ups in step with issues in an issue tracker you connected. Change an item's title, status or assignee in Firefight and its issue follows, and a change to the issue's title, status or assignee comes back to the item.

You set it up under **Settings → Workspace**, in **Issue tracking**. Like the rest of the Workspace page, it is admin-only.

## Connect the tracker

Open **Configure → Integrations** and choose Linear or Jira.

- **Linear** connects one way, through Firefight's own Linear app. See [Linear](https://firefight.app/docs/api/integrations#linear) for how to connect it. The same connection is the one Halon uses to read and open issues, and changes made in Linear reach Firefight through the app, so there is nothing to paste.
- **Jira** offers two ways in, described below.

| Way | What it gives you |
|---|---|
| **Connect for issue sync**, with **Connect the Jira app** | Firefight's own Jira app. Firefight registers Jira's webhook itself, so changes made in Jira reach it with nothing to paste. Choose this one for issue tracking. Connect it to the site your issues live on. |
| **Continue with Jira** | Atlassian's own server, which Halon also uses to read and open issues in a chat. Issue tracking works with it too, but you create Jira's webhook yourself, as described below. |

The Jira app connection is named **Jira issue sync**, so it sits beside the one Halon uses.

## Choose the tracker

Pick the connection in **Issue tracker**. A workspace with several tracker connections lists each one, and items are kept in step with one of them at a time.

Below it, say where new issues go:

| Tracker | What you fill in |
|---|---|
| Linear | **Team**, the key or name of the team new issues are filed in, such as `ENG`. |
| Jira | **Site**, such as `acme.atlassian.net`, and **Project key**, such as `OPS`. **Issue type** is optional and is Task when you leave it empty. |

Press **Save changes**. Choosing a different tracker later asks for these again.

Choosing a tracker switches on the tracker tools issue tracking uses and grants exactly those to **Firefight issue sync**, the agent that makes every change in the tracker. It holds nothing else, and never borrows a person's access, so an item gets its issue whoever made it. Your [approval rules](https://firefight.app/docs/gateway/approvals.md) still apply to it. Choosing another tracker, or none, takes the grants back. If someone later takes one of them away under **Gateway → Permissions**, or switches one of the tools off, the setting says so. Choose the tracker again to put it back.

## Choose when an item gets an issue

**Open an issue for a new item** decides what happens when someone adds an action or a follow-up, from Slack, the dashboard, the API, an agent over MCP or Halon:

| Choice | What happens |
|---|---|
| Never | No issues are opened, and items offer no way to open one. This is the default. |
| Only when someone asks | No issue is opened on its own. Each item offers **Create issue**. |
| Always for follow-ups | Every new follow-up gets an issue. Actions offer **Create issue**. |
| Always for actions and follow-ups | Every new item gets an issue. |

Any choice other than **Never** needs a tracker chosen above, and saving without one says so.

The issue carries the item's title, the incident's identifier and a link back to the incident page. An item that already links to an issue, such as one Halon opened, never gets a second.

## Ask for an issue

Unless the setting is **Never**, an item that has no issue and is not done offers **Create issue**:

- On the incident page, next to the item's status.
- On the item's message in the incident channel.
- Over MCP, with `create_action_item_issue`. Halon can use it too.

The item says **Firefight is opening its issue** until the link appears in place of the button. If the issue cannot be opened, the item still keeps its place and says why under it, for example when the tracker refused it, when it is waiting for someone to approve it, or when an approver declined it. The button then reads **Try the issue again**. If Firefight restarted while it was opening the issue, the item asks you to check the tracker before you try again, since the issue may already be there.

## Send the tracker's changes to Firefight

How changes made in the tracker reach Firefight depends on the connection, and the setting says which applies once you save.

With Linear, changes come back through Firefight's own app, and the setting says there is nothing to set up.

With the Jira app connection, Firefight registers the webhook itself when you save, and the setting says so. Choosing another tracker, or removing the connection, removes the webhook too. If the tracker refuses to register it, the setting shows its reason.

With a Jira connection through Atlassian's own server, the setting shows an address that belongs to your workspace alone, with the steps to follow. In Jira, open **Settings**, then **System**, then **WebHooks**, and choose **Create a WebHook**. Paste the address as its URL, and tick **updated** and **deleted** under issue related events. Choose **Generate secret** and copy the secret before you create the webhook.

Paste the secret into the field under the steps and press **Save changes**. Until you do, the setting says that changes made in the tracker do not reach Firefight. Firefight accepts a change only when the tracker signed it, and the secret is never shown again. Paste a new one to replace it.

## What stays in step

| In Firefight | In the tracker |
|---|---|
| Picking up an item, or handing it to someone | The issue moves to a started state and is assigned to that person. |
| Marking an item done | The issue moves to a completed state. |
| Reopening an item | The issue moves back to a started state, or a not started one when nobody holds the item. |
| Unassigning an item | The issue is unassigned. |
| Renaming an item | The issue takes the new title. |

| In the tracker | In Firefight |
|---|---|
| The issue is completed or canceled | The item is marked done, and the channel hears about it. |
| The issue is reopened | The item reopens. |
| The issue is assigned to someone else | The item is handed to them. |
| The issue is unassigned | The item is unassigned and back to open. |
| The issue is renamed | The item takes the new title. |

Renaming, reopening and unassigning are in each item's menu on the incident page, on its message in Slack, over the API and over MCP. See [Running an incident from the dashboard](https://firefight.app/docs/incidents/running-from-the-dashboard.md).

People are matched by email. When the tracker has no account with the person's email, the issue's assignee is left as it was, and the item says so. The same goes the other way, for a tracker account with no Firefight member behind it. Jira leaves out the email of someone whose profile hides it, which counts as no match.

A status follows the tracker's own kinds of state. In Linear, a completed or canceled issue counts as done, and in Jira, any status in the done category does.

Every change made either way is in **Gateway → Activity**, under the **Issue sync** source and Firefight issue sync. Registering or removing the tracker's webhook is listed there too, under whoever saved the settings.

## Edge cases

- **The issue was deleted or archived.** The item keeps its link, stops being kept in step, and says why.
- **The issue moved to another team or project.** Firefight follows it under its new key.
- **The connection was removed or switched off.** No issues are opened, and the setting says what to fix.
- **You choose a different tracker.** Items linked to the old one keep their links but are no longer kept in step.
- **A change arrives late.** A change older than the last one made to the same field, on either side, is ignored, so the tracker never undoes something you just did.

You can also change these settings from an agent with `update_workspace_settings`, using `issue_tracker`, `issue_creation`, `issue_tracker_target` and `issue_webhook_secret`.