# Restore

Cloudback can restore your GitLab project data from any backup archive. This includes the Git repository, metadata (issues, merge requests, labels, milestones), and board configurations.

## Overview

Restoring a GitLab project involves:

1. **Authorizing** a restore OAuth token (with `api` write scope)
2. **Selecting** the target namespace (personal or group)
3. **Providing** a project name
4. **Executing** the restore - Cloudback creates the project, pushes the repository, and restores all metadata

## Prerequisites

* A successful backup archive of a GitLab project
* A **GitLab.com account** with access to the target namespace
* You must have permission to create projects in the target namespace

## Step-by-Step Restore Process

### Step 1: Initiate Restore

1. Navigate to your GitLab project in the Cloudback dashboard
2. Open the **Backups** tab and find the backup to restore from
3. Click the **Restore** button

### Step 2: Authorize Restore Access

If this is your first restore, Cloudback requests a separate OAuth token with write permissions:

* **Scope requested**: `api` (full read-write access to the GitLab API)
* **Purpose**: Grants Cloudback permission to create projects, push repositories, and create issues/MRs

Click **Authorize** on the GitLab consent page.

> **Why a separate token?** Backup only needs `read_api` scope, but restore needs `api` (full access) to create projects and entities. Keeping these separate follows the principle of least privilege.

### Step 3: Select Target

Choose where to restore the project:

| Target Type            | Description                                                                 |
| ---------------------- | --------------------------------------------------------------------------- |
| **Personal namespace** | Restores under your personal GitLab account (`username/project-name`)       |
| **Group**              | Restores into a GitLab group you have access to (`group-name/project-name`) |

### Step 4: Execute Restore

Click **Restore** to begin. The process runs in the background.

## What Gets Restored

| Entity               | Restored Fields                                                                      |
| -------------------- | ------------------------------------------------------------------------------------ |
| **Repository**       | All branches, tags, refs, LFS objects                                                |
| **Project Settings** | Visibility, features, merge settings, description, topics                            |
| **Labels**           | Name, color, description                                                             |
| **Milestones**       | Title, description, state, dates                                                     |
| **Issues**           | Title, description, state, labels, milestone, assignee, dates, time tracking, weight |
| **Issue Comments**   | Body, author, dates, system/internal flags                                           |
| **Issue Links**      | Type (relates\_to, blocks, is\_blocked\_by)                                          |
| **Merge Requests**   | Title, description, state, branches, labels, milestone, draft                        |
| **MR Comments**      | Body, author, diff positions                                                         |
| **Boards**           | Board lists with label-based columns                                                 |

## ID Mapping

During restore, Cloudback maintains mappings between old and new IDs:

* **Milestone IDs**: Old global ID → new global ID (used in issue/MR milestone references)
* **Issue IIDs**: Old project-scoped IID → new IID
* **MR IIDs**: Old project-scoped IID → new IID

This ensures cross-references between entities are preserved correctly.

## Learn More

* [GitLab Backup Contents](https://docs.cloudback.it/gitlab/backup-contents) - What data is in each backup
* [Cross-Platform Restore](https://github.com/cloudback/docs-internal/blob/docs/data-restoration/cross-platform-restore.md) - GitHub ↔ GitLab bidirectional restore
* [Restoring a Backup](https://github.com/cloudback/docs-internal/blob/docs/data-restoration/restoring-a-backup.md) - General restore documentation