# Linear

SureCloud connects to Linear to retrieve issues, project status, and team workflow data. This allows SureCloud to track the progress of remediation tasks, security findings, and compliance action items managed in Linear — confirming that identified risks are being actively tracked and resolved within defined timeframes.

## Authentication and setup

Linear supports OAuth 2.0 for third-party integrations. SureCloud connects via the Linear OAuth flow.

{% hint style="info" %}
SureCloud uses OAuth 2.0 for this integration. No credentials are stored — access is maintained via a refresh token that SureCloud rotates automatically.
{% endhint %}

{% stepper %}
{% step %}
**Initiate the connection in SureCloud**

Navigate to **SureCloud → Integrations → Linear → Connect** and click **Authorise with Linear**. SureCloud will redirect you to the Linear authorisation page.
{% endstep %}

{% step %}
**Approve access in Linear**

Log in to Linear with a workspace Admin or Member account. Review the requested scopes and click **Authorise** to grant SureCloud read access to your Linear workspace.
{% endstep %}

{% step %}
**Return to SureCloud**

After authorisation, you will be redirected back to SureCloud with the integration status updated to **Connected**. Click **Test Connection** to confirm data is accessible.
{% endstep %}
{% endstepper %}

## Endpoints

Linear exposes its data via a single GraphQL endpoint at `https://api.linear.app/graphql`. SureCloud uses the following queries:

| API Call                                 | Use Case                                                                    |
| ---------------------------------------- | --------------------------------------------------------------------------- |
| `POST /graphql` — `issues` query         | Retrieve issues including title, status, assignee, priority, and due date   |
| `POST /graphql` — `teams` query          | Enumerate teams to scope remediation tracking by engineering team           |
| `POST /graphql` — `projects` query       | Retrieve project status to track compliance initiative progress             |
| `POST /graphql` — `workflowStates` query | Retrieve workflow state definitions (e.g. Todo, In Progress, Done) per team |
| `POST /graphql` — `users` query          | Enumerate workspace members and their roles                                 |

## Pagination

Linear GraphQL queries use cursor-based pagination. SureCloud passes `first` (page size) and `after` (cursor) arguments and uses the `pageInfo.endCursor` from each response as the `after` value in the next request, continuing until `pageInfo.hasNextPage` is `false`.

```json
POST /graphql
{
  "query": "query issues($after: String) { issues(first: 250, after: $after) { nodes { id title state { name } } pageInfo { hasNextPage endCursor } } }",
  "variables": { "after": "<value_from_previous_response>" }
}
```

## Required permissions / scopes

SureCloud requests the following OAuth scopes from Linear:

| Scope  | Purpose                                                            |
| ------ | ------------------------------------------------------------------ |
| `read` | Read access to issues, projects, teams, workflow states, and users |

No write permissions are requested.

## Polling frequency

| Data Type                             | Interval       |
| ------------------------------------- | -------------- |
| Issues and their status               | Every 6 hours  |
| Projects and milestones               | Every 24 hours |
| Team and workflow state configuration | Every 24 hours |
| Workspace members                     | Every 24 hours |

## Troubleshooting

<details>

<summary>OAuth authorisation fails or returns an error on redirect</summary>

This can occur if the authorising Linear account does not have sufficient workspace permissions, or if a browser extension is blocking the redirect. Try the OAuth flow in a private browser window. Ensure the account used has at least Member-level access to the Linear workspace.

</details>

<details>

<summary>Issues from a specific team are missing in SureCloud</summary>

Linear's OAuth token provides access scoped to the workspace of the authorising user. If your organisation uses multiple Linear workspaces, only the workspace associated with the authorising account will be accessible. For multi-workspace setups, contact SureCloud Support to configure additional connections.

</details>

<details>

<summary>Completed or cancelled issues are not appearing in SureCloud</summary>

SureCloud collects issues across all workflow states, including completed and cancelled. If completed issues are missing, verify that the `workflowStates` query is returning terminal states for the relevant team, and that the issue was updated within the SureCloud lookback window.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/linear.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.