Skip to content

Issue tracking

Linear

Create a Linear issue from a build or a screenshot, with the build link and the diff.

The Linear integration adds a Create issue button to the build review. It files an issue in the Linear team you chose for the project, with the build link, the branch, who rejected the changes and why, and a link to the diff image. The issue then shows on the build.

You get Where
A Create issue button The build review header, for the selected screenshot or the whole build
The issue key (for example ENG-123) On the build, and in a Created ENG-123 toast

An owner or admin of the workspace does this.

Open Workspace settings › Integrations › Add integration › Linear.

  1. Create an API key in Linear. Use a personal key: Settings › Account › Security and access.
  2. Paste it into CirCI. Use the API key field (lin_api_…) and connect. CirCI asks Linear who the key belongs to; a key Linear rejects fails with a message.

The key is stored encrypted and never shown again. Issues are created as the person who owns the key. If Linear later rejects the key, the integration is flagged as needing attention with the reason.

On the Linear integration's page, choose a Linear Team for each project. A project without a team has no Create issue button. A project maps to one Linear connection at a time.

When a project has a tracker mapped, the build review header shows Create issue. It acts on the screenshot you have selected, or on the whole build when none is selected.

The Create issue dialog has:

  • a Tracker switch, only when the project has both Linear and Jira,
  • a Title, pre-filled as Visual regression: <screenshot> in build #<number> (or Visual regression in build #<number> for a whole build), up to 250 characters,
  • a read-only Description preview.

The description CirCI sends says what changed, then lists the branch, pull request number, short commit, author, who rejected the build and their reason when there is one, a link to the build (to the screenshot when one is selected) and the diff image address. In Linear the diff image appears in the description and is also attached to the issue. If the attachment fails, the issue is still created with the image in its description.

When Linear answers, CirCI records the link (for example ENG-123) on the build and shows a Created ENG-123 toast. If Linear fails, the dialog shows the error and nothing is recorded. The issue links back to the build.

What you see Why, and what to do
There's no Create issue button The project has no Linear team mapped. Choose a Team on the integration's page
Connect fails with a message Linear rejected the key. Create a new personal API key
The dialog shows an error from Linear Nothing was recorded. Fix what the message says (for example a deleted team) and try again
The integration shows needs attention Linear rejected the key later. Connect again with a new key
  • Status sync. CirCI doesn't read an issue's state back from Linear, and doesn't close issues when a build is approved. The link on the build is all it keeps.
  • Choosing labels, priority or assignee in the dialog.
  • Creating issues automatically. Every issue is made by a person pressing the button.

Not yet verified against Linear.