# Restoring a Backup

Cloudback allows you to restore your backups to any supported platform. You can also perform cross-platform restores between GitHub and GitLab.

All restore operations - whether for a single item or multiple items - use the same **Restore Wizard**. The only difference is how you trigger it and how many items are selected. For restoring multiple items at once, see [Bulk Restore](https://docs.cloudback.it/data-restoration/bulk-restore).

## Platform-Specific Restore Guides

For detailed information about what gets restored, platform-specific requirements, and entity mapping for each platform, see:

* [GitHub: Restoring Data](https://docs.cloudback.it/github/restore) - restore application, cross-account restore, source restrictions, restored entities
* [Azure DevOps: Restoring Data](https://docs.cloudback.it/azure-devops/restore) - OAuth authorization, restored entities, limitations
* [Linear: Restoring Data](https://docs.cloudback.it/linear/restore) - empty workspace requirement, OAuth scopes, entity restore order, reference rewriting
* [GitLab: Restoring Data](https://docs.cloudback.it/gitlab/restore) - OAuth scopes, namespace selection, ID mapping, restored entities

## Initiating a Restore

There are two ways to start the Restore Wizard:

### From the Repository Details Page

Open the Cloudback Dashboard and navigate to the repository/workspace details page. Open the **Backups** tab, find the backup you want to restore, and click the **Restore** icon:

![Restore a backup from backups list](https://2781059148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQEI7SjBF2CddqNXZpCoE%2Fuploads%2Fgit-blob-972ffd4e5dd41fe65da260aa821e175aaaeafcce%2Frepository-details-backups-tab.png?alt=media)

### From the Dashboard Toolbar

On the Cloudback Dashboard, select one or more items using the checkboxes, then click the **Restore** button in the toolbar. Selecting a single item starts a single restore; selecting multiple items starts a [Bulk Restore](https://docs.cloudback.it/data-restoration/bulk-restore):

![Restore a backup from dashboard](https://2781059148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQEI7SjBF2CddqNXZpCoE%2Fuploads%2Fgit-blob-6ebfaf252c2bb4fa9a723f142f30e76a35a3f209%2Fbackup-restore-from-dashboard.png?alt=media)

## Restore Permissions

Backups require only read access, but restores need write access. Cloudback uses **separate integrations** for backup and restore, following the principle of least privilege. Write permissions are requested only when you initiate a restore:

{% tabs %}
{% tab title="GitHub" %}
The [Cloudback Backup Application](https://github.com/apps/cloudback) has read-only access. For restores, you need to install the separate [Cloudback Restore Application](https://github.com/apps/cloudback-restore) which has read and write access. You can uninstall it after the restore is complete. See [GitHub: Restoring Data](https://docs.cloudback.it/github/restore) for details.
{% endtab %}

{% tab title="Azure DevOps" %}
If this is your first time restoring to an organization, you will be prompted to grant Cloudback write access via a separate OAuth authorization. You can revoke access after the restore is complete. See [Azure DevOps: Restoring Data](https://docs.cloudback.it/azure-devops/restore) for details.
{% endtab %}

{% tab title="Linear" %}
Linear restore requires a separate OAuth authorization with write permissions (scopes: `read`, `write`, `issues:create`, `comments:create`, `initiative:write`). A popup guides you through authorization when you initiate the restore.

> **Important**: The target Linear workspace must be **empty** before restore can proceed - no projects, no custom views, no more than one team, and no labels. Create a new workspace at [linear.app/join](https://linear.app/join) before starting the restore. See [Linear: Restoring Data](https://docs.cloudback.it/linear/restore) for details.
> {% endtab %}

{% tab title="GitLab" %}
GitLab restore requires a separate OAuth authorization with `api` scope (full read-write access). You will be prompted to authorize when you initiate the restore. See [GitLab: Restoring Data](https://docs.cloudback.it/gitlab/restore) for details.
{% endtab %}
{% endtabs %}

## Encrypted Backups

If a backup is protected by an [RSA Lockbox](https://docs.cloudback.it/encryption-management/rsa-lockbox) encryption key, the Restore Wizard includes an additional step that prompts you to paste your RSA private key. Cloudback decrypts the archive password in memory and discards your private key immediately.

For bulk restores with multiple encryption providers, the wizard asks for each provider's private key once.

Backups using the built-in **Secure Random Key** provider do not require extra input during restore.

## Restore Wizard

The Restore Wizard guides you through the same steps regardless of whether you're restoring one item or many. The number of steps depends on whether you're restoring within the same platform or across platforms.

### Azure DevOps and Linear Restore

The restore wizard has 3 steps:

1. **Select source**: Choose the backup(s) you want to restore.
2. **Select target**: Choose where to restore.
3. **Restoring**: Monitor the restoration progress.

### GitHub and GitLab Restore

GitHub and GitLab restores always include a platform selection step, enabling cross-platform restore between the two. The restore wizard has 4 steps:

1. **Select source**: Choose the backup(s) you want to restore.
2. **Select platform**: Choose the target platform (GitHub or GitLab).
3. **Select target**: Choose the target account/namespace.
4. **Restoring**: Monitor the restoration progress.

For details on cross-platform data conversion, see [Cross-Platform Restore](https://docs.cloudback.it/data-restoration/cross-platform-restore).

### Step 1: Select Source

Choose the backup you want to restore from the list of available backups. For bulk restores, you can change the backup snapshot for each item using the dropdown. Click **Next**:

![Select a backup](https://2781059148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQEI7SjBF2CddqNXZpCoE%2Fuploads%2Fgit-blob-f086cf75aca15c2a9af408c30cdff575dce51add%2Fbackup-restore-select-source.png?alt=media)

### Step 2: Select Target

Choose where to restore the backup:

{% tabs %}
{% tab title="GitHub" %}
Enter the target GitHub account name and click **Start Restore**. The repository name and visibility are carried over from the backup automatically.
{% endtab %}

{% tab title="Azure DevOps" %}
Enter the target organization name and project name, then click **Start Restore**.

> **Note**: A new repository will be created in the target project. You cannot restore to an existing repository.
> {% endtab %}

{% tab title="Linear" %}
Follow the guided steps to authorize the Cloudback Restore app in the target workspace via OAuth. Cloudback verifies the workspace is empty before proceeding. If the workspace has existing data, you will need to create a new empty workspace first. There is no manual team selection - Cloudback uses the workspace's existing team automatically.
{% endtab %}

{% tab title="GitLab" %}
Select the target namespace (personal account or group) by clicking on it from the list of connected GitLab accounts. The project name is carried over from the backup automatically.
{% endtab %}
{% endtabs %}

![Select repository for restore](https://2781059148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQEI7SjBF2CddqNXZpCoE%2Fuploads%2Fgit-blob-3da091c1a4db872f6425f0fb870914c78949bf05%2Fbackup-restore-select-target.png?alt=media)

### Step 3: Restoring

The restore process starts and you can monitor the progress. You can wait for completion or return to the dashboard - the restore continues in the background. Once complete, you will see a notification with the restore status.

{% tabs %}
{% tab title="GitHub" %}
The restoration includes source code (via `git push --mirror`), branches, tags, and backed-up metadata: issues (with issue types and sub-issues), issue comments, milestones, labels, collaborators, commit comments, unmerged pull requests, projects (legacy and ProjectV2), releases (with assets), webhooks, and repository settings (description, homepage, merge methods, topics).

> **Note**: Merged pull requests are skipped during restore. Wiki pages are not restored.
> {% endtab %}

{% tab title="Azure DevOps" %}
The restoration includes source code (via `git push --mirror`), pull requests with review threads and comments, labels, and attachments. See [Azure DevOps: Restoring Data](https://docs.cloudback.it/azure-devops/restore) for details and limitations.
{% endtab %}

{% tab title="Linear" %}
The restoration includes teams, labels, projects (with milestones and external links), cycles, initiatives, issues (with parent-child hierarchy), comments (with threading), documents, attachments, custom views, templates, issue relations, project/initiative updates, and embedded files (re-uploaded with URL rewriting). See [Linear: Restoring Data](https://docs.cloudback.it/linear/restore) for the full entity list and restore order.
{% endtab %}

{% tab title="GitLab" %}
The restoration includes the Git repository (via `git push --mirror`), project settings, labels, milestones, issues (with time tracking), issue comments, issue links, merge requests, MR comments, and boards. See [GitLab: Restoring Data](https://docs.cloudback.it/gitlab/restore) for details.
{% endtab %}
{% endtabs %}

## Viewing the Restored Repository

Once complete, view the restored repository by opening the repository details page, clicking the **Restores** tab, and clicking the repository link:

![Open restored repository from restores list](https://2781059148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQEI7SjBF2CddqNXZpCoE%2Fuploads%2Fgit-blob-d7eb6d5cedfcd4de4ec2f4175d14a41a1aaccb45%2Frepository-details-restores-tab.png?alt=media)

## Learn More

* [Bulk Restore](https://docs.cloudback.it/data-restoration/bulk-restore)
* [GitHub: Restoring Data](https://docs.cloudback.it/github/restore)
* [Azure DevOps: Restoring Data](https://docs.cloudback.it/azure-devops/restore)
* [Linear: Restoring Data](https://docs.cloudback.it/linear/restore)
* [GitLab: Restoring Data](https://docs.cloudback.it/gitlab/restore)
* [Cross-Platform Restore](https://docs.cloudback.it/data-restoration/cross-platform-restore)
* [Encryption Overview](https://docs.cloudback.it/encryption-management/encryption-overview)
* [Download Backups](https://docs.cloudback.it/data-restoration/download-backups)