Retiring a self-managed GitLab server: keeping merge request history

What merge request history does a GitLab server hold?#

A GitLab server holds merge request history as several linked records, not one object: the description, threaded discussions anchored to lines of code, system notes, a diff version for every push, approvals and the pipelines that ran against each version. Together they show how a change was proposed, challenged, revised and accepted.

Most of that lives in the PostgreSQL database, but not all of it. Repositories sit in Git storage, uploaded screenshots sit in the uploads directory, and job logs and artifacts often sit in object storage or on a separate disk. Depending on configuration, merge request diffs may also be stored outside the database, which is easy to miss in a backup plan.

Backup, project export or API: which one keeps the review trail?#

The full instance backup and an API pull keep the review trail; a project export keeps the merge requests but flattens their history. GitLab documents that its file export includes repositories, issues with comments, merge requests, labels, milestones, releases, LFS objects and protected branches, but it also warns that export files should not be used for backups and that, after import, merge requests show only the latest diff version and latest pipeline.

That means a migration built on project exports can look complete in the new instance while every earlier review round is gone. The reviewer comment that forced a redesign still appears, but the code it referred to does not. Treat project exports as a way to move active work, and build the archive from the backup and the API.

The shutdown checklist for a self-managed GitLab server#

The shutdown checklist runs from steps that cannot be redone later, such as recording versions and storage paths, to steps that prove the archive works. Keep the server, its admin account and the engineer who knows its quirks available until the last item is signed.

• 1Record the exact GitLab version and edition, the PostgreSQL version, and where repositories, uploads, diffs, artifacts and LFS objects are stored.
• 2Stop new writes by archiving projects or restricting roles, and announce the date after which nothing new will be recorded.
• 3Take the native full backup, copy the configuration and secrets files separately, and checksum every file.
• 4Restore onto an isolated test instance of the same version and open a sample of old merge requests, including some with many review rounds.
• 5Pull every merge request through the API: metadata, discussions, notes, diff versions, approvals and linked issues, keyed by project and merge request ID.
• 6Mirror-clone every repository with all references, including archived projects and personal namespaces that hold company code.
• 7Save job logs and artifacts for release branches and incident pipelines, and keep pipeline metadata for the rest.
• 8Scan the archive for secrets and personal details, rotate any live credential, and record sign-off from engineering, security and counsel before powering off.

Running a long API pull on an old server#

A long API pull on an old GitLab server works best as a resumable job that walks one project at a time and writes raw responses to disk. List the merge requests in each project, then fetch each one's discussions, notes, versions and approvals, and record which IDs finished so a failure restarts where it stopped.

On a self-managed instance the administrators set the rate limits, so the constraint is usually aging hardware rather than policy. Run pulls outside working hours if the server still serves users, and watch database load. If you also use project exports, GitLab's documented defaults allow six project exports per minute per user and one export download per minute per user, and admins can change them.

Check completeness against the instance, not against memory. Compare merge request counts per project with the totals the server reports, spot-check threads with many replies, and keep an index listing project, merge request ID, title, author, dates, state and archive path for each record.

Rights and privacy questions before the server goes off#

Rights and privacy questions on a GitLab archive start with whose code it is. Most repositories hold company-owned work, but services teams sometimes keep customer-owned code in the same instance, and acquired products may carry terms from their previous owner. Flag those projects in the index so they can be handled separately.

On a self-managed server the records sit on your own infrastructure, and Section 8.4 of the GitLab Subscription Agreement version GLSA_01.12.26 v8 states that the customer retains all right, title and interest in its Customer Content, subject to a limited license to GitLab; older versions word this differently, so confirm which version your company signed. Personal details still need care: commit metadata, user tables and review comments carry names and email addresses, and pipeline logs can expose credentials.

Ask counsel whether any project is under a legal hold or contractual retention duty before anything is deleted. Then store the archive encrypted, limit access to a named group, and add it to your retention schedule like any other record system.

Illustrative: a fleet software company switches off its old GitLab#

Illustrative: a fictional fleet maintenance software company ran a self-managed GitLab on an aging virtual machine for most of its history. Engineering moved active projects to a cloud GitLab instance using project exports, and the old server was scheduled for shutdown when the hosting contract ended.

During a final check, the CTO opened an old merge request in the new instance and saw only the final diff. Reviewer comments about a rounding change in service interval calculations pointed at code that no longer appeared. The team paused the shutdown, took a full backup, proved it on a test instance, pulled every merge request through the API and mirror-cloned all repositories, including a retired mobile app.

The verified backup, the API archive and the index now sit in encrypted company storage. When a customer later questioned how service intervals were calculated, engineers traced the answer through the original review rounds instead of reconstructing it from the final code.

How SourceX approaches a retired GitLab archive#

SourceX treats a retired GitLab archive as engineering history whose value depends on links: a merge request tied to the issue that prompted it, the review that shaped it and the release that shipped it. In the Supply step of the SourceX five-step transaction, a company describes versions, years of history and how those records connect; no files are shared at that stage.

If the company proceeds, the Rights, Preparation, Approval and Delivery steps follow, with customer-owned code excluded, secrets and personal details removed, and every release approved by the company. The archive stays in the company's own storage or ships on encrypted drives, and the SourceX Evidence Packet records provenance, licensing rights, permitted use, the privacy record and release authorization.