Restoring a Backup
Step-by-step guide to restoring your Cloudback backups to GitHub, Azure DevOps, Linear, or GitLab, including cross-platform restore between GitHub and GitLab.
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.
Platform-Specific Restore Guides
For detailed information about what gets restored, platform-specific requirements, and entity mapping for each platform, see:
GitHub: Restoring Data - restore application, cross-account restore, source restrictions, restored entities
Azure DevOps: Restoring Data - OAuth authorization, restored entities, limitations
Linear: Restoring Data - empty workspace requirement, OAuth scopes, entity restore order, reference rewriting
GitLab: Restoring Data - 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:
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:
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:
The Cloudback Backup Application has read-only access. For restores, you need to install the separate Cloudback Restore Application which has read and write access. You can uninstall it after the restore is complete. See GitHub: Restoring Data for details.
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 for details.
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 before starting the restore. See Linear: Restoring Data for details.
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 for details.
Encrypted Backups
If a backup is protected by an 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:
Select source: Choose the backup(s) you want to restore.
Select target: Choose where to restore.
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:
Select source: Choose the backup(s) you want to restore.
Select platform: Choose the target platform (GitHub or GitLab).
Select target: Choose the target account/namespace.
Restoring: Monitor the restoration progress.
For details on cross-platform data conversion, see 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:
Step 2: Select Target
Choose where to restore the backup:
Enter the target GitHub account name and click Start Restore. The repository name and visibility are carried over from the backup automatically.
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.
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.
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.
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.
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.
The restoration includes source code (via git push --mirror), pull requests with review threads and comments, labels, and attachments. See Azure DevOps: Restoring Data for details and limitations.
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 for the full entity list and restore order.
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 for details.
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:
Learn More
Last updated
Was this helpful?