# 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](/gitlab/backup-contents.md) - 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cloudback.it/gitlab/restore.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.