Connect Linear

After this guide, a Linear issue that gets the Issue implementer's label becomes a plan, the code and a pull request. The agents comment on the Linear issue to say so: when they start, with the plan, with the pull request and when it is merged.

Who can do it:

• The Linear key: a workspace admin or owner for every product, or a person who may change the product's own keys and tools.
• The Linear team key and the webhook: a workspace admin or owner, or a person who may change everything in that product.

See Roles.

Before you start

You need:

• A Linear workspace, and permission to make an API key and a webhook in it. Webhooks are in Linear's settings under API, for workspace admins.
• A Linear account that can comment on the issues of your team. Its personal API key is the key you give us.
• The Issue implementer turned on for the product. See Choose what starts by itself.

Step 1: add the Linear key

1. In Linear, open Settings → Security & access, and make a personal API key. Copy it. It starts with lin_api_.
2. Open Settings → Integrations.
3. In the group Where requests come from, press Connect on the row Linear.
4. Paste the key into the field API key.
5. Under Use it for, choose every product, or one product.
6. Press Save and test.

Step 2: name the Linear team

The team key is the short code in front of the number of an issue. In ENG-12, the team key is ENG.

1. Open the product's settings: Settings → Products, then Settings on the product's row.
2. Open Technical settings at the end of the page.
3. Under Linear, type the team key in Linear team key, such as ENG.
4. Press Save in the bar at the bottom of the window.

Step 3: make the webhook

A webhook tells the agents at once when a Linear issue is created or changed. Linear signs each message with a secret, and we check that signature. So a message that is not from your Linear webhook does nothing.

1. In the product's Technical settings, find Linear webhook. It shows once the team key is saved.
2. Press Save the Linear webhook. The page shows a URL, and a Secret that we made. The page shows the secret once.
3. In Linear, open Settings → API → Webhooks → New webhook. Paste the URL. Tick Issues. Save the webhook in Linear.
4. Linear shows a signing secret for the webhook. Paste it into Secret from Linear (optional) on our page, and press Save the Linear webhook again. If Linear lets you choose the secret yourself, you can use the secret we made instead.

The webhook shows set when a secret is saved. A new secret replaces the old one, so paste the new secret into Linear too, or the other way round.

Step 4: give an issue the label

In Linear, add the Issue implementer's label to an issue of your team. The label is agent:implement, unless you changed Label that starts it in the Issue implementer's options. Make the label in Linear first.

What you see when it worked

• A new suggestion appears under Suggestions, for the Linear issue. The agents start the plan and the code at once, because the label is your yes. Nothing goes on your product until the pull request is merged.
• The agents comment on the Linear issue when they start, with the plan, with the pull request and when it is merged.
• The webhook shows set in the product's settings.

More

• Integrations: every integration and where its key can be.
• Approve a suggestion: what to do with the pull request.
• When something does not work.