Project management migration

GitHub Issues → Linear

Move projects, work items, hierarchy, statuses, users, comments, attachments, custom fields, automation, permissions, and reports from GitHub Issues into Linear with an explicit exception ledger and evidence-based cutover.

Typical timeline8–18 business days35–72 hours active work

Statusneeds review

Source testedGitHub Issues documentation reviewed 2026-07-19

Destination testedLinear documentation reviewed 2026-07-19

Last reviewed2026-07-19

Sources2

Before you migrate

Should you make this move?

Both platforms have a case. Compare what you gain with what you give up before scheduling the cutover.

Current platform

GitHub Issues

Reasons to stay

Lightweight planning stays directly connected to code, pull requests, and releases
Structured ownership, status, and workflow views improve operational visibility

Reasons to leave

Cross-team planning, reporting, and workflow controls are intentionally limited
Custom fields, automations, history, and reporting are difficult to reproduce exactly

New platform

Linear

What gets better

Fast, opinionated product-development workflows keep software teams focused
Structured ownership, status, and workflow views improve operational visibility

What gets worse

Non-software work and highly customized enterprise processes fit poorly
Custom fields, automations, history, and reporting are difficult to reproduce exactly

Best of the move

Linear: Fast, opinionated product-development workflows keep software teams focused. This removes a major source-side concern: Cross-team planning, reporting, and workflow controls are intentionally limited.

Worst of the move

What you lose: Lightweight planning stays directly connected to code, pull requests, and releases. What you inherit: Non-software work and highly customized enterprise processes fit poorly.

01At a glance

Know the shape of the move.

Transfer outcome12 features audited

Clean0

Partial9

Manual2

Lost1

Mapping route9 of 9 fields have a destination path

SourceGitHub Issues9 mapped fields

Automatic0

Transform8

Manual1

Unsupported0

DestinationLinear9 supported paths

This timeline assumes

Up to 100 projects, 100,000 work items, and 500 users
Only active work and explicitly approved history enter the destination.
Users and guests are provisioned before assignment mapping.
A representative project or board is imported before the full workspace.
The migration team records evidence for every blocking verification check.

02Loss matrix

What survives the move.

“Partial” and “manual” are not footnotes. They are work that must be scheduled and verified.

Item	Outcome	Impact	What happens	Mitigation
Projects, work items, hierarchy, owners, statuses, dates, and comments	partial	critical	Core projects, work items, hierarchy, owners, statuses, dates, and comments can move, but GitHub Issues and Linear use different models, limits, identifiers, and import behavior.	Pilot every feature class, preserve source IDs, and reconcile accepted, transformed, rejected, and excluded items.
Custom views, formulas, automation, permissions, dashboards, and history	manual	critical	GitHub Issues-specific runtime configuration and historical evidence do not become native Linear behavior through the core data transfer.	Inventory every active dependency, approve its destination disposition, and test the replacement before source writes stop.
Projects, boards, and active work	partial	critical	Core work items can move, but source and destination hierarchy differ.	Approve the destination hierarchy before importing tasks.
Task titles and descriptions	partial	high	Text transfers more reliably than rich blocks, embeds, and application-specific markup.	Compare a stratified sample containing every content type.
Statuses, sections, and workflow	partial	critical	Columns, sections, groups, and statuses can represent different business concepts.	Map each source value to one approved destination state.
Assignees, teams, and guests	partial	critical	User identities can map while roles, guest scope, and licensing change.	Provision users first and test internal and external access.
Dates, milestones, and dependencies	partial	high	Due dates may move while schedules, dependency types, and baseline behavior differ.	Rebuild critical dependencies and validate milestone ordering.
Comments and activity history	partial	high	Import coverage and author attribution vary by route.	Archive full history and verify every required collaboration type.
Attachments and external links	partial	high	Files can exceed limits or remain linked to source-only URLs.	Copy required binaries and test access as ordinary users.
Custom fields and calculated values	partial	high	Field types, options, formulas, and validation do not match exactly.	Create a signed field dictionary and preserve source values.
Recurring work and templates	manual	high	Recurrence and templates are runtime configuration rather than task data.	Rebuild only active schedules and test their next occurrence.
Automation and integrations	lost	critical	Rules, webhooks, API clients, and connected apps do not execute after import.	Inventory every writer and enable replacements one at a time.

03Field and feature mapping

Where each thing goes.

Source	Destination	Method	Notes
GitHub Issues project or board	Linear project, team, or container	transform	Approve hierarchy and ownership first.
Task or card	Task or issue	transform	Preserve source ID and URL.
Section, list, group, or status	Destination status or grouping	transform	Map business meaning, not visual position.
Assignee or member	Destination assignee	manual	Map inactive and guest users explicitly.
Due date or milestone	Destination date or milestone	transform	Normalize timezone and date-only values.
Dependency or relation	Destination dependency or relation	transform	Create after both work items exist.
Custom field	Destination field or label	transform	Map type, options, and null values.
Comment or update	Destination comment or archived context	transform	Preserve author and timestamp when supported.
Attachment	Destination attachment or durable link	transform	Copy the binary and verify ordinary-user access.

04Before you begin

Make the move recoverable.

Backup procedure

Create the source-of-truth backup

Preserve GitHub Issues data, configuration, and operating evidence before any destination write.

Export all available GitHub Issues projects, work items, comments, files, users, fields, and settings.
Capture project structure, statuses, permissions, templates, automations, integrations, and active schedules.
Record counts by project, state, owner, and item type.
Hash raw exports and transform working copies only.

Proof to capture: A signed manifest reconciles every scoped record class, runtime dependency, export file, count, and hash.

Transformation · Migration workbook

Work hierarchy and state map

Preserve ownership and workflow meaning.

Inventory source values and exceptions.
Define explicit destination mappings.
Reject unmapped critical records.

Proof to capture: Save the input, output, command or tool settings, warnings, and final item counts.

Transformation · CSV or API transformer

Destination import files

Create deterministic users, work items, fields, and relationships.

Normalize encoding, dates, identifiers, and blanks.
Run a representative pilot.
Reconcile accepted, rejected, and transformed rows.

Proof to capture: Save the input, output, command or tool settings, warnings, and final item counts.

05Handle with care

The things most likely to hurt.

These are operating limits. Treat every “Stop if” condition as a blocked migration, not a suggestion.

Mapping

Hierarchy or status changes meaning

criticalpossible likelihood

Work appears in the wrong team, project, or workflow state.

Consequence: Teams lose ownership and act on the wrong priorities.
Mitigation: Approve mappings with project owners before bulk import.

Stop if: A critical state or owner has no deterministic destination.

Import

Private work becomes visible

criticalpossible likelihood

Imported containers inherit broader destination access.

Consequence: Confidential projects or client work is exposed.
Mitigation: Create and test access before inviting users.

Stop if: An unauthorized test user can open restricted work.

Cutover

Both tools create actions

criticalpossible likelihood

Source rules and destination automations both notify or update work.

Consequence: Tasks drift and people receive duplicate actions.
Mitigation: Freeze source automations and enable replacements one at a time.

Stop if: Any unapproved source writer remains active.

06Precise timeline

Do the work in this order.

Estimate forUp to 100 projects, 100,000 work items, and 500 users

Total elapsed8–18 business days

Active work35–72 hours

BufferAdd time for large exports, unsupported GitHub Issues features, destination limits, identity exceptions, regulated data, or strict downtime requirements.

Days 1–3Inventory and decisions2–3 days

Days 3–5Backup and reconcile1–3 days

Days 5–12Map and pilot3–8 days

Days 10–20Final delta and switch1–5 days

Days 12–40Observe and close3–10 days

1
Days 1–3 · inventory
Inventory and decisions
6–12 hours active2–3 days elapsedOwner review waiting
- Inventory GitHub Issues data, features, users, domains, and integrations.
- Approve scope, owners, mappings, and exclusions.
Depends on: GitHub Issues and Linear administrator access
Stop / go checkpoint
Export?
Go when: Every critical item has an owner and disposition.
Stop when: Consent, billing, access, or system ownership is unclear.
2
Days 3–5 · backup
Backup and reconcile
5–10 hours active1–3 days elapsedExport processing waiting
- Create immutable exports and configuration evidence.
- Reconcile counts, totals, and hashes.
Depends on: Approved inventory
Stop / go checkpoint
Transform?
Go when: Source totals and export manifests agree.
Stop when: Any critical dataset or configuration is absent.
3
Days 5–12 · pilot
Map and pilot
10–35 hours active3–8 days elapsedDestination processing and review waiting
- Configure Linear and transform representative data.
- Run a pilot containing normal records and every critical edge case.
Depends on: Verified backup
Stop / go checkpoint
Scale?
Go when: Pilot mappings, behavior, access, and evidence pass.
Stop when: Any critical check fails or produces unexplained variance.
4
Days 10–20 · cutover
Final delta and switch
5–25 hours active1–5 days elapsedDNS, import, or sync propagation waiting
- Freeze production writes in GitHub Issues.
- Apply the final delta, switch ownership, and run blocking checks.
Depends on: Passed pilot and approved rollback
Stop / go checkpoint
Open production?
Go when: Counts reconcile and one destination system owns production.
Stop when: A source writer remains active or a blocking check fails.
5
Days 12–40 · observe
Observe and close
3–18 hours active3–10 days elapsedOperating-cycle evidence waiting
- Monitor one complete operating cycle.
- Sign the verification report and close rollback only after stability.
Depends on: Verified cutover
Stop / go checkpoint
Close rollback?
Go when: No trigger occurs during the agreed observation period.
Stop when: Data, access, delivery, routing, or business results regress.

07The point of change

Cut over with a way back.

Go live

Cutover

Make Linear the only production system without losing the final GitHub Issues delta.

Recommended window: A low-volume weekday morning with platform, data, DNS, and business owners available.

Freeze production writes and scheduled actions in GitHub Issues.
Export, transform, and reconcile the final delta.
Apply the approved delta to Linear.
Switch domains, forms, integrations, sending, or sync ownership as applicable.
Run every blocking verification check and keep the source intact.

Proof to capture: Linear owns production, totals reconcile, and every blocking check has durable evidence.

Return to safety

Rollback

Return production ownership to GitHub Issues without losing destination-era changes.

Deadline: Within seven days and before source data, plans, credentials, domains, or billing are changed.

Stop new writes and scheduled actions in Linear.
Restore the prior GitHub Issues routing, forms, integrations, sending, or sync ownership.
Export the Linear post-cutover delta.
Review and apply safe destination-era changes to GitHub Issues.
Run the same blocking checks against the restored source.

Proof to capture: GitHub Issues again owns production with current data and no duplicate destination action.

Rollback immediately when

Unexplained critical count or value variance
Missing or exposed critical data
Duplicate production action
Failed access, routing, delivery, or integration check
A critical feature has no safe destination replacement

08Verification report

Prove the migration worked.

Every blocking check must pass. Capture the evidence before cleanup begins.

ID	Check	Method	Expected result	Evidence
`V-01`Blocking	Work-item reconciliation	Compare counts by project, state, owner, and item type.	Every scoped item is accounted for.	Count ledger.
`V-02`Blocking	Project and workflow mapping	Inspect each destination team, project, grouping, and status.	All mappings match the signed model.	Hierarchy report.
`V-03`Blocking	Task value parity	Compare 30 stratified work items.	Critical text, fields, dates, and estimates match.	Field comparison.
`V-04`Blocking	Ownership and guests	Test active, inactive, internal, and external identities.	Assignments and access match policy.	User matrix.
`V-05`Blocking	Subtasks and dependencies	Query representative parent, child, blocked, and related work.	No unexplained orphan or flattened critical link.	Relationship report.
`V-06`Blocking	Attachment access	Open representative files as ordinary users.	Required files load without source-only access.	Attachment log.
`V-07`Blocking	Recurring and connected actions	Run controlled work through every approved rule.	One correct destination action with no source duplicate.	Automation log.
`V-08`Blocking	Single work system	Inspect source and destination writers and team process.	Linear alone owns active work.	Cutover checklist.

09Post-migration cleanup

Remove the scaffolding safely.

Safe after: One complete operating cycle, at least seven stable days, and owner sign-off on every blocking check.

Create final GitHub Issues exports and archive verification evidence.
Revoke temporary credentials, API keys, webhooks, and elevated roles.
Remove obsolete embeds, forms, jobs, integrations, and DNS records.
Keep the source intact through the approved retention window.
Cancel paid plans only after billing, legal, and recovery review.
Schedule the next Linear backup, access, and migration-playbook review.

Sources and maintenance

Built to be reviewed.

Tested 2026-07-19. Next scheduled review: 2026-10-19.

GitHub Issues: official migration documentationAccessed 2026-07-19
Linear: official migration documentationAccessed 2026-07-19

Know the shape of the move.

This timeline assumes

What survives the move.

Where each thing goes.

Make the move recoverable.

Create the source-of-truth backup

Work hierarchy and state map

Destination import files

The things most likely to hurt.

Hierarchy or status changes meaning

Private work becomes visible

Both tools create actions

Do the work in this order.

Inventory and decisions

Export?

Backup and reconcile

Transform?

Map and pilot

Scale?

Final delta and switch

Open production?

Observe and close

Close rollback?

Cut over with a way back.

Cutover

Rollback

Prove the migration worked.

Remove the scaffolding safely.

Built to be reviewed.