Self-Hosted Git Server Backup and Disaster Recovery Guide
Git hostingbackupdisaster recoveryself-hostingForgejoGitea

Self-Hosted Git Server Backup and Disaster Recovery Guide

OOpenDev Forge Editorial Team
2026-11-15
7 min read

A practical checklist for backing up and restoring self-hosted Git repositories, databases, artifacts, configuration, and keys.

A dependable self-hosted Git server backup protects more than repository files. This guide provides a reusable checklist for backing up repositories, databases, artifacts, registries, configuration, and secrets—then testing a full restore against clear recovery objectives.

Overview

A Git server disaster recovery plan should answer two questions: what can be restored, and how quickly can it be restored? A bare copy of Git repositories may preserve source history, but it usually does not recreate users, permissions, pull requests, issues, webhooks, runners, package registries, or application settings.

Start by documenting your deployment. Record whether you run Forgejo, Gitea, GitLab, or another platform; the application version; the operating system; the database engine; storage paths; reverse-proxy settings; external integrations; and the location of encryption keys. Keep this inventory outside the server so it remains available during an outage.

Define two targets before selecting a backup schedule:

  • Recovery point objective (RPO): the maximum acceptable amount of lost change, such as one hour or one day.
  • Recovery time objective (RTO): the target time to make the service usable again.

These targets influence backup frequency, storage design, standby infrastructure, and the amount of restoration testing required. A small team may choose a slower, manual rebuild. A critical internal platform may need automated backups, off-site copies, and a documented replacement environment.

Backup coverage at a glance

Data or dependencyWhy it mattersRecommended treatment
Git repositoriesSource history, branches, tags, and sometimes large-file objectsUse a platform-supported export or repository-level backup, then verify by cloning or inspecting a restored copy.
DatabaseUsers, permissions, issues, merge requests, comments, and application metadataUse a consistent database dump or native backup method; test restoration on a separate instance.
Attachments and uploadsIssue files, avatars, release assets, and other non-Git contentBack up the configured storage directories or object-storage data.
Packages and artifactsContainer images, language packages, build outputs, and releasesInclude registry storage and its metadata; confirm retention rules do not remove required versions.
ConfigurationDatabase connection details, domains, ports, integrations, and service settingsVersion-control a sanitized configuration record and protect the live secrets separately.
Keys and certificatesEncryption, signing, SSH, OAuth, webhook, and TLS operationsStore encrypted copies with controlled access and document rotation or replacement procedures.
Infrastructure definitionRecreates operating-system packages, containers, networking, and storageKeep deployment scripts, compose files, manifests, and provisioning notes in a separate repository.

Checklist by scenario

1. Build the backup set

  1. List every repository namespace, including archived, private, mirrored, and administrative repositories.
  2. Identify repositories using Git LFS, submodules, release assets, or unusually large objects.
  3. Record the database name, engine, version, connection method, and backup location.
  4. Find application uploads, attachments, registry data, runner configuration, and CI cache data. Treat caches as optional only after confirming they can be recreated.
  5. Export or document instance configuration, scheduled jobs, SMTP settings, OAuth providers, webhooks, deploy keys, and external storage endpoints.
  6. Inventory encryption keys, signing keys, SSH host keys, TLS certificates, and recovery codes. Do not place unencrypted secrets in a public or broadly shared repository.
  7. Back up the deployment definition, including container images or package versions where rebuilding from the original sources may not be reliable.

2. Create a safe backup workflow

Run application-aware backups where the platform provides them. A database file copied while writes are active may be unusable or inconsistent, so use the database engine's supported dump or snapshot process. Likewise, coordinate repository and attachment backups when the application requires a consistent point in time.

Use at least two independent storage locations, with one outside the primary host or site. A practical arrangement is local backup storage for fast recovery plus encrypted off-site object storage or another controlled system. Separate backup credentials from production credentials, restrict write and read permissions, and consider immutable or append-only retention for a defined portion of the backup set.

Label each backup with the application version, database version, creation time, scope, and checksum where practical. Monitor job completion rather than assuming that a scheduled command succeeded. Alerts should identify failed jobs, unexpected size changes, expired credentials, and insufficient storage.

3. Restore a single repository

  1. Create an isolated test destination with no write access to production.
  2. Restore the repository using the platform's documented import or recovery method.
  3. Clone it and inspect branches, tags, commit history, Git LFS objects, submodules, and release assets.
  4. Check repository permissions and protected-branch settings if those are part of the export.
  5. Record the elapsed time, missing data, and manual steps. Update the runbook before the next test.

4. Restore the application and database

For a full recovery, provision a clean host or isolated environment instead of experimenting on the damaged system. Install the documented operating-system and application versions, configure storage, restore the database, restore uploads and registry data, and then apply the platform's documented migration steps. Avoid improvising version upgrades during the first recovery unless the original version cannot run.

Restore configuration only after reviewing secrets and host-specific values. Recreate DNS, TLS termination, firewall rules, SMTP, identity providers, runners, and webhooks in a controlled order. Keep the recovered service private until administrators have verified authentication, authorization, repository access, and audit behavior.

5. Use a simple recovery-test template

  • Date and scenario: for example, lost host, corrupted database, or accidental repository deletion.
  • Backup selected: timestamp, location, checksum, and application version.
  • Planned RPO and RTO: write the targets before testing.
  • Observed results: restore start and finish times, data gaps, and failed steps.
  • Validation: login, repository clone, push to a test repository, issue and attachment access, package retrieval, CI job execution, and webhook delivery.
  • Follow-up: owner, due date, and the exact change required.

What to double-check

Review the backup plan against the actual installation, not an assumed default layout. Forgejo, Gitea, and GitLab deployments can differ by package, container image, database choice, storage backend, and administrator configuration. Consult the release-specific documentation for backup and restore commands before running them in production.

Confirm that the backup includes data stored outside the main application volume. Object storage, mounted volumes, external databases, runner registrations, and registry blobs are common sources of incomplete recovery. Also verify that a database dump matches the application data it references; restoring metadata without the corresponding files can produce broken links and missing attachments.

Check encryption and access controls as carefully as availability. A backup containing source code, credentials, tokens, or private user data should be encrypted in transit and at rest, with access logs and a documented key-recovery path. Test that an authorized recovery operator can obtain the key without giving every system administrator permanent access.

Choose retention that matches the likely failure modes. One reasonable example is daily backups retained for a short operational window, weekly backups retained for several weeks, and monthly backups retained for a longer planning period. Adjust those intervals to repository churn, legal or organizational requirements, storage capacity, and the time needed to discover silent corruption. Retention is useful only if old backups are actually restorable.

Common mistakes

  • Backing up only the Git directory: this can omit database records, permissions, issues, uploads, packages, and configuration.
  • Keeping every copy on the production host: disk failure, ransomware, operator error, or host compromise can affect both the service and its backups.
  • Never performing a restore: a successful backup job proves that data was written, not that the data can produce a working service.
  • Relying on undocumented commands: package paths and supported procedures change across versions and deployment methods.
  • Mixing restoration with an upgrade: changing application and database versions at the same time makes failures harder to isolate.
  • Ignoring keys and certificates: restoring files without the keys that protect or identify them can leave encrypted data inaccessible or integrations broken.
  • Leaving test recovery exposed: a temporary restored instance can contain private source code and should use isolated networking and temporary credentials.

For related operational planning, see the guide to choosing an open-source Git hosting platform and the self-hosted CI/CD runner guide. If a recovery affects deployments, pair this runbook with a CI/CD rollback and incident response playbook.

When to revisit

Review this checklist before seasonal planning cycles and whenever workflows or tools change. Schedule a restore test at least quarterly if the Git server supports important development or release work; choose a different scenario each time so the team does not rehearse only one path.

Revisit the runbook after a major Forgejo, Gitea, GitLab, database, operating-system, storage, or deployment change. Also review it after adding a package registry, changing object storage, moving hosts, rotating encryption keys, introducing a new identity provider, or changing retention rules. Update commands, backup locations, storage credentials, version notes, and validation steps immediately rather than waiting for the next scheduled review.

End every drill with three actions: compare observed RPO and RTO with the targets, assign owners for gaps, and record the next test date. A self-hosted Git server backup strategy is complete only when another administrator can follow the documentation, recover the service in an isolated environment, and verify that the restored system is usable.

Related Topics

#Git hosting#backup#disaster recovery#self-hosting#Forgejo#Gitea
O

OpenDev Forge Editorial Team

Editorial Team

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.