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:

Authorizing a restore OAuth token (with api write scope)
Selecting the target namespace (personal or group)
Providing a project name
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

Navigate to your GitLab project in the Cloudback dashboard
Open the Backups tab and find the backup to restore from
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