# 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](/linear/backup-contents.md) - 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cloudback.it/linear/restore.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.