Bug tracking in Plane: Setup, workflows, and best practices

Most teams have a bug tracker. But very little of a bug’s history actually ends up there.

A problem may be reported by a customer, flagged by Support, detected by monitoring, or discovered by an AI agent testing or working in the codebase. The screenshot stays in one tool, customer context in another, and the fix in a pull request. The pull request merges, the Bug closes, and nobody checks whether the original problem has actually stopped.

Bug tracking takes a reported or detected problem from discovery to a verified resolution. Plane brings reports from people, systems, and agents into the same Bug type, where triage, customer context, code changes, and verification stay connected.

A merged pull request is not evidence that a bug is fixed. It is evidence that code changed.

This guide shows how to run the complete bug-tracking process in Plane, from discovery and triage to verification, reporting, and governance across teams.

Bug tracking vs issue tracking

The two terms are often used interchangeably, but they do not mean quite the same thing.

Issue tracking covers any unit of work, including tasks, requests, incidents, improvements, and Bugs. Bug tracking is narrower. It focuses on product behavior that differs from what was expected and includes a verification step that most other work does not need. Every Bug is an issue, but not every issue is a Bug.

An incident and a Bug can come from the same underlying problem, but they run on different clocks. The incident closes when service is restored. The Bug closes when the behavior that caused it has been fixed and verified.

For the wider workflow across every work type, see issue tracking workflow: definition, stages, and examples.

Define the Bug lifecycle

A Bug moves through four phases: report, triage, fix, and verify.

Plane organizes states into five groups: Backlog, Unstarted, Started, Completed, and Cancelled. You name the states inside each group, so the phases above become states your team actually reads.

One practical setup is Triage, Validated, In Progress, QA, Verified, Declined, and Duplicate.

This is a starting point, not a required workflow. A smaller team may combine Triage and Validated, while a team with a formal release process may add states such as Ready for QA or Ready for Release. What matters is keeping the fix and verification as separate events.

Set the states first

Go to Project Settings → States and name the states inside each group before you configure anything else. Every automation, workflow, and Dashboard below refers back to them.

Keep In Progress and QA separate. Once a fix is merged, the developer may be finished, but the Bug is not. QA gives that work somewhere to wait until someone has tested the original report and confirmed that the problem is gone.

Keep In Progress and QA separate. Once a fix is merged, the developer may be finished, but the Bug is not. QA gives that work somewhere to wait until someone has tested the original report and confirmed that the problem is gone.

Create and triage Bugs

Create a Bug work item type

Bugs move through a different process from Tasks and Feature Requests. They need to be reproduced, assessed for severity, connected to a fix, tested in the affected environment, and verified before they are closed.

Creating a separate Bug type gives that work its own structure. Fields such as severity, reproduction steps, expected and actual behavior, environment, and affected version appear only where they are relevant. It also makes Bugs easier to filter, triage, report on, and move through a dedicated workflow.

Every work item in Plane has a type. Task is the default, and custom work item types let you create a Bug type with the properties your team needs.

Go to Project settings → Work-Structure → Work item Types → Add work item type. Name it Bug, choose an icon and a color, then open the type and select Add new property.

Recommended properties:

Two more are worth adding once reports come from outside engineering:

Require severity and reproduction steps. Leave the rest optional.

Keep the required list short
A form with nine mandatory fields does not produce better reports. It produces fewer of them, filed as Tasks instead, and six months later your bug data is split across two work item types. Optional fields let the triage owner fill in what the reporter could not.

The type gives every Bug the right structure. The quality of the report still depends on what goes into those fields.

Triage before committing work

Triage is where a report either becomes planned work or leaves the queue. Follow the same basic checks each time:

• Confirm the reported behavior. Reproduce it before anything else happens to it.
• Check for existing Bugs. Search before a second record gets created for the same problem.
• Record the environment and affected version. These are the details that make a fix testable.
• Set severity and priority. Both, and they are not the same field.
• Add customer impact where the report ties to an account.
• Assign an owner.
• Move the Bug to Validated, Declined, or Duplicate.

Set severity before priority

Severity, customer impact, reach, and workaround describe the Bug. During triage, review these properties together and assign its Priority in Plane: Urgent, High, Medium, Low, or None.

Give the queue a named owner and a regular review schedule. Without both, Triage quickly becomes another backlog.

Where a report waits depends on how it arrived
Bugs created directly, whether in Plane, from a Slack message, synced from a repository, or generated by an alert, land in the Triage state you defined. Reports submitted through Intake stay in the Intake queue until someone accepts them, which is what keeps unreviewed submissions out of your project backlog.

For the full process around this decision, see the bug triage process.

What a good bug report looks like

A good report gives someone enough information to reproduce the problem without going back to the reporter.

• Write a specific title: Applying a promo code clears the cart on Safari 17, not Checkout is broken.
• Add numbered steps: Keep them short, specific, and easy to follow.
• Separate expected and actual behavior: This makes the difference clear during triage and verification.
• Name the environment: Include the release, browser, operating system, device, or deployment where the problem occurred.

A complete Bug might look like this:

• Title: Applying a promo code clears the cart on Safari 17
• Severity: Critical
• Steps to reproduce: Add two items, enter SPRING25, and select Apply
• Expected: The discount applies and both items remain in the cart
• Actual: The cart empties and the promo field resets
• Environment: Production, Safari 17, macOS 14.4
• Affected version: 4.12.0
• Customer impact: Two linked accounts
• Found by: Support

Not every detail has to be entered manually. Sentry can provide error and environment data, Intake can collect structured fields, Slack Thread Sync can preserve the original discussion, and AI agents can create Bugs with context from the tools and code they are working with.

Keep guesses about the cause, urgency language, and unrelated problems out of the report. They make Bugs harder to triage, deduplicate, and verify.

Collect reports from every source

Bugs rarely begin in the tracker. Bringing each source into the same Bug type gives the team one triage process instead of a different queue for every channel.

A few of these paths change how the report is handled.

Report bugs from Slack

Turn on Thread Sync when you create the Bug. Comments move between the Slack thread and the work item in both directions, keeping the original discussion, screenshots, and follow-up questions connected to the report.

Create a Bug work item from an existing Slack message using the message shortcut, or type /plane in the channel.

Collect bug reports through Intake

Intake accepts reports from people without a Plane account through a public form or project email address. Connect the form to the Bug type to collect details such as reproduction steps and environment upfront. Submissions wait in Intake until they are reviewed, so reporting stays easy without sending every submission straight into the backlog.

Sync Bugs from GitHub and GitLab

GitHub and GitLab keep repository issues connected to the Bugs tracked in Plane. Teams can decide which issues to sync, map repository states to Plane states, and choose whether updates move in one direction or both.

With bidirectional sync, changes to the title, description, state, assignees, labels, and comments stay aligned across both tools. Engineering can continue working from the repository while Product, Support, and QA follow the same Bug in Plane.

Only sync issues that need to enter the team’s bug-tracking process. This keeps routine repository activity out of the triage queue.

Label-based synchronization runs both ways. Add the plane label to a repository issue to create a work item, or add the repository label to a Plane work item to create an issue. Map genuine bugs to the Bug type. The label acts as a filter, keeping unrelated repository activity out of the project.

Turn Sentry errors into Bugs

The Sentry integration can create a Plane Bug when an error meets the conditions defined in a Sentry alert rule. The rule can also set properties such as priority and assignee, giving the Bug a clear starting point when it reaches triage.

Linked Sentry issues and Plane Bugs keep their resolution states in sync. Resolving the issue in Sentry updates the Bug in Plane, and moving the Bug to the mapped resolved state updates Sentry.

Define alert conditions around signals such as error frequency, affected environment, or failure rate. This helps the team capture errors that need action without creating a new Bug for every occurrence.

Create Bug reports with MCP and AI agents

The Plane MCP server lets AI tools create and update Bugs directly in Plane. Claude, Claude Code, ChatGPT, Codex, Cursor, VS Code, Windsurf, and Zed are supported, along with any client that has native remote MCP support. You need a workspace where you are a Member or Admin, and the server runs on self-hosted deployments as well as Plane Cloud.

An agent can turn the context it already has into a Bug, setting the title, description, work item type, priority, assignee, labels, and state as it creates the work item. Custom properties such as severity are set on the Bug once it exists, which is one additional step rather than a different capability.

For example, a coding agent that finds a failing authentication flow could act on a prompt like this:

Can you file a bug in Mobile App? Login times out on Safari 17.
Happens on the in-app webview when you sign in with SSO, spinner
just hangs and then errors out after about 30 seconds. Started
after the 4.12.1 rollout, few merchants have hit it. Chrome is fine.
High priority, tag it auth, assign to me.

MCP connectors work in the other direction. Connect a service such as GitHub, Sentry, Intercom, or PostHog from Workspace Settings → Integrations → Connectors, and Plane AI can read and act on data from it during a conversation, so the context behind a Bug comes from the tool that observed it rather than from someone retyping it.

The two routes are worth keeping straight:

• Plane MCP server: an external AI tool or agent creates and updates Bugs in Plane
• MCP connectors: Plane AI reads context from external tools while you work inside Plane

Agents act as the connected user, and workspace and project roles apply to every read and write. Keep newly created Bugs in Triage so a person confirms the report, checks for duplicates, and sets the final severity and priority before the team commits to the work.

Start tracking Bugs in one project
Set up the Bug type, the states, and one Intake form in a single project before rolling anything out. Get started free

Connect the fix and verify the result

Connect pull requests

Reference the work item identifier in the pull request title or description:

[WORK-ITEM-ID] Fix cart reset when applying a promo code

Brackets enable state automation. An unbracketed identifier creates the reference without changing the Bug's state, which is useful when a pull request touches a Bug it is not resolving.

Configure the mapping from Workspace settings → Integrations → GitHub → Pull Request Automation:

Map Merged to QA, not Verified. The code has changed, but someone still needs to test the result.

Control how Bugs move between states

Closing and verifying are two different events. A merge confirms that the code changed, not that the original problem is gone.

Workflows and Approvals control which state transitions are available, who can complete them, and which transitions require approval.

Configure the bug workflow from Project settings → Execution → Workflows. A workflow defines which state transitions exist and who is allowed to make them. Expand a state, select Add flow, and set:

• Via: Transition or Approval
• Move to: the destination state
• By: the members allowed to complete it

Restrict the final transition so only the people responsible for verification can reach Verified. Plane blocks transitions the workflow does not allow, so the gate holds without anyone policing it. For critical fixes and production releases, use Approval instead of Transition and set the destination on approval, the destination on rejection, and the approvers.

Verification brings the fix back to the original report. Follow the documented steps, test in the affected environment rather than whichever one is most convenient, and record the result on the Bug. Anyone opening it later should be able to see what was tested and who tested it.

If the fix passes, move the Bug to Verified. If it fails, return it to In Progress with the reason attached. The history then shows that the fix was tested and sent back, rather than quietly reopened.

The question at the end is not whether the pull request merged. It is whether the reported behavior stopped.

Monitor and report on bug health

Views and Dashboards answer different questions. Views show the team what needs attention now. Dashboards show leaders how the process is performing over time.

Create Views for active work

Views help teams return to the Bugs that need attention without rebuilding the same filters each time. Create focused Views for common triage, ownership, and verification checks, such as:

• Blocker and Critical Bugs still open
• Bugs without an owner
• Bugs waiting in QA
• Bugs open beyond the expected resolution time
• Bugs linked to a customer
• Bugs reopened after verification

Reopened Bugs are particularly useful to track. When a Bug returns after verification, the team needs to understand whether the test missed something, the fix was incomplete, or the same behavior returned for a different reason.

Build Dashboards for trends

Dashboards bring Bug data from multiple projects into one view, helping engineering and product leaders spot patterns that are difficult to see from individual work items.

A bug health Dashboard could track:

• Open Bugs by severity
• Bugs reported versus verified over time
• Average time from report to verification
• Time spent in Triage, In Progress, and QA
• Bugs by source, product area, or team
• Reopened Bugs
• Bugs affecting multiple customers

Pay particular attention to Bugs reported versus Bugs verified. If those lines keep moving apart, the team is accumulating unverified work regardless of how many Bugs it marks as closed.

Scale bug tracking across the organization

One team can manage its Bug type, states, and workflow from project settings. Across an engineering organization, those project-level configurations can quickly drift. Critical may mean a production outage to one team and a minor inconvenience to another, making cross-project reporting unreliable.

Workspace Governance moves the shared configuration from individual projects to the workspace level. Workspace Admins define the building blocks once, and projects use the same governed resources.

Govern bug tracking at the workspace level

For bug tracking, Workspace Governance can centralize:

• States: Define the shared states that Bugs move through, including Triage, In Progress, QA, and Verified.
• Work Item Types and properties: Create one Bug type with a common severity model and the properties every team must capture.
• Workflows and Approvals: Define how Bugs move between states, who can complete each transition, and where approval is required.
• Automations: Apply the same routing, assignment, and state-change rules across projects.

Plan Workspace Governance before enabling it

Enabling Workspace Governance is permanent. States, Work Item Types, Workflows, Automations, templates, and recurring work move to workspace management, and Project Admins can no longer create or edit them independently. Review the existing project configurations and pilot the shared Bug model before enabling governance across the workspace.

Projects reference this shared configuration rather than keeping separate copies. Workspace Admins manage changes, while Project Admins work within the options the workspace provides.

For the Bug workflow, Workspace Admins can decide how much flexibility projects retain:

• Any: Projects can choose any active workspace workflow for the Bug type.
• Constrained: Projects can choose from an approved set of Bug workflows.
• Required: Every project must follow the same Bug workflow.

A Required workflow is useful when every Bug must follow the same path from Triage to Verified. Constrained workflows give teams some flexibility while keeping them within an approved operating model.

Need a consistent Bug type, severity model, and workflow across every engineering team? Talk to our team about scaling bug tracking with Plane.

Move bug tracking from Jira or another tool

Jira is a mature issue tracker, but years of configuration can leave bug tracking spread across workflows, marketplace apps, and team-specific conventions. Plane brings the process into one connected system, from the first report to the verified fix.

Reports from Slack, Intake, GitHub, GitLab, Sentry, MCP, and AI agents all land in the same Bug type. Triage, development, pull requests, QA, approvals, and verification stay connected to that one work item instead of spreading across tools.

The structure is yours to set. Define Bug properties, states, workflows, and approval rules without forcing the same setup on every other kind of work. Views keep teams focused on the Bugs that need attention, and Dashboards track the trend across projects. As the organization grows past a single team, Workspace Governance keeps a shared Bug type, severity model, and workflow across every team. Workspace Admins set the standard, and projects work inside it instead of drifting apart.

None of this locks you into how Plane runs. Deploy it on Plane Cloud, self-hosted, or fully air-gapped, and the API and MCP server give internal tools and AI agents the same types, states, and permissions as everyone else.

Moving existing work does not mean starting over. Plane imports from Jira, Linear, Asana, ClickUp, and other tools, so teams bring their history with them into a more connected process.

For organizations reviewing their options ahead of the Jira Data Center transition, Plane's open letter to Jira Data Center customers covers the timeline and migration considerations.

Browse the importers

From report to verified fix

A bug tracker should do more than count how many records were closed. It should show whether a reported or detected problem reached the right team, received a decision, moved through a fix, and was verified where it occurred.

Plane keeps that path connected, whether the Bug begins with a customer, an alert, a repository, or an AI agent. The report, ownership, customer context, code changes, and verification remain part of the same process from discovery to resolution.

Start with one project, a clear Bug lifecycle, and a named triage owner. Add integrations, reporting, and shared governance as the process grows.

Start tracking Bugs in Plane

Frequently asked questions

1. How do you track bugs without a dedicated QA team?

Verification is a step, not a department. Where possible, assign it to someone who did not write the fix. On smaller teams, the reporter may be the best verifier. Keep a separate QA state and record what was tested, even when there is no QA team.

2. What do you do with a bug you cannot reproduce?

Record what was tested and ask the reporter for the missing environment, evidence, or reproduction details. If it remains unreproducible, move it to a clearly named Cancelled-group state rather than closing it as “not a bug.” Link similar reports using the Duplicate of relation, since several reports may eventually reveal the pattern.

3. What is the difference between a bug and a regression?

A regression is a bug in behavior that previously worked. It often receives closer attention because it points to a recent change and a gap in test coverage, but its priority should still reflect severity, reach, and available workarounds. Track it as a Bug with a label or property that identifies it as a regression.

4. What do you do when a bug is working as designed?

If the design is wrong, change the work item to a Feature Request and move it into the appropriate workflow. If the design is correct but the expectation was wrong, close the Bug with the reason recorded. Separating expected and actual behavior in the original report makes this decision easier.

5. Should customer-reported bugs be prioritized above internally found ones?

Not automatically. A customer report provides evidence of impact, but it does not determine severity or priority on its own. Consider how many customers are affected, which accounts are involved, whether a workaround exists, and how critical the affected path is.

6. Where do security vulnerabilities go?

Vulnerability reports should not enter an open bug queue. Track them in a restricted project with access limited through roles and permissions. The resulting fix can follow the Bug workflow once it is safe to describe more broadly.

7. Do you need a separate bug tracker from your project tracker?

Most teams do not need a separate tool if their project tracker supports Bug-specific properties, workflows, integrations, permissions, and reporting. Keeping Bugs with the rest of the product work also keeps the original report, code change, customer context, and verification record connected.

8. What is a healthy number of open bugs?

There is no useful universal benchmark. Compare Bugs reported with Bugs verified over the same period. If reports consistently outpace verification, the backlog is growing. Then look at age, severity, reopened Bugs, and time spent in each state to understand whether the remaining work is healthy or stuck.