Linear

With Linear as a workspace’s tracker, Limn links each pull request to its Linear issues, reads those issues, and shows each team’s active cycle on This Sprint. It reads with a personal API key you save in Settings, and it never changes anything in Linear.

#What you need

• Your Linear workspace’s address, for example https://linear.app/acme.
• A personal API key. Create one in Linear under Settings → Security & access. It starts with lin_api_. Read access is enough. See Linear’s API documentation.
• Optional, but useful: Linear’s GitHub integration, so Linear itself attaches pull requests to issues.

#Set it up

1. Open Settings → Integrations. Under Issue tracker, set Provider to Linear.
2. Type the Workspace URL.
3. Optional: type your Team keys, comma-separated, for example ENG, OPS, and choose Where to look. Without team keys only the pull request title is searched for keys.
4. Save. The Linear API key block appears.
5. Paste your Personal API key, save, and press Check connection. The check names the Linear workspace the key belongs to.

#How pull requests link to issues

1. First, the issues Linear’s GitHub integration attached the pull request to. Linear sees the branch, the title, “Fixes ENG-123” in the description and links made in Linear.
2. Then, keys like ENG-123 in the title and, with team keys set, the branch name.

Both count. Without the integration, linking by key still works. To add an issue by hand, paste its link or key in the Story check’s Add tickets.

#What Limn reads

• For each linked issue: the identifier, title, description, state, assignee, project name, sub-issues, the issues blocking it, the created and completed dates, and the newest 20 comments.
• Acceptance criteria: the sub-issues (completed ones ticked, cancelled ones left out), else a task list in the description, else an “Acceptance criteria” heading.
• Open points: an “Open points” or “Open questions” section of the description.
• For This Sprint: each team’s active cycle, with its dates.

Linear has no issue types, so story checks and settings treat every issue alike.

How often Limn reads

An open pull request’s issues are read when it arrives and about every 30 minutes; its Linear links are checked about every 30 minutes too. The cycle is read about every 20 minutes while This Sprint is in use. Limn tracks Linear’s rate limit for your key and waits before it gets close, so you never see a limit error. A workspace with 100 open pull requests stays far inside the limit.

#What Limn writes

One thing, only when you pick it: the assignee. In a ticket’s story view, the assignee is a menu of the active members of the issue’s team, and Unassigned. The change is made with the saved Linear key, so it shows as made by the key’s owner, and the key needs write access. Limn does not change states, cycles or comments.

#Troubleshooting

Where the key is kept: Data and storage.