# Connect Rat Things to Linear

Linear is a built-in Rat Things Connection. An agent can search and inspect issues, discover team
and workflow-state IDs, create or update issues, and add comments through a verified Linear
workspace account. Connections remain separate from the Agent configuration. Standard Sessions require explicitly
declared MCP or application-function tools to invoke these operations.

This guide sets up a deployment-owned Linear OAuth application, installs one workspace, and runs a
bounded Slack-to-Linear handoff. Rat Things uses Linear's app actor, so writes appear as the
installed application rather than impersonating the workspace admin who grants consent.

> This is currently a connected-service integration, not Linear-native Run ingress. Do not enable
> Agent session event webhooks or request `app:assignable` or `app:mentionable`: assigning or
> mentioning Rat Things inside Linear does not start a Run yet.

## What the built-in Connection can do

| Operation | Access | Purpose |
| --- | --- | --- |
| `linear.teams.list` | Read | List visible teams and their workflow states so later calls can use provider IDs |
| `linear.issues.search` | Read | Search issue text, optionally within one team |
| `linear.issues.get` | Read | Read one issue and the first page of up to 20 comments |
| `linear.issues.create` | Write | Create an issue in one team with a title and optional Markdown description |
| `linear.issues.update` | Write | Change an issue title, description, state, or assignee |
| `linear.comments.create` | Write | Add a Markdown comment to an issue |

The adapter sends fixed GraphQL documents only to `https://api.linear.app/graphql`. The model
cannot supply a query document, provider origin, OAuth scope, or credential. Linear provider
authority, the persistent Rat grant, the capability profile, and declared tool operation/resource
narrowing must all admit a call before the host credential broker reads the token.

## Before you start

You need:

- a deployed Rat Things AWS stack and an authenticated CLI;
- workspace-admin access in the Linear workspace that will install the app;
- permission to create and read one AWS Secrets Manager secret in the stack Region; and
- the same Terraform checkout and variables used for that deployment.

Linear's current OAuth flow supports PKCE and rotating refresh tokens. Rat's callback already
implements one-time state, S256 PKCE, code exchange, refresh fencing, and identity-preserving
reconnection. The provider details used here come from Linear's
[OAuth 2.0 guide](https://linear.app/developers/oauth-2-0-authentication) and
[app-actor guide](https://linear.app/developers/oauth-actor-authorization).

## 1. Read the deployment callback URL

OAuth configuration is intentionally a second step after the base stack exists:

```bash
terraform -chdir=infra output -raw oauth_callback_url
```

Copy the complete HTTPS URL. Do not shorten it, add a path, or substitute a console URL.

## 2. Create the Linear OAuth application

In Linear, open **Workspace settings → API → OAuth applications**, then create an application:

1. Use a recognizable name such as **Rat Things** and describe the workspace actions it performs.
2. Register the exact callback URL from step 1 as a redirect URI.
3. Keep the application private unless you intend to operate the provider review and support path
   for other Linear workspaces.
4. Leave webhooks disabled for this integration. The current built-in does not consume Linear
   issue, comment, or Agent Session events.
5. Save the application, then copy its client ID and client secret into a temporary
   owner-readable file.

The compiled Rat manifest—not the CLI or browser—adds `actor=app`, `prompt=consent`, and scopes
`read,write` to the authorization request. `read` is needed for workspace identity, teams, search,
issues, and comments. `write` is provider authority for the three reviewed write operations; it
does not expose arbitrary Linear mutations to the agent.

## 3. Store the OAuth application credential in AWS

Create a local file outside the repository:

```json
{
  "client_id": "replace-with-linear-client-id",
  "client_secret": "replace-with-linear-client-secret"
}
```

Put it in Secrets Manager without placing either value in Terraform or a shell argument:

```bash
aws secretsmanager create-secret \
  --name rat-things/linear-oauth-app \
  --secret-string file:///secure/tmp/linear-oauth-app.json \
  --region us-west-2
```

Retain the returned secret ARN, remove the temporary file through your normal secure cleanup
process, and do not commit it. The secret contains the deployment-owned OAuth application
credential, not a workspace access token.

## 4. Enable Linear OAuth in the deployment

Add only the secret ARN to the existing map in the deployment's Terraform variables:

```hcl
integration_oauth_app_secret_arns = {
  linear = "arn:aws:secretsmanager:us-west-2:111122223333:secret:rat-things/linear-oauth-app-AbCdEf"
  # Keep any existing providers, for example slack = "arn:...".
}
```

Package and apply the reviewed checkout using the deployment's normal process. Then confirm the
catalog exposes Linear and reports OAuth as configured:

```bash
rat-things plugins --json
```

The `linear` manifest should show `oauthInstallation.status` as `configured` and the exact callback
URL. A `host-required` status means the ARN map has not reached the control plane.

## 5. Install the Linear workspace

Start consent from the authenticated Rat owner that should own the Connection:

```bash
rat-things connect linear --oauth --wait \
  --access read-write \
  --alias linear-work
```

The CLI opens a ten-minute authorization URL. A Linear workspace admin chooses the workspace and
approves the app installation. Add `--no-browser` on a headless host and open the printed URL in a
browser; omit `--wait` if the initiating shell should return immediately.

After the callback, Rat queries Linear's `viewer` and `organization` fields before storing the
issued token. The Connection label is derived from that response, and its stable workspace and app
user IDs are recorded separately. Neither token nor secret value is returned.

## 6. Verify the installed identity and access

```bash
rat-things connection show linear-work
rat-things connection test linear-work
rat-things connection consumers linear-work
```

Check that the workspace label and provider scopes are expected, health is `healthy/verified`, and
the Rat grant is `read-write`. Start with `--access read-only` instead when a workflow needs only
team discovery, search, and issue inspection.

To reconnect an expired or revoked authorization without changing the alias, grant, or consumers:

```bash
rat-things connection reconnect linear-work --oauth --wait
```

Rat accepts the replacement only if Linear resolves it to the same workspace and app-user IDs.

## 7. Expose bounded operations to an Agent

A verified Connection does not automatically add tools to a standard Session.
Declare an MCP server or application functions in the Agent configuration. Their
trusted implementation should invoke only the installed operations and enforce the
Connection's account, operation and resource grants before reading credentials.

For a read-only investigation, expose team discovery, issue search and issue reads.
For issue creation, use a separately bounded tool that validates the approved team.
If duplicate creation is unacceptable, enforce a durable idempotency boundary in
that host implementation; a search-first prompt cannot enforce uniqueness.

A Session using application functions enters `requires_action` until the application
returns each result with its `turn_id` and `call_id`. The saved Items record those
calls. See [Agents API](agents-api.md) and the
[Slack-to-Linear workflow guide](../guides/slack-to-linear-agent-workflow.md).

## Optional personal API key path

For one trusted operator workspace, the built-in also accepts a Linear personal API key. Put
`{"api_key":"..."}` in an owner-readable credential file and install it explicitly:

```bash
rat-things connect linear --auth-scheme api-key \
  --credential-file /secure/tmp/linear-api-key.json \
  --access read-only \
  --alias linear-personal
```

Linear personal keys are broad and do not report granular OAuth scopes. Prefer OAuth for a shared
or long-lived deployment, and keep the Rat grant and declared tool operation list narrow either way.

## Current boundaries

- Linear cannot yet start or continue a Rat conversation through mentions, issue delegation, or
  Agent Session prompts.
- Rat does not emit Linear Agent Activities or use Linear's native agent-session progress UI.
- Issue deletion, archival, labels, projects, cycles, attachments, relations, and administrative
  operations are not installed.
- Search returns at most 20 ranked issue summaries; issue inspection returns the first page of up
  to 20 comments.
- Write calls are autonomous inside the resolved Session envelope. There is no mid-Turn approval prompt.

Linear documents its GraphQL endpoint, issue queries/mutations, and error envelopes in its
[GraphQL guide](https://linear.app/developers/graphql). When native Linear ingress is added, it must
also follow Linear's signed raw-body and timestamp checks from the
[webhook guide](https://linear.app/developers/webhooks), acknowledge within five seconds, and keep
ingress separate from agent execution and result delivery.

For the shared account model, see [Integrations, accounts, and permissions](plugins.md). For Run
authority, see [The fixed capability envelope](capability-envelope.md).