# Restore

Cloudback can restore your GitHub repository data from any backup archive. This includes the full Git repository, issues, pull requests, releases, labels, milestones, projects, and more. You can restore to the same account, a different account, or even from a non-GitHub backup (GitLab) via [Cross-Platform Restore](https://github.com/cloudback/docs-internal/blob/docs/data-restoration/cross-platform-restore.md).

## Overview

Restoring a GitHub repository involves:

1. **Installing** the Cloudback Restore Application (separate from the backup app)
2. **Selecting** the target account and repository name
3. **Executing** the restore - Cloudback creates the repository, pushes the code, and restores all metadata

## Prerequisites

* A successful backup archive (from GitHub or GitLab)
* A **target GitHub account** (personal or organization) to restore into
* The [Cloudback Restore Application](https://github.com/apps/cloudback-restore) installed on the target account

## Restore Application

Cloudback uses two separate GitHub Apps following the principle of least privilege:

* **Backup App** (read-only) - installed during setup, used for daily backups
* **Restore App** (read-write) - installed separately, only when you need to restore

### Installing the Restore Application

1. Go to the [Cloudback Restore Application](https://github.com/apps/cloudback-restore/installations/select_target) installation page.
2. Select the target GitHub account (organization or user).
3. Grant the requested permissions - read and write access to code and metadata.

> **Security Tip:** The Restore Application is only needed for the duration of the restore. Consider uninstalling it from your target account once the restore is complete.

## Step-by-Step Restore Process

### Step 1: Initiate Restore

1. Navigate to your repository in the Cloudback dashboard
2. Open the **Backups** tab and find the backup you want to restore
3. Click the **Restore** button

Alternatively, select one or more repositories on the dashboard and click **Restore** in the toolbar to start a [Bulk Restore](https://github.com/cloudback/docs-internal/blob/docs/data-restoration/bulk-restore.md).

### Step 2: Select Target

1. Enter the target GitHub account name (personal or organization)
2. Click **Start Restore**

The repository name and visibility are carried over from the backup automatically.

### Step 3: Execute Restore

Click **Restore** to begin. The process runs in the background - you can close the page and return later. A notification will appear when the restore completes.

## What Gets Restored

| Entity                  | Details                                                                                                              |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Repository**          | All branches, tags, refs via `git push --mirror`, plus LFS objects                                                   |
| **Issues**              | Title, body, state, labels, milestone, assignee, issue types, sub-issues                                             |
| **Issue Comments**      | Body, author, dates                                                                                                  |
| **Pull Requests**       | Unmerged PRs with title, body, state, labels, milestone, branches, reviews, review comments, and requested reviewers |
| **Commit Comments**     | Comments on specific commits                                                                                         |
| **Milestones**          | Title, description, state, due date                                                                                  |
| **Labels**              | Name, color, description                                                                                             |
| **Releases**            | Tag, name, body, assets (uploaded files)                                                                             |
| **Projects**            | ProjectV2 in current backups; classic projects from older archives                                                   |
| **Collaborators**       | Repository collaborator invitations                                                                                  |
| **Webhooks**            | Webhook URLs and configuration                                                                                       |
| **Repository Settings** | Description, homepage, merge methods, topics                                                                         |

### Not Restored

* **Merged pull requests** - skipped during restore (the commits are already in the repository history)
* **Wiki pages** - not restored
* **GitHub Actions workflows** - restored as files in the repository, but workflow run history is not restored

## Cross-Account Restore

You can restore backups to a **different** GitHub account than the one that created the backup. This is useful for:

* Migrating repositories between organizations
* Disaster recovery to a standby account
* Restoring data to an account that doesn't have Cloudback installed
* Restoring between GitHub Enterprise Managed User (EMU) and non-EMU accounts

The process is the same as a standard restore - just select a different target account in Step 2. The Restore Application must be installed on the **target** account.

### Restricting Allowed Source Accounts (Optional)

By default, Cloudback allows restores from any source account. To restrict which source accounts can restore to your organization, create a GitHub Actions organization variable:

1. Navigate to the GitHub settings for your **target organization**
2. Go to **Security > Secrets and variables > Actions**
3. Click the **Variables** tab → **New organization variable**
4. Enter:
   * **Name**: `CLOUDBACK_ALLOWED_RESTORE_SOURCE`
   * **Value**: Source account name(s), each prefixed with the platform. Separate multiple entries with commas.
     * *GitHub source:* `github:source-org-1`
     * *GitLab source:* `gitlab:source-group-1`
     * *Mixed example:* `github:source-org-1,gitlab:source-group-2`
   * **Repository access**: Can be left as "Public repositories"
5. Click **Add variable**

> **Note:** This variable is only checked for **organization** targets. Personal account targets skip this check. Organization **owners** also bypass this check - they can restore from any source without setting the variable.

## Learn More

* [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 repositories at once
* [Cross-Platform Restore](https://github.com/cloudback/docs-internal/blob/docs/data-restoration/cross-platform-restore.md) - GitHub ↔ GitLab bidirectional restore
* [GitHub Backup Contents](https://docs.cloudback.it/github/backup-contents) - What data is in each backup
* [Known Issues](https://github.com/cloudback/docs-internal/blob/docs/troubleshooting-and-support/known-issues.md) - Troubleshooting restore errors