Restore Overview
GitSec's restore feature lets you recover a backup snapshot to a new repository on GitHub, GitLab or Bitbucket. Restoring into an existing repository is not available yet.
Restore App vs. Backup App
When restoring to GitHub, GitSec uses two separate GitHub Apps:
| App | Permissions | Purpose |
|---|---|---|
| Backup App | Read-only | Reads your repository data to create backups. |
| Restore App | Read & Write | Creates or pushes to repositories during a restore. |
The Restore App is separate because restoring requires write access to create new repositories or push code. This separation follows the principle of least privilege, the Backup App never has write access to your repositories.
The Restore App is installed on-demand when you start your first restore. You will be prompted to install it on the target GitHub organization during the restore wizard.
When installing the Restore App, you must select All repositories: not "Only select repositories". The restore process requires access to all repositories in the target organization to function correctly. If you select specific repositories only, the restore will fail.
When restoring to Bitbucket, there is no GitHub App to install. Instead, you select a target workspace from your connected Bitbucket account during the restore wizard.
When restoring to GitLab, there is no app to install either. You can restore to GitLab.com, connected with OAuth, or to a Self-Managed GitLab instance, connected with its address and an access token. During the restore wizard you choose the Target namespace: your personal namespace or a group you can create projects in. See Connecting GitLab for how to connect either one.
What Can Be Restored?
What you can restore depends on the provider you restore to:
| Scope | GitHub | GitLab | Bitbucket |
|---|---|---|---|
| Code & Commits (including tags) | ✓ | ✓ | ✓ |
| Repository Metadata | — | ✓ (description, default branch) | ✓ (description, website, fork policy, language) |
| Pull Requests | ✓ with comments and reactions | ✓ as merge requests with their comments | ✓ with comments (reactions are not restored) |
| Issues | ✓ | ✓ | — |
| Releases | ✓ | ✓ | — |
| Collaborators | ✓ | ✓ | — |
You can also restore a backup into a different provider than the one it was taken from. In that case:
- 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. For example, restoring a GitHub or Bitbucket backup into GitLab carries over its pull requests, issues and releases.
- Repository metadata backed up from GitHub is not restored into another provider.
The restore wizard only offers the scopes that are present in the selected backup snapshot; scopes the snapshot does not contain are hidden. Older backups that do not include source code do not appear in the restore flow.
Global Restores Page
Navigate to Restores in the sidebar to see all restore operations, whatever their status. The table shows:
- Target Repository: The repository the backup was restored to, shown with its Git provider icon (GitHub, GitLab or Bitbucket).
- Source Repository: The repository the backup was originally taken from, also shown with its provider icon.
- Scopes: The scopes that were restored (for example, Code & Commits).
- Start Date / Finish Date: When the restore started and finished.
- Elapsed Time: Total duration of the restore.
- Size: The total size of the restored data.
The page also gives you tools to find and track restores:
- Search: Filter the list by target repository name.
- Status: Show only restores in the selected statuses: Pending, In Progress, Completed, Partially Completed, Failed, Cancelled or Paused.
- Date range: Narrow the list to a date range picked on a calendar.
- Pagination: Move between pages and change how many rows are shown per page.
- Refresh: Click the refresh button at the top right of the page to reload the list on demand.
Viewing Restore Details
The full details of a restore execution are available on the Activity page. Open any restore row there to see:
| Field | Description |
|---|---|
| Execution ID | The unique identifier of this restore execution, with a copy button next to it. |
| Correlation ID | An identifier that links together all events belonging to this restore, with a copy button next to it. |
| Source Repository | A link to the repository the backup was taken from. |
| Target Repository | The full name of the repository the backup is restored to. |
| Created At / Started At / Completed At | Timestamps for when the restore was created, started, and completed. |
| Duration | The total run time of the restore, shown once it is available. |
| Scope Statuses | Each scope in the restore, listed with its own status and message. |
| Failure Reason | For failed or partially completed restores, a plain-language explanation of what went wrong. |
When contacting support about a restore, include the Execution ID and Correlation ID: use the copy buttons next to each value to grab them exactly.
Cancelling a Restore
You can cancel a restore that is still running. For example, one that appears stuck or was started by mistake:
- Open the Background jobs panel at the bottom right of the screen. It is available on every page.
- Find the running restore and click its cancel icon.
GitSec shows a Cancelling the run notification, the restore stops, and its status changes to Cancelled. Restores that have already finished cannot be cancelled.
Starting a Restore
There are two ways to start a restore:
- From the Backup Snapshots page: Click the restore button on any backup row.
- From a repository's Restore tab: Select a backup and start the wizard.
Both methods launch the Restore Wizard.
If you store backups in your own storage and cannot use GitSec, you can also restore the source code yourself. See Restore from Your Own Storage.