Create Linear issues from workflows

When feedback needs your product or engineering team, a workflow can open a Linear issue for it — in the team you choose, with a title, a description and a priority built from what Polzy knows. If the workflow also created a Polzy action, the action follows the issue and closes itself once the issue is done or cancelled. At the end of this guide you will have Linear connected and a workflow opening issues.

Before you start

You need:

• A workspace on Business, and the Admin role in it.
• Integrations and Workflows switched on for the workspace, under Settings → General → What this workspace does.
• A Linear account that can create issues in the teams you will use. Issues are created as this account, so a dedicated one keeps them from being tied to one person.
• A personal API key for that account (below).

Create a personal API key

1. In Linear, open Settings → Account → Security & access.
2. Under Personal API keys, choose New key and name it Polzy.
3. Give it full access, or at least permission to read and create issues, and access to the teams Polzy should reach.
4. Copy the key. It starts with lin_api_.

If Linear does not let you create a key, a Linear admin may have turned member API keys off under Settings → Administration → API. Linear explains keys in Linear: API and webhooks.

Connect Linear to Polzy

1. In the sidebar, under Automate, open Integrations and choose the Available tab.
2. Find Linear and choose Connect.
3. Paste the key into Personal API key.
4. Choose Test connection. Polzy answers Connected as and the account's name.
5. Choose Connect.

Integration

Connect Linear

Keys are encrypted and only used on your behalf.

1 of 1 required

Credentials

Personal API keyRequired

In Linear, Settings → Account → Security & access → Personal API keys → New key.

Connected as Amara Okafor

Encrypted at restCancelTest connectionConnect

The key is stored encrypted. Once connected, Linear's row under Integrations offers Configure scope to replace the key, and Manage for its page.

Open an issue from a workflow

1. Open Workflows and the workflow, or start a new one.
2. Under Connectors in Installed steps, drag Create a Linear issue · Linear onto the canvas, after the step it should follow. A row with a lock means Linear is not connected yet, or needs attention.
3. Under Team, choose the team. The list shows every team the key can see, by name and key.
4. Write the Title, up to 255 characters. Type {{ to insert a value from the run, such as the action's title.
5. If you like, write a Description.
6. Choose a Priority: No priority, Urgent, High, Medium or Low.

Installed steps

Drag onto the canvas, or click to add

Connectors

Create a Jira issue · Jira

Create a Linear issue · Linear

Create an Asana task · Asana

Create a Linear issue · LinearConnector action

Connector

Linear

Action

Create a Linear issue

Details

TeamRequired

Customer Success (CS)

TitleRequired

Description

Priority

High

The step leaves the issue's identifier, such as CS-142, as {{connector.issueKey}} and its address as {{connector.url}}. A Test run walks the workflow without opening the issue; only a real run creates one. Workflows explains triggers and steps.

Close the action when the issue is done

When Create a Linear issue runs after Create action item in the same workflow run, the issue is linked to that action:

• Tracked in. The action's panel shows the issue's identifier, linked to Linear, and the state Linear last reported.
• Closed by Linear. Polzy asks Linear about the issue at most every 10 minutes. When it is completed — or cancelled, since the work will not happen there — the action moves to Done.
• Status only. Comments and other changes stay in Linear. An action closed in Polzy first is not asked about again.

What Polzy sends to Linear

Only what the step says: the team, the title, the description and the priority, with the values you insert. Nothing else about the answer or the person leaves Polzy. An anonymous answer has no person, so values such as the respondent's email are empty; what someone wrote is sent only once it has been read for safety. Single answers are not held back by the privacy floor, so think about who can read the team's issues before you put people's own words in one.

Troubleshooting

• Linear refused the credentials (401). The key is wrong, or was revoked. Make a new one, choose Configure scope on Linear's row under Integrations, paste it, and Save. A run that meets this marks Linear Needs attention.
• Linear: followed by Linear's own words (in a run). Linear refused the request — often because the key has no access to that team, or may not create issues. Check the key's permissions.
• Linear did not create the issue. Linear answered without an issue. Run the workflow again; if it keeps happening, check the team still exists.
• This step names no team or The issue has no title. Fill in the step's Team and Title.
• The Team list is a plain box. The key sees no teams, or Linear could not be reached.
• The action does not close. The Linear step did not run after Create action item in the same run, the issue is neither completed nor cancelled, or the connection needs attention — checks pause until it is fixed.

Good to know

• One connection, every team. Each step picks its team from what the key can see.
• Who is the creator? The account the key belongs to.
• Can a step open the same issue twice? No. A step that is run again after a crash reuses what it created the first time.

Useful links

• Linear: API and webhooks