> For the complete documentation index, see [llms.txt](https://cloudback.it/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cloudback.it/docs/linear/restore.md).

# 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
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 [Step 3: Verify Workspace Status](#step-3-verify-workspace-status) 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. 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:

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.

### 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](/docs/linear/backup-contents.md) - What data is in each backup
* [Restoring a Backup](/docs/data-restoration/restoring-a-backup.md) - General restore documentation
* [Bulk Restore](/docs/data-restoration/bulk-restore.md) - Restoring multiple items at once