Restore

Learn how to restore Linear workspace data from a Cloudback backup, including the authorization flow, empty workspace requirement, and supported entities.

Cloudback can restore your Linear workspace data from any backup archive. This guide explains the restore process, requirements, and what gets restored.

Overview

Restoring a Linear workspace involves:

Authorizing a separate restore OAuth token (with write permissions)
Preparing the target workspace (must be empty or cleaned)
Selecting the target workspace
Executing the restore - Cloudback recreates all entities in dependency order

Prerequisites

A successful backup archive of a Linear workspace
A target Linear workspace to restore into (can be the same workspace or a different one)
You must be an admin or owner of the target workspace

Important: The target workspace must be empty before restore can proceed. See Step 3: Verify Workspace Status below.

Step-by-Step Restore Process

Step 1: Initiate Restore

Navigate to your workspace in the Cloudback dashboard
Open the Backups tab and find the backup you want to restore from
Click the Restore button

Alternatively, use the Restore now button on the workspace details page header.

Step 2: Authorize Restore Access

Cloudback requires a separate OAuth authorization for restore operations, because restoring data requires write permissions that are not granted during the initial backup setup.

A popup window opens for Linear OAuth authorization:

Scopes requested: read, write, issues:create, comments:create, initiative:write
Purpose: Grants Cloudback permission to create issues, projects, comments, and other entities in the target workspace

Click Authorize to proceed.

Step 3: Verify Workspace Status

After authorization, Cloudback checks whether the target workspace is empty. The UI verifies:

No projects exist
No custom views exist
No more than one team (the default team)

Additionally, when the restore starts, Cloudback verifies that no labels exist in the workspace. If labels are present, the restore is rejected with an error.

Why must the workspace be empty? Restoring into a workspace with existing data could create conflicts - duplicate labels, conflicting issue numbers, and broken references. The empty workspace requirement ensures a clean restore without data corruption.

Step 4: Confirm and Start

The target workspace is already selected during the authorization step. Cloudback uses the workspace's default team to receive all team-specific data. Click Start Restore to begin.

Step 5: Execute Restore

Click Restore to begin. The restore process runs in the background:

Embedded files are uploaded first (images and attachments from content fields)
Teams are created with their settings and members
Labels and project labels are restored
Projects with external links and milestones
Cycles per team
Initiatives with project links and external links
Issues (first pass: most issues, sorted so parents are created before children)
Project updates and initiative updates
Comments (with threading and resolution support)
Issues (second pass: issues that reference comments)
Issue relations (blocks, duplicates, relates-to)
Documents, attachments, custom views, and templates

The restore may take several minutes for large workspaces.

What Gets Restored

Fully Restored Entities

Entity	Details
Teams	Name, settings, cycle configuration, members
Issues	Title, description, priority, assignee, labels, state, dates, parent-child hierarchy
Comments	Body text, threading (parent/reply), resolution status
Projects	Name, description, content, lead, members, external links, status
Cycles	Name, dates, progress, team association
Documents	Title, content, project/initiative/issue associations
Initiatives	Name, description, content, owner, external links, project links
Templates	Issue, project, and document templates with template data
Labels	Issue labels and project labels with hierarchy
Custom Views	Saved filters and views
Workflow States	Mapped per team from backup to target workspace
Project Milestones	Name, target date, project association
Issue Relations	Blocks/blocked-by, duplicates, relates-to links
Project Updates	Status updates with health indicators
Initiative Updates	Status updates with health indicators
Attachments	Metadata and references
Embedded Files	Re-uploaded with URL rewriting across all content fields

User Mapping

During restore, Cloudback maps users from the backup to the target workspace:

Users are matched by email address
If a user exists in the target workspace with the same email, their actions (assignee, creator, commenter) are attributed correctly
If a user does not exist in the target workspace, their actions are attributed to the Cloudback app identity

Reference Rewriting

Cloudback automatically rewrites internal references during restore:

Issue identifiers: e.g., ENG-123 in the source becomes CLOUD-45 in the target
Linear URLs: Links to issues, projects, and documents are updated to point to the new entities
Embedded file URLs: uploads.linear.app URLs are replaced with new upload URLs after re-uploading

Known Limitations

Cannot Rename Default Team

Linear's API (actor=application OAuth) does not permit renaming teams. The default team in the target workspace retains its original name, even if the backup had a different team name.

Free Plan Limits Active Issues

Linear's Free plan allows 250 active issues per workspace. If the target workspace is on that plan and the backup holds more active issues than the limit, Linear refuses the issues above it. Everything else still restores, and the restore report lists what was left out.

Cloudback warns you before the restore starts when a selected backup exceeds the limit. To restore the whole workspace, upgrade the target workspace to a paid Linear plan first.

Learn More

Linear Backup Contents - What data is in each backup
Restoring a Backup - General restore documentation
Bulk Restore - Restoring multiple items at once