Linear CI Contract Integration

Overview

Add deterministic CI coverage around a Linear integration while keeping ordinary pull-request tests offline and production writes explicitly gated.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• For CI and scheduled automation, Linear recommends requesting a client-credentials token at the start of each run instead of persisting an access token as a long-lived key.
• A client-credentials token is an app-actor token, is valid for 30 days, and must be replaced after a 401; requesting different scopes revokes the app's existing app-actor tokens.
• GraphQL transport success does not prove operation success; CI assertions must inspect the response errors array and mutation payload.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Inventory existing CI, test doubles, secret providers, and any Linear-aware branch or pull-request convention.
2. Keep pull-request tests offline with recorded, redacted GraphQL fixtures and schema-level assertions.
3. Put any live read probe in a separately approved protected job; acquire the narrowest client-credentials token per run and never echo it.
4. Gate live mutations behind an explicit environment approval and an idempotency key owned by the integration.
5. Assert HTTP status, GraphQL errors, expected payload fields, and rate-limit headers; preserve only redacted receipts.
6. Document who can rotate the OAuth client secret, disable the job, and clean up test artifacts.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; cre…

Linear Error Triage

Overview

Classify a failure before changing code or credentials, because Linear can return GraphQL errors with HTTP 200 and throttling errors with HTTP 400.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Always inspect the GraphQL errors array; a response can include partial data and errors together.
• Rate limiting is identified by extensions.code: RATELIMITED in an HTTP 400 GraphQL response, not by assuming HTTP 429.
• The SDK exposes parsed LinearError details including query, variables, status, data, raw error, and per-error path/type when available.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Capture the operation name, HTTP status, GraphQL error code/path, SDK version, and redacted rate headers.
2. Separate authentication, authorization, input, not-found, complexity, endpoint-budget, and service-health failures.
3. Reproduce with the smallest read-only query using the same auth mode; do not paste tokens or full customer variables.
4. For partial data, decide whether the caller must reject the whole response or can use explicitly safe fields.
5. For throttling, follow reset metadata, shrink requested fields/pages, and coordinate all workers sharing the user or app budget.
6. Return the root-cause evidence, bounded remediation, and a regression assertion.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-enable webhooks; import or export data; change roles, SCIM, or audit str…

Linear Issue Lifecycle Workflow

Overview

Build an issue workflow that resolves workspace-owned identifiers first and treats each write as a reviewable, reversible business action.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• issueCreate requires a team ID; without a state ID Linear selects the team's first Backlog state, or Triage when enabled.
• The SDK uses verb-first mutation names such as createIssue, updateIssue, and archiveIssue.
• Changes made during the first three minutes after issue creation are treated as part of creation and do not produce activity-log entries.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Resolve the authenticated viewer, organization, target team, workflow states, labels, and assignees using read-only queries.
2. Translate the requested business transition into an explicit create/update/comment/relation plan with stable IDs.
3. Validate required fields, visibility, duplicate policy, and whether Triage changes the default initial state.
4. Preview the exact mutation variables with sensitive or personal fields redacted.
5. After approval, perform one mutation and verify both GraphQL errors and payload success before the next action.
6. Return identifiers, resulting state, reconciliation query, and rollback or archive instructions.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-enable webhooks; import or export data; change roles, SCIM, or audit streaming; transmit…

Linear Project and Cycle Coordination

Overview

Map planning intent onto the workspace's actual project, cycle, initiative, and team model before making relationship changes.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Issues belong to one team, while projects can belong to one or more teams; access must be evaluated at both levels.
• List operations are Relay-style connections and must be paginated rather than assuming nodes is complete.
• Archived resources are hidden by default and require includeArchived: true when reconciliation needs them.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Discover visible teams, project statuses, cycles, initiatives, milestones, and archived-state requirements.
2. Define the source of truth and stable matching keys for every entity; names alone are not sufficient for unattended writes.
3. Build a read-only diff of requested membership, dates, status, and ownership changes.
4. Validate cross-team visibility and reject any mapping that would expose a private team's issues.
5. Apply approved mutations in dependency order and stop on the first GraphQL or payload failure.
6. Re-query every changed entity and produce a reconciliation report with compensating actions.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-enable webhooks; import or export data; change roles, SCIM, or audit streaming; transmit diagnostics; change paid entitlements; or perform another production mutation without…

Linear Workload and Capacity Tuning

Overview

Treat cost as the integration's compute, queue, storage, support, and quota consumption; do not claim a fixed Linear API price from cached documentation.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Linear publishes request and complexity budgets, not a universal per-request price; plan and contract entitlements are dynamic.
• Polling is discouraged; webhooks are the primary change signal when supported.
• Filtering, explicit page sizes, narrow field selection, and updated-time ordering reduce both query complexity and local processing.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Measure requests, complexity, payload bytes, queue time, retries, storage growth, and operator toil by workflow.
2. Separate required freshness from habitual polling and replace supported polling loops with verified webhooks.
3. Set per-workload request and complexity budgets below the applicable shared limits.
4. Reduce fields, page sizes, fan-out, duplicate reads, and retention while preserving correctness and audit needs.
5. Load-test with synthetic data and compare before/after throughput, freshness, and failure recovery.
6. Verify current plan terms with the workspace owner before presenting monetary savings.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-enable webhooks; import or export data; change roles, SCIM, or audit streaming; transmit diagnostics; change paid entitlements; or perform another production mutati…

Linear Data Handling and Export Safety

Overview

Preserve Linear's team and workspace access boundaries when data leaves the product, and minimize replicated content to the stated purpose.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Images and other assets may require authentication; external displays should download and self-host approved assets instead of leaking authenticated URLs.
• Workspace CSV exports are admin-controlled, owner-only on Enterprise, recorded in the audit log, and delivered through a link that expires after 12 hours.
• Issue-view CSV limits and role permissions differ; attachment files are not included even when links appear in descriptions.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Inventory data classes, sources, destinations, fields, team visibility, recipients, retention, and deletion owners.
2. Select the least-privileged export path: narrow GraphQL query, approved view export, workspace export, or supported reporting integration.
3. Remove unneeded descriptions, comments, customer requests, emails, attachment links, and audit metadata before transfer.
4. Encrypt approved transfers and stores, bind access to the original team/workspace visibility, and log export authorization.
5. Test deletion, subject-request, legal-hold, and access-revocation behavior on representative synthetic records.
6. Return a field-level data map and evidence without embedding the exported data itself.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; conf…

Linear Redacted Debug Bundle

Overview

Collect contract, version, timing, and failure metadata while excluding credentials, raw environment dumps, customer content, and unrestricted GraphQL variables.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Useful evidence includes operation name, timestamp, status, GraphQL error code/path, SDK version, redacted rate headers, and webhook delivery ID.
• SDK errors can contain queries, variables, response data, and raw errors; each field requires redaction before sharing.
• Webhook payloads can contain issue, comment, customer, and actor data; a delivery ID is safer evidence than the full payload.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Define the recipient, purpose, incident window, and approved data classes before collection.
2. Record package and runtime versions, endpoint host, auth mode—not token—and the smallest failing operation name.
3. Extract only allowlisted status, error-code/path, timing, request ID, delivery ID, and rate-budget fields.
4. Redact authorization, cookies, secrets, URLs with tokens, GraphQL variables, issue text, comments, emails, and user names.
5. Review the archive manifest and sample every included file before transmission.
6. Record recipient, retention deadline, deletion owner, and the exact secure transfer channel.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-enable webhooks; import or export data; change roles, SCIM, or audit streaming; transmit diagnostics; change paid…

Linear Deployment Evidence Integration

Overview

Design deployment-to-work traceability around stable issue identifiers and owner-approved state changes, while preferring native source-control integration where it satisfies the requirement.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Linear's GraphQL API is the explicit mutation surface; branch names and commit text are conventions, not proof that a deployment occurred.
• OAuth or app-actor access should be scoped to the teams and operations the deployment reporter actually needs.
• Every mutation result must be checked for GraphQL errors and reconciled by issue ID.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Inspect deployment receipts, Linear's source-control integration, identifier conventions, and current issue-transition policy.
2. Choose the native integration, a read-only evidence link, or a custom mutation path based on the actual gap.
3. Resolve issue identifiers from trusted release metadata; reject free-form or ambiguous branch parsing.
4. Preview comments, links, labels, or state changes and separate evidence recording from workflow transition authority.
5. After the deployment system reports final status and approval is present, perform one idempotent update.
6. Re-query the issue and preserve the deployment, mutation, and rollback receipts.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-enable webhooks; import or export data; change roles, SCIM, or audit streaming; transmit…

Linear Enterprise Access Governance

Overview

Model access from the workspace's actual plan, roles, teams, OAuth actor, and identity-provider ownership instead of inventing application-side Linear roles.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Workspace Owner exists only on Enterprise; Team Owner exists on Business and Enterprise; Free-plan users are admins.
• SCIM 2.0 is an Enterprise capability. Linear supplies the base connector URL and bearer token in security settings; do not hard-code a guessed endpoint.
• SCIM group push can map groups one-to-one to teams, and special linear-owners, linear-admins, and linear-guests groups control roles.
• Enterprise audit logs retain 90 days of events and are accessible only to workspace owners.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Confirm plan, workspace owners, admins, team owners, members, guests, private teams, and existing SCIM ownership.
2. Map each application action to the narrowest OAuth scopes and team access; do not derive authorization from UI role labels alone.
3. Review identity-provider group mappings, default public teams, guest exceptions, suspension, and break-glass ownership.
4. Test create, update, suspend, unsuspend, group removal, and disconnect behavior in a non-production identity set.
5. Configure audit queries or streaming with redaction, retention, and SIEM ownership appropriate to the signed policy.
6. Produce a least-privilege matrix and a separately approved rollout/rollback plan.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authori…

Linear Read-Only Connectivity Proof

Overview

Verify endpoint, auth mode, viewer identity, and visible team count without spending the first test on a production write.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• The GraphQL endpoint is https://api.linear.app/graphql and supports introspection.
• Personal API keys use Authorization: <API_KEY> without Bearer; OAuth access tokens use Authorization: Bearer <ACCESS_TOKEN>.
• The official TypeScript SDK accepts either apiKey or accessToken in LinearClient.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Inspect the repository runtime, package manager, secret-loading convention, and existing Linear client code.
2. Select personal API key only for owner-controlled scripts or OAuth for applications used by others.
3. Pin a compatible @linear/sdk range or construct a minimal GraphQL request using the correct authorization form.
4. Query only viewer ID/display name and a small page of visible team IDs/keys; inspect GraphQL errors.
5. Record SDK version, auth mode, endpoint, status, and counts without logging the token or returned personal content.
6. Leave all create/update/delete operations for a separately approved workflow.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-enable webhooks; import or export data; change roles, SCIM, or audit streaming; transmit diagnostics; change paid entitlemen…

Linear Integration Incident Runbook

Overview

Restore a safe operating state from read-only evidence first, then reconcile missed or duplicated work without generating diagnostic mutations in production.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Linear webhooks time out after five seconds and retry failed deliveries at one minute, one hour, and six hours, up to three retries.
• Rate-limit evidence comes from request, endpoint, and complexity headers plus RATELIMITED GraphQL errors.
• OAuth client-secret rotation invalidates client-credentials tokens immediately but does not revoke existing workspace access/refresh tokens by itself.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Declare severity, commander, affected workspaces/teams, start time, customer impact, and mutation freeze state.
2. Check Linear service status and the smallest read-only authenticated query; capture redacted errors and rate headers.
3. Classify auth, authorization, quota, schema, webhook delivery, downstream queue, or reconciliation failure.
4. Contain retries, pause nonessential producers, preserve webhook delivery IDs, and avoid rotating secrets without an access-impact map.
5. Recover through the smallest approved change, then replay only idempotent or explicitly reconciled work.
6. Close with a gap analysis, missed-event reconciliation, credential review, and regression test.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-enable webhooks; import or export …

Linear SDK Installation and Authentication

Overview

Choose authentication from the operating model, pin the SDK through the repository's lockfile, and prove access with a bounded read-only query.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• The official package is @linear/sdk; npm reported 95.0.0 with Node.js >=18.x on 2026-09-11.
• Personal keys use a raw Authorization value; OAuth tokens use the Bearer scheme. The SDK represents these as apiKey and accessToken.
• OAuth is recommended for applications used by other people; scheduled automation should use the client-credentials grant when enabled.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Inspect runtime, Node version, manifest, lockfile, existing client construction, and secret provider.
2. Choose personal key for an owner-controlled integration, authorization-code OAuth for user-delegated access, or client credentials for approved unattended automation.
3. Pin a compatible SDK range and commit the resolved lockfile; do not silently take an unbounded latest version in CI.
4. Inject credentials from the approved server-side secret manager and document the variable name without its value.
5. Run a read-only viewer/team proof and check both transport status and GraphQL errors.
6. Assign owners for scope review, app approval, rotation, revocation, and emergency disablement.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-enabl…

Linear Local Development Loop

Overview

Keep routine tests deterministic and offline, then use a deliberate read-only or sandbox-workspace probe to detect contract drift.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Webhook delivery requires a publicly accessible HTTPS, non-localhost URL; localhost-only receivers are not a production-equivalent test.
• Signature verification requires the exact raw request body, so body-parser ordering belongs in local contract tests.
• GraphQL introspection and official generated SDK types are better schema authorities than hand-written guessed fixtures.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Inspect the repository's test framework, GraphQL client boundary, fixtures, environment loading, and webhook middleware order.
2. Record minimal redacted success, partial-error, auth-error, throttling, pagination, and webhook fixtures.
3. Inject a fake client at the adapter boundary; do not mock every SDK model method across the application.
4. Test raw-body signature verification, duplicate delivery IDs, five-second acknowledgement behavior, and queued processing.
5. Use an isolated workspace and approved tunnel only for explicit end-to-end checks; label and clean up test records.
6. Add a protected contract probe that detects schema/package drift without mutating production.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-enable webhooks; import or export data; change roles, SCIM, or audit streaming; transmit diagn…

Linear Workspace Data Migration

Overview

Choose the supported importer that preserves the required data, pilot a bounded team, and prove mappings and rollback before cutover.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Imports require a workspace admin; dedicated import assistants are preferred because they retain more source data and can support bulk deletion for a limited time.
• The CLI importer is for sources without a dedicated assistant and does not preserve all data such as comments or projects.
• Re-importing the same source into the same team skips already-imported issues unless the prior import is deleted first.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Inventory source entities, volumes, users, teams, statuses, labels, projects, comments, attachments, timestamps, and compliance constraints.
2. Choose a dedicated assistant when available; use the CLI only after documenting the data it cannot preserve.
3. Define deterministic user, team, workflow, priority, estimate, and label mappings plus explicit exclusions.
4. Run a small pilot into an approved destination team and validate counts, samples, permissions, links, and timestamps.
5. Approve the cutover window, source freeze, communications, duplicate policy, rollback window, and accountable owners.
6. After import, reconcile counts and sampled semantics, preserve receipts, and keep the legacy source read-only for the approved period.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-ena…

Linear Multi-Environment Isolation

Overview

Make environment boundaries explicit so a local test cannot consume production credentials, events, or team data.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• OAuth callback URLs are registered on an application, and OAuth webhook settings create a workspace-specific webhook when that app is authorized.
• Webhook signing secrets and OAuth client secrets rotate independently and take effect immediately for their respective uses.
• Client credentials must be enabled per OAuth app and app-team access can be changed from the app details page.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Inventory every environment's workspace, OAuth app, callback URL, webhook URL, signing secret, client secret, team access, and data class.
2. Use separate app registrations and secret references where blast radius or callback ownership differs.
3. Validate exact callback allowlists, public HTTPS endpoints, environment labels, and least-privilege team access.
4. Prevent local and pull-request jobs from resolving production secret names or mutation endpoints.
5. Promote configuration through reviewed manifests while rotating or revoking credentials as separate approved operations.
6. Test misrouting, stale-secret, rollback, and environment-disable scenarios before production rollout.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-enable webhooks; import or export data; change roles, SCIM, or audit streaming; transmit diagn…

Linear Integration Observability

Overview

Measure contract health and business freshness without placing tokens, GraphQL variables, issue content, or user identities in telemetry.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Linear returns request-limit, endpoint-limit, complexity, remaining-budget, and reset headers that can drive safe capacity telemetry.
• Webhook delivery headers include unique delivery ID, event type, signature, and timestamp; never log the signature as reusable evidence.
• Enterprise audit logs retain 90 days and can be queried or streamed, but are owner-only and contain sensitive actor/IP metadata.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Define service objectives for API success, GraphQL application errors, webhook acknowledgement, queue lag, and reconciliation freshness.
2. Emit operation names, status, normalized error code, latency, retry count, and rate/complexity budget—not raw queries or variables.
3. Track webhook delivery ID hashes, event type, verification result, acknowledgement latency, dedupe outcome, and processing lag.
4. Alert on sustained budget exhaustion, auth failures, signature failures, queue age, and reconciliation divergence.
5. Keep audit-log ingestion separate, least-privileged, redacted, and aligned with the organization's retention policy.
6. Test dashboards and alerts with synthetic failures and record owner, runbook, and quieting rules.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-ena…

Linear Query Performance Tuning

Overview

Tune the measured operation rather than applying guessed delays, and preserve correctness with bounded pagination and reconciliation.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Each property costs 0.1 complexity point, each object 1 point, and connections multiply child cost by the requested page size or default 50, rounded up.
• A single query cannot exceed 10,000 complexity points; hourly complexity and request limits are shared by user or app actor.
• Filtering server-side, requesting explicit page sizes, ordering by updated time, and using webhooks reduce unnecessary work.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Measure operation latency, requested fields, connection fan-out, page sizes, complexity header, payload bytes, and cache hit rate.
2. Replace broad SDK model walks with a purpose-built GraphQL query when only a narrow projection is needed.
3. Filter at the server, request the smallest explicit page, and paginate until hasNextPage is false.
4. Eliminate N+1 reads and uncoordinated polling; use webhooks plus a bounded reconciliation window.
5. Load-test below the applicable shared request/complexity budgets and verify tail latency and correctness.
6. Document before/after evidence and rollback the query change if semantics or visibility differ.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-enable webhooks; import or export data; change roles, SCIM, or audit streaming; transmi…

Linear Production Readiness Gate

Overview

Produce an evidence-backed go, conditional-go, or no-go decision instead of a box-checking document detached from the deployed system.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• OAuth is recommended for apps used by others, and app/team authorization, refresh behavior, and secret rotation must be tested.
• Webhook receivers require public HTTPS, raw-body signature verification, a 200 response within five seconds, deduplication, and reconciliation.
• Request and complexity limits vary by auth mode and can include lower endpoint-specific windows.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Identify the exact artifact, commit, environment, workspace/team scope, data classes, owner, and rollback authority.
2. Verify SDK/runtime compatibility, token type, exact scopes, secret storage, rotation, revocation, and access review.
3. Run offline tests plus approved read-only auth, error, rate-header, pagination, and webhook-signature probes.
4. Review data minimization, export/retention, observability redaction, idempotency, queue behavior, and missed-event reconciliation.
5. Exercise dependency outage, token failure, throttling, duplicate webhook, rollback, and disablement paths.
6. Record blockers, evidence, accountable approvers, decision, expiry, and post-launch checks.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-enable webhooks; import or export data; change roles, SCIM, or audit streaming; transmit diagn…

Linear Request and Complexity Control

Overview

Coordinate the applicable user, app-actor, endpoint, and complexity budgets so retries do not multiply pressure.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• API key: 2,500 requests and 3,000,000 complexity points per user per hour; OAuth: 5,000 requests and 2,000,000 points per user or app user per hour.
• Unauthenticated traffic: 600 requests and 100,000 complexity points per IP per hour; one query is capped at 10,000 points.
• Endpoint-specific limits can be lower and expose their own limit, remaining, reset, and endpoint-name headers.
• GraphQL throttling returns HTTP 400 with extensions.code: RATELIMITED; Linear uses a leaky-bucket refill model.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Inventory every producer and auth actor sharing a quota, including multiple keys owned by the same user.
2. Read request, endpoint, and complexity headers and convert reset values from UTC epoch milliseconds.
3. Allocate per-workload budgets below all applicable limits and centralize queue/admission control.
4. Reject queries above the single-query maximum before sending; reduce fields, nesting, and page size.
5. On RATELIMITED, stop new pressure, honor the relevant reset/window evidence, and bound retry attempts with jitter.
6. Test burst, sustained, endpoint-specific, complexity, and retry-storm behavior with synthetic workloads.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re…

Linear Integration Reference Architecture

Overview

Create a repo-grounded architecture that makes authority, data flow, failure containment, and reconciliation explicit. Preserve the host application's boundaries instead of forcing a generic service topology.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Use the official SDK for broad typed access and purpose-built GraphQL queries for narrow high-volume projections.
• Webhook ingress must verify the raw-body HMAC, acknowledge within five seconds, deduplicate by delivery ID, and move durable work to a queue.
• A reconciliation reader is still required because webhooks and downstream consumers can fail or be disabled.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Map callers, workspaces, teams, auth actors, data classes, latency targets, writes, and compliance boundaries from the repository.
2. Separate credential acquisition, Linear adapter, policy/authorization, webhook ingress, durable queue, worker, and reconciliation components.
3. Define stable identifiers, idempotency, pagination checkpoints, partial-error handling, and rate-budget ownership.
4. Keep mutation commands behind policy and approval checks; keep reads and reconciliation independently operable.
5. Design observability around operation metadata and delivery IDs with strict content redaction.
6. Review outage, backlog, schema change, credential rotation, replay, rollback, and tenant-isolation scenarios.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace da…

Linear TypeScript SDK Patterns

Overview

Keep SDK mechanics inside a bounded adapter and expose domain-shaped results rather than generated model objects throughout the application.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Current SDK mutations use verb-first names such as createIssue, updateUser, and archiveProject.
• Connections expose nodes, pageInfo, fetchNext, and fetchPrevious; optional variables are passed in an object.
• linearClient.client.rawRequest supports purpose-built GraphQL, while LinearError exposes parsed request/response/error evidence.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Inspect the installed SDK version, generated types, adapter boundary, call sites, and error policy.
2. Create one client per approved auth context and inject it; never construct clients throughout business code.
3. Wrap SDK models in domain functions that accept stable IDs and return minimum typed projections.
4. Paginate every connection explicitly and expose checkpoints for long-running synchronization.
5. Use raw GraphQL only when it measurably reduces fields or fan-out; keep operation names and variables typed.
6. Normalize LinearError and GraphQL partial errors into retryable, terminal, and reconciliation-required outcomes.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-enable webhooks; import or export data; change…

Linear Integration Security Baseline

Overview

Apply least privilege and fail-closed verification across every credential, workspace boundary, inbound event, and diagnostic path.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• Authorization-code OAuth supports PKCE; applications must use exact registered redirect URLs and validate authorization state.
• All OAuth apps moved to the refresh-token system on 2026-04-01; access and refresh tokens require secure server-side storage and revocation handling.
• Webhook authenticity is HMAC-SHA256 over the exact raw body; compare safely and use timestamp/delivery ID for replay controls.
• Client-secret rotation and webhook-signing-secret rotation are separate operations with different impacts.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Inventory tokens, client and signing secrets, redirect URLs, scopes, team access, caches, logs, exports, and third-party processors.
2. Select the narrowest auth actor and scopes, validate OAuth state/PKCE, and store credentials only in an approved secret manager.
3. Verify webhook raw-body HMAC before parsing or queuing; reject invalid signatures and stale/replayed deliveries.
4. Redact authorization, cookies, queries, variables, issue content, emails, actor data, and signatures from telemetry.
5. Test revocation, client-secret rotation, signing-secret rotation, compromised-token containment, and app disablement.
6. Document residual risk, accountable owners, and an independently approved remediation rollout.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change s…

Linear SDK and Schema Upgrade

Overview

Derive the migration from the installed/current SDK diff and live schema instead of assuming every version change repeats the historical 1.x-to-2.x rename.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• The historical SDK 2.x migration changed mutations from model-first to verb-first names; modern upgrades must use actual release and type changes.
• Linear GraphQL has no conventional versioned API; deprecated fields use @deprecated, and API changes appear in the changelog with an [API] prefix.
• On 2026-09-11 npm reported @linear/sdk 95.0.0 requiring Node.js >=18.x; recheck before each upgrade.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Record current Node, SDK, lockfile, generated types, GraphQL operations, custom raw queries, and deprecated-field usage.
2. Read the target package metadata, repository changes, generated schema/type diff, and applicable Linear API changelog entries.
3. Classify compile-time renames, behavioral changes, auth/data implications, and runtime-only risks.
4. Upgrade on a bounded branch, commit the resolved lockfile, and repair adapters before business call sites.
5. Run static checks, unit/fixture tests, GraphQL contract tests, and an approved read-only workspace probe.
6. Stage rollout with package rollback instructions, monitoring thresholds, and schema reconciliation evidence.

Approval Boundaries

Do not create, reveal, rotate, or revoke credentials; authorize an OAuth app; change scopes or team access; create, mutate, archive, or delete workspace data; configure or re-…

Linear Verified Webhook Processing

Overview

Build an ingress path that proves authenticity on raw bytes, acknowledges quickly, and makes downstream processing replay-safe.

Prerequisites

• The target repository, Linear workspace, environment, and accountable owner
• Current security, privacy, compliance, capacity, and change-control requirements
• An approved Linear credential only when a bounded live verification is necessary

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and evidence. Use WebFetch only for current first-party Linear documentation and package metadata. Use Write or Edit only for requested implementation with known target files. Never write credentials, customer content, unrestricted environment output, or unredacted GraphQL variables.

Current Contract

• The endpoint must be public HTTPS and return HTTP 200 within five seconds; failures retry after one minute, one hour, and six hours, up to three retries.
• Linear-Signature is the hex HMAC-SHA256 of the exact raw body; Linear-Delivery is the unique delivery UUID and Linear-Timestamp is epoch milliseconds.
• Only workspace admins or OAuth applications with admin scope can create or read webhooks.
• The official SDK provides LinearWebhookClient, including raw-body signature verification and framework handlers.

Authentication

Use a personal API key only for owner-controlled scripts, OAuth with PKCE for user-delegated applications, or an enabled client-credentials grant for approved automation. Personal keys use Authorization: <API_KEY>; OAuth tokens use Authorization: Bearer <ACCESS_TOKEN>. Store credentials server-side in an approved secret manager.

Treat app approval, team access, scope changes, credential creation, rotation, revocation, and production access as owner-approved actions.

Instructions

1. Select explicit resource types and team/all-public-team scope, and identify the webhook/admin owner.
2. Capture the exact raw request bytes before JSON middleware and verify HMAC-SHA256 with the configured signing secret.
3. Reject invalid or stale/replayed requests, deduplicate by Linear-Delivery, enqueue the verified envelope, and return 200 within five seconds.
4. Process events idempotently using action, type, entity ID, updatedFrom, organization, and webhook ID as appropriate.
5. Bound retries and dead-letter handling; never assume Linear will retry beyond the documented schedule.
6. Run periodic cursor-based reconciliation and test create/update/remove, duplicate, delayed, revoked-app, and secret-rotation cases.