GitLab

arcula protects GitLab Omnibus in Docker with three resources. They are copied in different ways, and the plan needs all three.

The database is taken by the dump, so gitlab-backup runs with SKIP=db: the database isn't copied twice.

Check the plan

1. Open the server's protection plan.
2. In “Application data”, find “GitLab: repositories and uploads” — in the “everything else” group. It must be ticked, and “How to copy” must show “gitlab-backup”.
3. There, also check the ticks on the GitLab database and on “GitLab: config and secrets”.
4. Save the plan.

Without “GitLab: repositories and uploads”, only the database gets into the backup — repositories and uploads aren't saved. If the resource appeared after the plan had already been confirmed, it has the “new” label. It goes into the backup only once you save the plan.

If “How to copy” says “gitlab-backup — the agent can't do this yet (update it)”, the agent is old, and for now this is a file copy without consistency. See Update agents.

Without gitlab-secrets.json the gitlab-backup archive can't be restored: it holds the GitLab encryption keys. So “GitLab: config and secrets” is a must.

How the backup runs

The agent runs in the GitLab container:

gitlab-backup create BACKUP=arcula-<time> SKIP=db

The archive is moved to /var/opt/gitlab/backups/snapshots/, goes into the backup and is deleted. Archives don't pile up in the GitLab backups directory.

If gitlab-backup fails, this component doesn't get into the backup. The last lines of its output are in the server log.

Restore

You need the same GitLab version and edition (CE or EE) as in the backup. The panel reminds you about this on the server: “Overview” → “Needed for a restore”.

Order: config and secrets, the database, then repositories and uploads.

1. arcula restore

On the new machine — prepare with the recovery kit, as in Restore data. It brings back the project directory, /etc/gitlab with gitlab-secrets.json, volumes and the database from the dump. Check in the report that the database step was done: without the database the archive must not be restored.

arcula doesn't apply the gitlab-backup archive; it extracts it to /var/lib/arcula/restore/<id>/gitlab. Find it:

sudo find /var/lib/arcula/restore -name '*_gitlab_backup.tar'

To get only the archive without touching a running GitLab — the component mode for “GitLab: repositories and uploads”.

2. Start GitLab

cd /opt/gitlab && docker compose up -d

Wait until GitLab is up.

3. Repositories and uploads

Below, the container is called gitlab and the archive is arcula-20261024T120000Z_gitlab_backup.tar. Put in your own:

docker cp /var/lib/arcula/restore/<id>/gitlab/arcula-20261024T120000Z_gitlab_backup.tar gitlab:/var/opt/gitlab/backups/
docker exec gitlab chown git:git /var/opt/gitlab/backups/arcula-20261024T120000Z_gitlab_backup.tar
docker exec gitlab gitlab-ctl stop puma
docker exec gitlab gitlab-ctl stop sidekiq
docker exec -it gitlab gitlab-backup restore BACKUP=arcula-20261024T120000Z SKIP=db
docker exec gitlab gitlab-ctl restart
docker exec gitlab gitlab-rake gitlab:check SANITIZE=true

BACKUP is the archive name without _gitlab_backup.tar. SKIP=db is required: arcula restore has already brought up the database.