Skip to content
Docs menu

Import issues into Venom Tasks

Move a whole Linear workspace into Venom Tasks from one API key, in the background, and sync it again later; or bring issues from Linear, Jira, GitHub, Asana, Trello or Lark into one team with a mapping and a dry run.

View .md

Moving from another tracker should take one sitting. Settings → Import (/tasks/settings/import) has two ways in. Move in from Linear at the top brings a whole Linear workspace from one API key, runs on the server and can sync again later. Below it, Other sources, files and single teams walks an export or an API key through a mapping, a dry run and the import into one team. The same Import issues button is on Settings and in the empty state of an issue list; workspace Settings → Move in (/settings/move-in) links here too.

Move in from Linear

  1. Paste a key and press Check. Create a personal API key in Linear → Settings → Security & access (read access is enough) and paste it. Moving in creates teams, so an owner or admin does it.
  2. Read the preview. It is read from your Linear workspace and needs no decisions: how many teams, projects, cycles, labels, issues, initiatives and members there are; each Linear team and whether it becomes a new team or goes into the team here with the same key (or name); how many members match a member here by email and who does not; how many attachments there are and how much of your file storage the import may use; what does not come over; and about how long it takes, counting any wait for Linear's hourly limit. Adjust has the choices that matter: include archived issues (off), download files uploaded to Linear (on, when Venom Notes is on) and how much to store at most (200 MB, up to what your organisation's file storage has left). Nothing is written yet.
  3. Press Import. The import runs on the server. A progress bar shows the phase and what came over so far; you can close the page and come back, Pause and Resume it, or Cancel it (what came over is kept). It ends with a summary and the move-in report: what was created, merged, updated and kept, what was not carried and why, the people who did not match a member, and links to the teams and projects. The job, its preview (which names the Linear workspace's people) and its controls are visible only to the member who started it and to owners and admins.

Sync. After an import finishes, Sync again asks for the key again and brings only what is new or changed in Linear since the last run: new and edited issues, comments (new ones, and a thread resolved since) and attachments. Teams, labels, cycles, projects, initiatives, updates, documents, views, templates and favorites are read whole each time: new ones are created, ones Linear changed are updated, the rest are left alone. An issue (or project, update, document, view or template) edited here after the import wrote it is not overwritten: it is counted as "changed here, kept" and named in the notes. The import's own comments, files and relations on an issue do not count as an edit here. An issue or comment that could not be brought (it failed twice in a run) is named in the notes, and the next sync reads it again even if Linear has not changed it. There is no schedule; a sync runs when you press it.

What comes over

Linear Becomes
Teams Venom Tasks teams: the existing team with the same key (or name), else a new team with Linear's key, name, description and estimate scale
Sub-teams Linear's team tree: each team goes under the team its Linear parent became (see The team tree)
Team settings on a team the import made: cycles on or off, cycle length, cooldown, start day and upcoming count; triage on or off; close a parent when its sub-issues are done; auto-archive and auto-close months; the estimate settings (extended scale, zero estimates, and whether an unestimated issue counts as one point; see Estimates). A value Tasks cannot hold (a 10-week cycle) is named in the notes. A team that already existed here keeps its own settings
Workflow states matched by name, then by type; a team the import made also gets Linear's other states
Labels workspace and team labels, label groups with their labels
Cycles per team, with name, dates and completion; Linear's number when the team does not use it yet
Projects name, content, status, lead (by email), start and target dates, teams, milestones, priority, members (by email) and project labels. A custom Linear status name ("In design") becomes Tasks' status of the same type, named in the notes. A project label becomes the workspace label with the same name (in any case), else a new one with Linear's colour; a label in one of Linear's label groups is named "Group › Label" (Tasks' label groups are for issues). Labels are added to what the project has here, never removed, up to the 20 a project holds
Initiatives name, description, status (Proposed, Planned, Active, Completed, Canceled), owner (by email), target date, the initiative above it (a sub-initiative stays under its parent), projects (each under the initiative that links it; a Linear plan without initiatives: none)
Project and initiative updates on the project's (or initiative's) Updates, with Linear's health (on track, at risk, off track), body and time; the author is the member with the same email, else the Linear person is named as the author
Documents notes of the org vault, where project documents live: a project's document in Projects/<project>/, attached to the project (its Documents tab) and linked to it in References; any other document in Moved from Linear/. A document of a project or issue only private teams can see stays in Linear, with a note, since every member can read the org vault. Needs Venom Notes
Custom views saved views: a shared view of a team becomes that team's view, a shared view without a team a workspace view, a personal view the personal view of its owner when the owner is a member here; with Linear's filter and how the view is displayed (layout, grouping, ordering and the rest). See Views
Issue templates Tasks templates of their team (a workspace template goes into every team the import wrote): name, title, the body, priority, labels, assignee and sub-issue titles; what had no place here (status, estimate, project, cycle, due date) is named on the template itself, in the templates list and its editor
Favorites the favorites of the person whose key it is, for the member with their email: issues, projects, cycles, views and teams
Issues everything the per-team import brings, plus project, milestone, cycle, every label (by id) and every subscriber who is a member, the creator (by email), Linear's manual order, archived issues when chosen, and Linear's created, updated, started, completed and canceled dates (so cycle and lead times read as in Linear)
History each issue's status moves and assignee changes, with Linear's times and the person who made them, in the issue's activity: Insights' time in status, cycle time and flow chart read them as for an issue made here
Links to Linear in descriptions and comments, a link to an issue or project of the same Linear workspace becomes a Venom link (a bare address becomes the identifier, shown as a chip); a link whose target did not come over keeps its linear.app address, which still opens the imported item when pasted (see Old Linear links)
Sub-issues and relations parents (also when the parent comes later), blocks, related (and Linear's "similar"), duplicates
Comments with their author when the author's email is a member here, else with the author's name and date in the text; replies under their comment; a thread resolved in Linear is resolved here
Reactions on issues and comments, by members (by email); a reaction by someone who is not a member, or a custom emoji Tasks cannot show, is counted in the report
Attachments a file uploaded to Linear is downloaded and attached (at most 25 MB; see Files below); any other attachment (a pull request, a Figma file) becomes a link on the issue
Files in descriptions images and files uploaded to Linear are downloaded and the description points at the copy here; other links stay as they are

In a team the import made, issues keep their Linear number (MOV-12 stays MOV-12), so links and habits survive. When a number is already taken (an issue made here first), the issue gets the next free number and keeps "Imported from Linear MOV-12" in its description; the summary counts these. A team the import did not make keeps its own numbering.

People match only by email. Anyone who does not match stays unassigned (and their comments carry their name) and is listed once in the summary; nobody is invited. An issue whose creator does not match is created by the member who ran the import, and its "created" entry names the Linear person; status moves by someone who does not match read "Name (Linear)". An assignee change to or from someone who does not match is left out of the history (it would read "unassigned") and counted in the report.

Manual order. Each team's issues are put in Linear's manual order (the order its lists and boards show under Manual), with the same keys Tasks uses when you drag an issue. An issue you moved here after the import keeps its place.

Needs review. An issue that lost a value on the way (an estimate outside the team's scale, an assignee who is not a member, labels or a milestone Tasks refused, a list Linear did not finish answering) gets the workspace label import:needs-review. The report links to each team's list filtered to it, and Remove the label takes it off every issue at once when you are done. The import remembers why it labelled each issue: when a later sync brings back what it lost and nothing else is missing, the label comes off by itself.

Estimates

A team the import makes takes Linear's estimate scale (Linear, Fibonacci, Exponential, T-shirt, or none) and its three estimate settings: the extended scale, zero estimates, and whether an unestimated issue counts as one point (Linear's "default estimate" of 1 or 0). Every estimate an issue has in Linear then comes over as it is: T-shirt's XXL (13) and XXXL (21) and Exponential's 64 are on Tasks' extended scales. Linear does not publish every extended value of its Linear and Fibonacci scales, so the import never guesses one: a value Linear sends that the team's scale lacks (a whole number from 0 to 64, at most 8 such values a team) is kept as Linear sent it and becomes part of that team's extended scale here, with a note. Nothing is mapped to a different number.

A team that already existed here keeps its own estimate settings. An estimate it does not offer is left out, counted in the report and the issue labelled for review. To bring those estimates back, change the team's settings (turn on its extended scale or zero estimates, or pick Linear's scale) and run Sync again: every left-out estimate the team now takes is set, unless the issue was given an estimate here in the meantime, and the label comes off an issue that lost nothing else. An issue an earlier import labelled before it kept the reason is read again from Linear once: its estimate comes back and its label stays, since what else it lost is not known. See Estimates for the settings.

The team tree

Linear's sub-teams (Team.parent in its API) come over as Venom Tasks sub-teams. The tree is set once every team has been read, so a parent that comes after its child on Linear's pages is no trouble. A team that already sits under another team here keeps its place (noted). A team whose Linear parent did not come over (archived in Linear, or not readable with the key), or that would sit more than 8 levels deep, stays at the top level with a note. An imported sub-team does not inherit its parent's estimates or cycles, since Linear's settings are per team and were copied. A sync sets the same parent again, which changes nothing.

Optional fields

Before it reads anything else, the import asks Linear's API once which fields it has (an introspection query). A field it relies on that is not there (the team's parent and settings, an issue's creator, manual order and history, a project's link id) is simply not asked for, and the notes say what was not read; a renamed field can never fail a whole part of the import. A key that may not ask gets the import as it was before these fields: issues, comments and the rest, without the tree, settings, creators, order or history.

History stays quiet. Imported issues and comments notify nobody and send nothing out: no org webhooks (tasks.issue.created, tasks.comment.created), no live events, no inbox items, no Chat Triage posts, no AI triage or triage rules, no SLA clock, no GitHub label sync, no automatic close of parents, and the member who ran the import does not follow every issue. What is written: the issues, comments, relations, links and files themselves, their activity history, and Linear's subscribers who are members here. Changes you make afterwards behave as usual.

Files. A file uploaded to Linear is stored once: a retry, a resumed step or a sync finds it by its Linear address or by its content and reuses it. One import stores at most the amount chosen under Adjust (200 MB unless changed); past it, a file in a description becomes the line (file not imported: over the import's size limit: name) and an attachment stays a link to Linear titled the same way, and the summary counts them. A file in an open team's issue goes in the org vault, as Tasks attachments do. A file in a private team's issue goes in that team's Notes vault (its members and org admins), or, when the team has no Notes vault, stays a link to Linear, with a note: it is never put where every member can read it. A file that fails to download stays a link, with a note; it never costs its issue.

Not brought: notifications, integrations, SLAs, triage rules, customer requests, project and document templates (Tasks has issue templates only), what an issue template sets that a Tasks template has no place for (status, estimate, project, cycle, due date: named in the notes), favorites of anyone but the key's owner and favorites of documents, labels, initiatives or folders, views of projects or initiatives, the parts of a view's display Tasks has no place for (a grouping by SLA, customer, release or label group, an ordering by your last activity: named in the notes), an estimate a team that already existed here does not offer (counted, labelled for review, and brought back by a sync once the team takes it), archived issues unless chosen, and files when Venom Notes is off (they stay links to Linear, which asks for a Linear sign-in). Each issue links back to its Linear original. Text is checked for key-shaped strings (API keys, tokens, private keys), which are replaced with [secret removed] before anything is stored.

Views

Linear's view filter is turned into Tasks' filter condition by condition: status (by state, or by type), assignee, creator, subscribers ("me" stays "me"), labels, project, cycle (a cycle, or the current, next or previous one), team, parent, priority, estimate, due, created, updated, started, completed and canceled dates (fixed or relative, such as "in the last 2 weeks"), title and description, relations (blocked, blocking, related, duplicates), and the project's status, lead and priority, combined with all-of and any-of groups as in Linear. The view keeps Linear's name and description.

A condition Tasks has no filter for (customer, SLA status, attachments and the like), or that names something that did not come over, is left out, and the view is made with the rest. Such a view may list different issues than in Linear, so the report counts it, the notes name each left-out condition, and the view's own description starts with "Moved from Linear without: …". A condition that maps only roughly (a relative month, which Tasks reads as 30 days; a case-sensitive text match, which Tasks reads ignoring case) is named the same way. A view with nothing Tasks can filter on is not made, with a note.

How a view is displayed comes over too: the workspace's saved display for the view, and where it saved nothing, what Linear shows the person whose key it is. Layout (a list stays a list, a board stays a board; Linear's split view becomes a list), grouping and sub-grouping (status, status type, assignee, agent, priority, project, milestone, cycle, team, label, none), ordering (manual, title, priority, created, updated, due date, links, estimate, status, assignee, agent, customers, revenue, time in status) and its direction where the ordering has one (dates, numbers and titles; priority and status keep Tasks' own order), which completed issues show (all, none, the past day, week or month), closed issues by recency, sub-issues and their nesting, empty groups, hidden groups and columns, and the properties a row shows. A grouping or ordering Tasks lacks keeps Tasks' default for that part and is named in the notes and in the view's description ("Displayed without: …"); one that is only close (completed issues since the cycle began, shown as the past week) is named as close. A view whose display Linear does not answer opens with Tasks' default (a list grouped by status), and the report counts it. A view imported before the display could be read gets it on the next sync, unless it was edited here.

Linear's API gives the key's owner the shared views and their own personal views; other people's personal views are not readable with one key, so they do not come over.

The move-in report

When the job ends, the page shows the report, and Copy report and Download give it as Markdown:

  • a row per kind (teams, labels, cycles, projects, milestones, initiatives, project and initiative updates, issues, comments, resolved threads, reactions, relations, attachments and files, history entries, documents, custom views, templates, favorites, estimates, project labels and views' display) with how many Linear has (Check's count where Check counts it, else what the run read), how many Venom holds from Linear now, and how many the run created, updated and skipped;
  • every reason something was not carried, grouped and counted ("estimate outside the team's scale: 12", "person not in the org: 3 issues assigned, left unassigned", a status move to a state that did not come over, a team left at the top level), with the notes that name each item;
  • how many issues carry import:needs-review, a link per team to them, and Remove the label;
  • the people who did not match a member.

A sync reads only what changed, so "In Venom" counts every run's items: after the last sync it reads against Linear's own count. Reactions, resolved threads, favorites, estimates, project labels and views' display have no "In Venom" count (–); the run's columns count them. Estimates: issues read with an estimate, estimates written (created), estimates brought back by a sync (updated) and estimates a team does not offer (skipped). Project labels: labels read on projects, labels made here (created) and labels added to projects (updated), and labels past a project's 20 (skipped). Views' display: views read, views with Linear's display (created) and views whose display Linear did not answer (skipped). Agents get the same report from tasks_import_job_get (report in its answer).

An old address of an issue (https://linear.app/<workspace>/issue/ENG-12/…) or a project (https://linear.app/<workspace>/project/<name>-<id>) opens the item it became wherever Venom reads a reference: ⌘K, workspace_item_get, the Linked section and [[…]] (see References). The import's map answers, so it works when the issue's number changed here, and no call is made to Linear. Only linear.app addresses are read this way. An identifier nothing here has (ENG-12 after a team key changed) is looked up in the same map.

Before you stop using Linear

  1. Keep the team keys, so Fixes ENG-12 in old commits and branch names still finds its issue.
  2. Connect GitHub (Settings → GitHub).
  3. Invite the people the report lists as not matching a member, then sync.
  4. Open each view the report says was imported without some conditions, and compare its list with Linear's. Its layout, grouping and ordering came over; the report and the view's description name any part that did not.
  5. Check each team's estimate settings (Settings → the team → Estimates): the scale, the extended scale, zero estimates and whether unestimated issues count as one point. On a team that already existed here, change them to match Linear's if the report counts estimates left out, then sync again to bring them back.
  6. Ask each teammate whose personal views or favorites matter to them to recreate them here: only the key owner's come over.
  7. Run Sync again once more just before you switch, and read the report: "In Venom" against "In Linear", and what was not carried.
  8. Then stop using Linear. Its key can be revoked: the import deleted its own copy when the job ended.

The key, and what Venom Cloud calls

Venom Cloud calls api.linear.app only after you paste a key and press Check or Import, and downloads files only from uploads.linear.app addresses Linear itself returned (https, public addresses, at most 25 MB each). The key is sent to those two hosts and nowhere else; when Linear answers a download with a short-lived signed address, that one request is made without the key.

The background job needs the key while it runs, so it is sealed in the vault (the same encryption as the organisation's provider keys, bound to the organisation and the job) when you press Import. It is deleted when the import finishes, fails for good or is canceled, and in any case 24 hours after it started. It is never shown again (the page shows its last four characters while the job holds it), never written to a log, an audit row or an error. A server without a vault key (VENOM_VAULT_KEYS) cannot run a background import; the per-team import below still works.

Linear limits a key's requests and query complexity per hour. Check reads what the key has left and the estimate counts the wait when the import needs more; the import reads a page of 50 issues per request (with the first 20 labels and 20 subscribers each; an issue with more gets one small follow-up read for the rest, as do a project's teams and milestones and an initiative's projects), then one history read per issue, waits when Linear says to slow down and carries on by itself. It only reads: it never writes to Linear. A page Linear finds too complex is asked for again with half as many items, down to one; if even one is too complex, the rest of that part is skipped with a note. Parts a key or a plan cannot read (initiatives, milestones, labels, cycles, projects, relations, attachments, updates, documents, views, templates, favorites) are skipped with a note; only a key Linear refuses outright ends the import. Any other failed call is retried with a growing wait, six times in a row at most. Every failure says what happened, and running the import again is always safe: everything is remembered by its Linear id, so nothing comes over twice.

Each step of the job holds a lease; a step that runs past it stops before writing anything more, so two steps never work on one import at once. Pause and Cancel are seen before each issue, comment and attachment is written, and a new import waits until a canceled one's last step has stopped.

There is no "Connect with Linear" (OAuth) button yet: that needs an app registered with Linear. The readers take a token and do not care where it came from, so an OAuth connect can supply one later without changing the import.

Agents

The Tasks MCP server has tasks_import_job_list and tasks_import_job_get (Tasks read access; get returns the move-in report as report) and tasks_import_job_update (pause, resume, cancel; Tasks write access). Each sees only the jobs its member started, or all of them for an owner or admin. Starting an import is not a tool: it takes a key a person pastes, and a key in a tool argument would sit in the agent's transcript.

One team, from a file or a key

Below the Move in panel, Other sources, files and single teams brings issues into one team you pick, from any of the sources below, with a mapping step and a dry run. The rest of this page describes it.

Sources

Source Takes Brings
Linear the CSV export, or a personal API key title, description, status, priority, labels, assignee, estimate, due date, parent issue, created and completed dates; comments with the API key
Jira the CSV export (all fields) summary, description, status, priority, labels, assignee, story points, due date, parent, comments, created and resolved dates
GitHub Issues a repository (owner/name) and an access token title, body, open or closed (closed as not planned becomes canceled), labels, assignee, comments, created and closed dates. Pull requests are left out
Asana the project's CSV export name, notes, section as status, assignee (with email), tags, priority, due date, subtasks by parent title, created and completed dates
Trello the board's JSON export cards, lists as statuses, labels, first member as assignee, due date, checklists in the description, comments, creation date. Archived cards are skipped
Lark / Feishu Projects a work item view's CSV export name, description, status, priority (P0 to P3, or the Chinese names), owner, tags, points, due date, created and finished dates; English and Chinese headers

The steps

  1. Pick the source and the team. Issues land in one team. Drop the file on the page or paste its contents.
  2. Check the mapping. Each status in the source maps to one of the team's states (an exact name first, then the source's own state type, then common names like Done, Closed or Won't do). People match by email, then by an exact name that only one member has. Anyone unmatched stays unassigned and is listed. Labels that do not exist are created as workspace labels.
  3. Read the dry run. It counts what will be imported, what an earlier import already brought over, comments and new labels, and previews the first rows with the state, priority and assignee they will get. Nothing has been written yet.
  4. Import. A progress bar runs through the issues, parents first, a batch at a time. Stop after this batch pauses it.
  5. Read the summary. Created, already there and failed, each failure with its reason, the notes (an estimate off the team's scale is dropped, a comment too long is cut), who stayed unassigned, and links to the new issues.

What carries over

Priority, labels, estimate, due date, parent and sub-issues, comments (with the author's name and date in the text, because the author may not be a member here), and the created and completed or canceled dates. Each description ends with "Imported from Linear ENG-12", linking back when the source gave a URL. Imported issues do not notify anyone: no "assigned to you" for hundreds of issues at once.

An estimate is kept only when the team's estimate scale takes it (a Fibonacci team keeps 1, 2, 3, 5, 8, 13, and drops a 4). Change the scale in the team's settings first if you want them all.

Running it again

Each imported issue is remembered by its source and its id in the source (ENG-12). Running the same import again, or the CSV after the API key, skips those issues and creates only new ones. If the import stops halfway (a closed tab, a rate limit), run it again to continue. Deleting an imported issue forgets it, so it can come back.

An issue's parent is linked when the parent was imported first or earlier. A parent that is not in the import leaves the child without a parent, with a note.

Linear

CSV. In Linear: Settings → Workspace → Import / Export → Export CSV. The export holds one row per issue and no comments. Linear writes the assignee as a name, so people match by exact name.

API key. Create a personal API key in Linear → Settings → Security & access (read access is enough) and paste it on the page. Venom Cloud calls api.linear.app once per page of 25 issues, only while you wait on that screen. The key is held in your browser for the fetch, sent over HTTPS with each request, used for that request alone and dropped when the fetch ends. It is not stored and not written to a log or an error message. The API import brings comments, assignee emails and every state type.

Priorities map to Urgent, High, Medium and Low (Jira's Highest is Urgent, Lowest is Low). Sources that name people without an email (Jira, Trello, GitHub logins, Lark names) match a member only by an exact, unambiguous name, and anyone else is listed so you can pick a member in the mapping step.

GitHub

Enter owner/name and a token. A fine-grained token needs read access to the repository's Issues; a classic token needs repo (public_repo for a public repository). Venom Cloud calls api.github.com for one page of 30 issues at a time and for each issue's comments, only while you wait on that screen. The token is used for that request and dropped, as with Linear's key. A rate limit pauses the import with a message; run it again to continue.

Permissions

Importing needs the same permission as creating an issue: a member who can change things in the organisation (owner, admin or developer). A viewer or billing member can open the page and cannot import.

API

Move in from Linear uses these, same-origin with the console session:

Endpoint Body Answer
POST /tasks/api/import/linear/check {token, archived?} {preview}: what the workspace holds and what it becomes here; writes nothing
POST /tasks/api/import/jobs {source: "linear", token, archived?, files?, fileBytes?} 201 {job}; 409 import_running while one runs or is paused, 409 import_finishing while a canceled one's last step still runs. fileBytes: the files budget in bytes (default 200 MB, at most what the org's file storage has left)
GET /tasks/api/import/jobs {jobs}, newest first: the ones the caller started, or all for an owner or admin; never a token
GET /tasks/api/import/jobs/{id} {job}: status (running, paused, done, failed, canceled), phase, counts, notes, unmatched, error, token (last four characters, or null once deleted)
PATCH /tasks/api/import/jobs/{id} {action: "pause" | "resume" | "cancel"} {job}
POST /tasks/api/import/jobs/{id}/step {job} after up to ~40 s of work; the open page calls it, the imports cron (/api/cron/imports, every minute) carries the job on without it

The one-team import uses three endpoints, all POST, all same-origin with the console session:

Endpoint Body Answer
/tasks/api/import/plan {source, teamId, digest} (statuses, labels, assignees and keys) {plan}: state and member matches, labels to create, keys already imported
/tasks/api/import/run {source, teamId, issues[≤25], mapping} {outcomes}: created, skipped or failed per issue
/tasks/api/import/pull {source, token, scope?, cursor?} (scope is GitHub's owner/name) {issues, nextCursor}: one page of the source's API