Restore

Learn how to restore GitLab project data from a Cloudback backup, including repository, issues, merge requests, labels, milestones, and boards.

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 - What data is in each backup

• Cross-Platform Restore - GitHub ↔ GitLab bidirectional restore

• Restoring a Backup - General restore documentation