# Restore

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.

## Learn More

* [Linear Backup Contents](https://docs.cloudback.it/linear/backup-contents) - What data is in each backup
* [Restoring a Backup](https://github.com/cloudback/docs-internal/blob/docs/data-restoration/restoring-a-backup.md) - General restore documentation
* [Bulk Restore](https://github.com/cloudback/docs-internal/blob/docs/data-restoration/bulk-restore.md) - Restoring multiple items at once