--- title: "Import the Linear roadmap" description: "Import Linear initiatives and projects into Deck as initiatives and Projects, so the roadmap can link to customer evidence." url: "/docs/agents/workflows/import-linear-roadmap" --- This page is an agent-readable workflow for Deck. Humans can follow along. Coding agents should treat the steps as the source of truth. # Import the Linear roadmap — agent workflow * **Use it when:** the user says "import our Linear roadmap", "bring our Linear initiatives into Deck" or "sync our Linear projects to Deck". * **Outcome:** the Linear initiatives and projects that the user picked are Deck initiatives and Projects, each linked to its Linear item. Nothing changes in Linear. * **Needs:** Deck MCP and Linear connected to Deck. Only organization admins connect integrations, in Settings → Integrations. Only organization admins can import a Linear initiative. Any member can import a single Linear project. Imports spend no credits. ## 1. Probe Deck MCP Call `get_user_context`. This must be a real tool call. * 401 Unauthorized: tell the user to connect Deck MCP in this client (Settings → Connections). Stop. * No Deck tools: fetch and follow [https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md](https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md). Stop this workflow until the tools work. ## 2. Check the Linear connection and the role Make these calls at the same time: * `explore_integrations` with `integration_type: "LINEAR"`. Read the state. * `explore_workspace` with `view: "settings"`. Read `viewer_role`. If the state is `not_connected` or `needs_attention`, tell the user that an organization admin must connect or reconnect Linear in Settings → Integrations. Give them the link from the result. Stop until Linear is connected. If `viewer_role` is not `admin`, tell the user that only an admin can import a Linear initiative. A member can still import Linear projects one at a time (step 6). ## 3. List what Linear has Make these calls at the same time: * `list_projects` with `importable_from: "linear"` and `kind: "initiative"`. * `list_projects` with `importable_from: "linear"` and `kind: "project"`. Set `limit` to 50 or less. When `page_info.has_more` is true, call again with `cursor` set to `page_info.next_cursor`. Do not use `query`, `project_key` or the Deck Project filters with Linear. Deck returns `VALIDATION_ERROR` for them. A row with `already_linked_initiative_id` or `already_linked_project_id` is already in Deck. Its `deck_url` opens it. Do not import it again. If the result has `status: "not_connected"`, go back to step 2. ## 4. Find Deck items that already cover a Linear item Call `list_initiatives` and `list_projects` with no `importable_from`, at the same time. Compare titles with the Linear rows. When a Deck Project already covers a Linear project that is not linked, propose a link instead of an import. A link keeps the Deck Project and avoids a duplicate. ## 5. Show the plan and get a yes Show one table: Linear title, kind, status, target date, and "already in Deck", "link" or "import". Ask the user: * Which initiatives and projects to import. * Which segments to apply. Call `explore_segments` for the segment IDs. * Which Deck initiative each standalone project belongs to, if any. Use the IDs from `list_initiatives`. Import an initiative first. Deck also imports its child projects that are not linked yet. ## 6. Run the imports Run one call for each item: * A Linear initiative: `import_linear_initiative` with `external_id` and optional `segment_ids` (at most 20). Then call `explore_build_initiatives` with `result.initiative_id` and read the imported Projects. * A Linear project: `import_project_from_jira_or_linear` with `provider: "linear"`, `artifact_type: "project"`, `external_id`, optional `initiative_id` and optional `segment_ids`. Then call `explore_build_projects` with `result.project_id`. * A Deck Project to link: `link_project_jira_or_linear` with `project_id`, `external_url` (the Linear URL) and `fetch_from_provider: true`. Handle these errors: * `AUTH_ERROR` on `import_linear_initiative`: the user is not an admin. Ask an admin to run it, or import the child projects one at a time. Projects that you import this way have no link to the Linear initiative. * `ALREADY_LINKED`: the item is already in Deck. Skip it and report it. * `PROVIDER_NOT_CONNECTED`: go back to step 2. ## 7. Check the result Call `list_projects` with `external_provider: "linear"`, and `list_initiatives`, at the same time. Run step 3 again. Each imported row now shows its linked Deck ID. Report the items that you imported, linked and skipped, each with its `deck_url`. ## Rules * Show the plan and get a yes before you call write tools. * Use only `external_id` values from `list_projects`. Never invent Linear items. * Imports read Linear and create Deck records only. Deck tools do not create or change anything in Linear. To create a Linear project, use the Deck web app or your own Linear tools, then call `link_project_jira_or_linear`. * An identical import within 24 hours returns the first result and creates nothing new. * Deck refreshes the title, status, owner and dates of linked items daily. Deck does not sync child relationships after the import. Documents and evidence stay in Deck. * Quote Deck's numbers. Do not compute your own. * If the user has more than one Deck organization, call `select_organization` first and pass `org_id` on every call. ## Done when * Each Linear item that the user picked is imported, linked or reported as skipped, with a reason. * Each imported item has a Deck link. * The user knows the next step: link customer evidence with the [roadmap evidence check](/docs/agents/workflows/roadmap-evidence-check). See also: [Linear](/docs/integrations/linear), [Initiatives](/docs/features/initiatives), [Projects](/docs/features/projects) and [Model Context Protocol](/docs/integrations/mcp). --- [View full sitemap](/docs/sitemap)