# Linear

Create, find, update and archive Linear issues, comment on them, link and relate them, manage projects and project updates, and look up teams, people, statuses, labels and cycles.

## Connect Linear

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `linear` and choose **Linear**.
3. Choose **Sign in with Linear**.
4. Press **Sign in with Linear** at the bottom of the sheet, then choose your account in Linear’s window and allow access.

Or choose **Paste your personal API key**, paste it, and press **Test and save**. It stays until someone deletes it.

Sign in with Linear, or paste a personal API key (Linear → Settings → Security & access → Personal API keys).

**What if it says “Sign-in isn’t set up here yet”?**

Signing in with Linear needs a Linear app on this installation, and it has none yet. Until it is set up, **Paste your personal API key** works without it.

**On Cloud:** The sheet says “It’s set up once for everyone who uses this service, not by an organization.”

**Self-hosted:** An admin of the installation sees **Set up Linear sign-in** instead, and sets it up once for everyone. Everyone else sees who to ask.

1. Create an app in Linear’s developer settings ([Linear’s guide](https://linear.app/settings/account/security)).
2. In GoRunner, copy the **Redirect address to add in Linear’s developer settings**, and add it to the app.
3. Paste the **Client ID** and **Client secret**, then press **Save and sign in**.

[Set up a sign-in app](https://docs.gorunner.io/self-host/oauth-apps#other-providers)

**Can I use my own Linear app?**

Yes. In the sheet, open **Use your own Linear app** and paste its **Client ID** and **Client secret**. Add the redirect address it shows to your app first. The connection then signs in through your app instead of the installation’s.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Do things in Linear

Add a **Linear** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Issue](https://docs.gorunner.io/apps/linear#fields-f-issue): Create · Get · Get Many · Search · Update · Add Link · Archive · Unarchive · Delete
- [Comment](https://docs.gorunner.io/apps/linear#fields-f-comment): Add Comment · Get Many · Update · Delete
- [Project](https://docs.gorunner.io/apps/linear#fields-f-project): Create · Get · Get Many · Update · Delete
- [Project Update](https://docs.gorunner.io/apps/linear#fields-f-projectupdate): Create · Get Many
- [Issue Relation](https://docs.gorunner.io/apps/linear#fields-f-issuerelation): Create · Get Many · Delete
- [Team](https://docs.gorunner.io/apps/linear#fields-f-team): Get · Get Many
- [User](https://docs.gorunner.io/apps/linear#fields-f-user): Get · Get Many
- [Status](https://docs.gorunner.io/apps/linear#fields-f-workflowstate): Get Many
- [Label](https://docs.gorunner.io/apps/linear#fields-f-label): Get Many
- [Cycle](https://docs.gorunner.io/apps/linear#fields-f-cycle): Get Many

To start a workflow from Linear, use [Linear Trigger](https://docs.gorunner.io/apps/linear-trigger). It needs a connection of its own.

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Linear can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Linear says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Linear is `pieceId: "linear"` with `actionId: "linear"`, set by `resource` and an `operation_…` field, such as `operation_comment`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Linear › Issue

### Create

- **Team · Required**: The team the issue belongs to.
- **Title · Required**: The issue's title.
- **Description · Optional**: The issue's description, in Markdown.
- **Status · Optional**: The issue's status. On create, empty puts the issue in the team's first backlog state (or Triage when the team uses it).
- **Assignee · Optional**: The person to assign it to.
- **Priority · Optional**: Urgent, High, Medium, Low or No priority. Empty leaves it as it is. Options: Urgent, High, Medium, Low, No priority.
- **Labels · Optional**: Labels to set. On update they replace the issue's labels; use Other Fields addedLabelIds or removedLabelIds to add or remove some.
- **Project · Optional**: The project the issue belongs to.
- **Cycle · Optional**: The cycle (sprint) to put the issue in.
- **Due Date · Optional**: A date, YYYY-MM-DD.
- **Estimate · Optional**: Points, on the team's estimate scale.
- **Parent Issue · Optional**: Make this a sub-issue of another issue: the parent's UUID.
- **Other Fields · Optional**: More issue fields as a JSON object, by Linear's names.

### Get, Archive, Unarchive and Delete

- **Issue · Required**: The issue to read or change.

### Get Many

- **Team · Optional**: Only this team's. Empty lists every team's.
- **Filter · Optional**: A Linear issue filter, such as {"state": {"type": {"eq": "started"}}, "assignee": {"email": {"eq": "ada@acme.com"}}, "priority": {"lte": 2}}. Empty keeps every issue.
- **Order By · Optional**: Newest first by this time. On Search, empty orders by relevance. Options: Created, Last updated.
- **Include Archived · Optional**: Off by default.
- **Return All · Optional**: Read every issue, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many issues to return (1–1000). Default: 50. Shows when **Return All** is off.

### Search

- **Search Text · Required**: Words to find in issues' titles and descriptions (ranked by relevance).
- **Search Comments Too · Optional**: Off by default.
- **Team · Optional**: Only this team's. Empty lists every team's.
- **Filter · Optional**: A Linear issue filter, such as {"state": {"type": {"eq": "started"}}, "assignee": {"email": {"eq": "ada@acme.com"}}, "priority": {"lte": 2}}. Empty keeps every issue.
- **Order By · Optional**: Newest first by this time. On Search, empty orders by relevance. Options: Created, Last updated.
- **Include Archived · Optional**: Off by default.
- **Return All · Optional**: Read every issue, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many issues to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Issue · Required**: The issue to read or change.
- **Title · Optional**: A new title. Empty leaves it as it is.
- **Description · Optional**: The issue's description, in Markdown.
- **Status · Optional**: The issue's status. On create, empty puts the issue in the team's first backlog state (or Triage when the team uses it).
- **Assignee · Optional**: The person to assign it to.
- **Priority · Optional**: Urgent, High, Medium, Low or No priority. Empty leaves it as it is. Options: Urgent, High, Medium, Low, No priority.
- **Labels · Optional**: Labels to set. On update they replace the issue's labels; use Other Fields addedLabelIds or removedLabelIds to add or remove some.
- **Project · Optional**: The project the issue belongs to.
- **Cycle · Optional**: The cycle (sprint) to put the issue in.
- **Due Date · Optional**: A date, YYYY-MM-DD.
- **Estimate · Optional**: Points, on the team's estimate scale.
- **Parent Issue · Optional**: Make this a sub-issue of another issue: the parent's UUID.
- **Other Fields · Optional**: More issue fields to change as a JSON object, by Linear's names, such as {"teamId": "…"} to move the issue.

### Add Link

- **Issue · Required**: The issue to read or change.
- **Link · Required**: The URL to attach to the issue. Linear shows known services (GitHub, Figma, Sentry …) with their own preview.
- **Link Title · Optional**: The title the link shows. Empty lets Linear name it.

### Linear › Comment

### Add Comment

- **Issue · Required**: The issue to comment on, or whose comments to read.
- **Comment · Required**: The comment, in Markdown.
- **Reply To · Optional**: To reply in a thread: the id of the comment that starts it.

### Get Many

- **Issue · Required**: The issue to comment on, or whose comments to read.
- **Return All · Optional**: Read every comment, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many comments to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Comment ID · Required**: The comment's id (the id a comment step or Get Many returns).
- **Comment · Required**: The comment, in Markdown.

### Delete

- **Comment ID · Required**: The comment's id (the id a comment step or Get Many returns).

### Linear › Project

### Create

- **Name · Required**: The project's name.
- **Teams · Required**: The teams working on the project.
- **Summary · Optional**: A one-line summary (at most 255 characters).
- **Description · Optional**: The project's description, in Markdown.
- **Lead · Optional**: The person leading the project.
- **Start Date · Optional**: YYYY-MM-DD.
- **Target Date · Optional**: YYYY-MM-DD.
- **Priority · Optional**: Empty leaves it as it is. Options: Urgent, High, Medium, Low, No priority.
- **Other Fields · Optional**: More project fields as a JSON object, by Linear's names.

### Get and Delete

- **Project · Required**: The project to read or change.

### Get Many

- **Filter · Optional**: A Linear project filter, such as {"status": {"type": {"eq": "started"}}} or {"name": {"containsIgnoreCase": "launch"}}. Empty keeps every project.
- **Include Archived · Optional**: Off by default.
- **Return All · Optional**: Read every project, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many projects to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Project · Required**: The project to read or change.
- **Name · Optional**: A new name. Empty leaves it as it is.
- **Summary · Optional**: A one-line summary (at most 255 characters).
- **Description · Optional**: The project's description, in Markdown.
- **Lead · Optional**: The person leading the project.
- **Start Date · Optional**: YYYY-MM-DD.
- **Target Date · Optional**: YYYY-MM-DD.
- **Priority · Optional**: Empty leaves it as it is. Options: Urgent, High, Medium, Low, No priority.
- **Other Fields · Optional**: More project fields to change as a JSON object, by Linear's names.

### Linear › Project Update

### Create

- **Project · Required**: The project the update is about.
- **Update · Required**: The update, in Markdown.
- **Health · Optional**: How the project is doing. Empty keeps the project's last health. Options: On track, At risk, Off track.

### Get Many

- **Project · Required**: The project the update is about.
- **Return All · Optional**: Read every project update, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many project updates to return (1–1000). Default: 50. Shows when **Return All** is off.

### Linear › Issue Relation

### Create

- **Issue · Required**: The issue the relation starts from, or whose relations to list.
- **Relation · Required**: Options: Blocks the other issue, Is blocked by the other issue, Is a duplicate of the other issue, Is related to the other issue. Default: Blocks the other issue.
- **Other Issue · Required**: The other issue.

### Get Many

- **Issue · Required**: The issue the relation starts from, or whose relations to list.
- **Return All · Optional**: Read every relation, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many relations to return (1–1000). Default: 50. Shows when **Return All** is off.

### Delete

- **Relation ID · Required**: The relation's id (Get Many returns it).

### Linear › Team

### Get

- **Team · Required**: The team to read.

### Get Many

- **Return All · Optional**: Read every team, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many teams to return (1–1000). Default: 50. Shows when **Return All** is off.

### Linear › User

### Get

- **User · Required**: The person to read; "me" is the signed-in user (or the API key's owner).

### Get Many

- **Include Suspended · Optional**: Also list people whose access was suspended. Off by default.
- **Return All · Optional**: Read every user, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many users to return (1–1000). Default: 50. Shows when **Return All** is off.

### Linear › Status

### Get Many

- **Team · Optional**: Only this team's. Empty lists every team's.
- **Return All · Optional**: Read every status, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many statuss to return (1–1000). Default: 50. Shows when **Return All** is off.

### Linear › Label

### Get Many

- **Team · Optional**: Only this team's. Empty lists every team's.
- **Return All · Optional**: Read every label, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many labels to return (1–1000). Default: 50. Shows when **Return All** is off.

### Linear › Cycle

### Get Many

- **Cycles · Optional**: Which cycles to list. Options: All, The active one, Upcoming, Past. Default: All.
- **Team · Optional**: Only this team's. Empty lists every team's.
- **Return All · Optional**: Read every cycle, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many cycles to return (1–1000). Default: 50. Shows when **Return All** is off.

Source: https://docs.gorunner.io/apps/linear