linear-migration-deep-dive

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-enable webhooks; import or export data; change roles, SCIM, or audit streaming; transmit diagnostics; change paid entitlements; or perform another production mutation without explicit approval from the accountable owner. Keep diagnosis read-only unless implementation was requested.

Output

Return the workspace and team scope, auth mode without credential value, files and contracts inspected, exact operation names, evidence collected, validation result, sensitive fields redacted, remaining risk, accountable owner, approval state, and rollback or next action.

Error Handling

Examples

Use a compact handoff that makes scope, mutation authority, and verification evidence reviewable.

Input:

source=jira; teams=2; issues=500; mode=pilot; comments=required

Expected handoff:

method=dedicated-assistant; mappings=review; cutover=not-approved

Resources

• Skill-specific official documentation
• Linear developer documentation index
• Linear GraphQL API