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:

1. Authorizing a separate restore OAuth token (with write permissions)

2. Preparing the target workspace (must be empty or cleaned)

3. Selecting the target workspace and team

4. 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 Empty Workspace Requirement below.

Step-by-Step Restore Process

Step 1: Initiate Restore

1. Navigate to your workspace in the Cloudback dashboard

2. Open the Backups tab and find the backup you want to restore from

3. 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:

• No projects exist

• No custom views exist

• Exactly one team exists (the default team)

• No labels exist

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: Select Target

Choose the target workspace where data should be restored. The default team in the workspace will receive all team-specific data.

Step 5: Execute Restore

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

1. Embedded files are uploaded first (images and attachments from content fields)

2. Teams are created with their settings and members

3. Labels and project labels are restored

4. Projects with external links and milestones

5. Cycles per team

6. Initiatives with project links and external links

7. Issues (first pass: most issues, sorted so parents are created before children)

8. Project updates and initiative updates

9. Comments (with threading and resolution support)

10. Issues (second pass: issues that reference comments)

11. Issue relations (blocks, duplicates, relates-to)

12. 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.

Learn More

• Linear Backup Contents — What data is in each backup

• Restoring a Backup — General restore documentation

• Bulk Restore — Restoring multiple items at once