Restore Wizard
The Restore Wizard guides you through restoring a backup snapshot to a new GitHub, GitLab or Bitbucket repository in four steps.
Step 1: Select Target Account
Choose the GitHub organization, GitHub personal account, GitLab account or Bitbucket account where the restored repository will be created.
- The dropdown lists every account you can restore to. Each entry shows the account name with a provider badge (GitHub, GitLab or Bitbucket).
- GitLab targets can be GitLab.com, connected with OAuth, or a Self-Managed GitLab instance, connected with its address and an access token. If your GitLab account is not listed, connect it first as described in Connecting GitLab.
- If your GitHub or Bitbucket target account is not listed, click Install for New Organization and pick a provider:
- GitHub: installs the GitSec Restore App on the organization or personal account you authorize.
- Bitbucket: connects your Bitbucket account through an authorization popup.
For GitHub targets, the Restore App requires write access to create or push to repositories. This is a separate app from the Backup App used for read-only operations.
Step 2: Select Backup Source
Choose which backup snapshot to restore from.
- A dropdown shows the backup snapshots for the selected repository, loaded 10 at a time, scroll to the bottom of the list to load more.
- Each snapshot displays the repository full name, the execution ID, the completion timestamp, and a status badge (Completed, Failed, In Progress, Partially Completed, Pending, or Cancelled).
- Older backups that do not include source code are not listed, because they cannot be restored.
- Select the snapshot you want to restore.
Step 3: Configure Target Repository
Set up the target repository for the restore:
| Field | Description |
|---|---|
| Repository Type | Currently only New is available. Every restore creates a new repository. The Existing option is disabled and marked Coming Soon. |
| Workspace | Bitbucket targets only. Select the Bitbucket workspace where the new repository will be created. This field is required. |
| Target namespace | GitLab targets only. Select where the new project will be created: Personal (your personal namespace) or a group you can create projects in. |
| Repository Name | The name of the new repository (maximum 64 characters). The name must be unique in the target account, workspace or namespace. |
| Description | An optional description for the repository. |
| Visibility | Private or Public. For GitHub targets, Internal is also offered. |
| Scopes | Select which scopes to restore. |
Internal visibility is a GitHub Enterprise feature available only for organization accounts. If the target account is a personal user account, please select Private or Public. If you choose Internal anyway, the wizard shows a warning and the repository is created as Private instead.
Scopes
What can be restored depends on the target provider:
- GitHub: Code & Commits, Pull Requests (with comments and reactions), Issues, Releases and Collaborators.
- GitLab: Code & Commits, Repository Metadata, Pull Requests (restored as merge requests with their comments), Issues, Releases and Collaborators.
- Bitbucket: Code & Commits, Repository Metadata and Pull Requests (with comments).
When you restore into a different provider than the backup was taken from:
- Collaborators can only be restored to the provider they were backed up from.
- Repository Metadata, Pull Requests, Issues and Releases from another provider can only be restored into a GitLab target.
- Repository metadata backed up from GitHub is not restored into another provider.
Only the scopes present in the selected backup snapshot are shown; scopes the snapshot does not contain are hidden. For the full scope table, see What Can Be Restored?.
Step 4: Review and Confirm
Review all restore details before starting:
- Source Details: The target account and the backup snapshot ID.
- Target Repository: Name, description, and visibility settings.
- Scopes: The scopes that will be restored.
Each section has an Edit button so you can go back and modify settings.
When ready, click Start Restore to begin the restore process.
After the Restore
Once the restore completes successfully, you will see a confirmation screen. The restored repository will be available in the target GitHub organization, GitLab namespace or Bitbucket workspace with the configured settings.
You can follow a running restore step by step in the Background jobs panel at the bottom right of any page, and find it afterwards on the Activity page or the Restores page in the sidebar.