Linear Guide for Developers is a step‑by‑step reference that helps you move from zero to daily use of Linear. You will learn the core concepts, set up your workspace, master the main workflows, explore advanced patterns, and avoid the most common mistakes. Follow the guide and start tracking work faster than with traditional tools.
Linear structures work around three main objects: Issues, Projects, and Cycles. An Issue represents a single piece of work. Projects group related issues, while Cycles are time‑boxed sprints. The UI shows a left‑hand navigation pane, a central board, and a right‑hand detail pane. All actions are keyboard‑first, aiming for speed.
Issues have a title, description (Markdown), status, priority, and assignee. You can add labels, estimate points, and link pull requests. The default statuses are Backlog, Todo, In Progress, and Done.
Projects are containers for issues. They can be hierarchical (parent/child) and have custom fields. A typical setup includes a “Product” project for customer‑facing work and an “Infrastructure” project for internal tooling.
Cycles run for a fixed length (usually two weeks). When you start a Cycle, Linear automatically moves issues from Backlog to Todo based on priority and estimate. The Cycle view shows progress bars, velocity, and burndown.
Getting Linear ready for a development team takes less than 30 minutes. Follow these steps:
Visit linear.app and sign up with your work email. Choose the “Essentials” plan if you want the cheapest paid tier; the free tier is limited to 5 active users.
In Settings → Team, click “Invite”. Enter email addresses or import from Slack. Each member receives an invite link that expires after 7 days.
Navigate to Settings → Integrations → GitHub (or GitLab, Bitbucket). Click “Connect”, select the organization, and grant read/write permissions. After linking, every PR will appear as a comment on the linked issue.
Create a “Product” project and an “Infrastructure” project. Use the “Add Custom Field” button to add a “Customer Impact” dropdown (Low, Medium, High). This field helps prioritize work during sprint planning.
Go to Settings → Cycles. Set the default length to 14 days, start day to Monday, and enable “Auto‑close completed issues”. This matches most agile teams.
These are the actions you will repeat daily.
Use drag‑and‑drop or keyboard shortcuts: t to move to Todo, i for In Progress, d for Done. When an issue reaches Done, Linear automatically adds a “Closed” timestamp.
In a PR description, add “Fixes #123” where 123 is the Linear issue number. After merging, Linear updates the issue status to Done (if configured).
Beyond the basics, teams often need custom automation and reporting.
Linear’s built‑in automation lets you trigger actions on status changes. Example: When an issue moves to “In Progress”, automatically add the label “dev”. Go to Settings → Automation → New Rule, choose “When status changes to In Progress”, then “Add label dev”.
The GraphQL API can update many issues at once. Below is a sample curl command that sets the “Customer Impact” field to “High” for all issues in the “Product” project that have the label “urgent”.
curl -X POST https://api.linear.app/graphql \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"query":"mutation Update($ids:[ID!]!){issuesUpdate(ids:$ids,input:{customFields:{customerImpact:\"High\"}}){success}}","variables":{"ids":["issueId1","issueId2"]}}'
Replace YOUR_API_KEY with a token generated in Settings → API.
Create a custom View that shows all “High” impact issues, sorted by estimate. Click “Views → New View”, set filters, and save. Share the view link with stakeholders for live reporting.
Avoid these traps to keep your Linear workspace clean.
Many teams skip custom fields and rely on labels alone. Labels are harder to query via API. Define fields like “Severity” or “Release” early.
Adding dozens of tags per issue makes filtering noisy. Limit tags to 3 per issue and use hierarchical projects for broader categories.
Starting a Cycle without a point cap leads to over‑commitment. Use the “Capacity” field in Cycle settings to enforce a realistic limit.
If a PR isn’t linked, Linear can’t auto‑close the issue. Enforce a commit‑message policy that includes “Fixes #ISSUE”.
Linear’s API allows 60 requests per minute per token. Batch updates instead of firing a request per issue.
The table below compares Linear with two popular tools: Jira Software and Asana. Numbers reflect the November 2024 pricing and feature sets.
| Feature | Linear (Essentials) | Jira Software (Standard) | Asana Premium |
|---|---|---|---|
| Base price per user | $8/mo | $7.75/mo | $10.99/mo |
| API rate limit | 60/min | 100/min | 50/min |
| Keyboard‑first UI | Yes | No | No |
| Built‑in cycles | Yes | Via add‑on | No |
| Custom fields | Unlimited | Limited (10) | Limited (5) |
| Integration with GitHub | Native | Via Marketplace | Via Zapier |
| Export to CSV | Yes | Yes | Yes |
Linear is a modern issue tracking and project management tool built for software teams. It combines a clean UI with fast APIs.
Go to Settings → Integrations → GitHub, click Connect, select your repository, and grant access. Linear will sync PRs and branches automatically.
Yes. Linear includes cycle planning, sprint velocity, and burndown charts. Create a Cycle, assign issues, and track progress in real time.
Skipping the custom workflow setup, ignoring the API rate limits, and over‑using tags without a naming convention cause confusion.
Linear starts at $8 per user per month for the Essentials plan, while Jira Software starts at $7.75 per user per month but adds extra cost for advanced reporting.
Linear Guide for Developers gives you a clear path from installation to advanced automation. Follow the steps, avoid the mistakes, and your team will ship faster with fewer blockers.