> For the complete documentation index, see [llms.txt](https://docs.cloudback.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloudback.it/gitlab/restore.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.