Skip to main content
Skip to content

Configuring the backup service

Enable and configure the built-in backup service in the Management Console, and optionally migrate legacy settings.

Before configuring the backup service, ensure you have:

  • A GitHub Enterprise Server instance running version 3.17 or later.
  • A dedicated storage volume provisioned and managed for use as the backup target.

Storage requirements

To ensure reliable and performant backups, your storage must meet the following requirements:

  • Capacity: Allocate at least five times the amount of storage used by your primary GitHub appliance data disk. This accounts for historical snapshots and future growth.

  • Filesystem support: The backup service uses hard links for efficient storage, and your GitHub instance uses symbolic links. The backup target must support both symbolic and hard links, and it must use a case-sensitive filesystem to prevent conflicts.

    You can test whether your filesystem supports hardlinking symbolic links by running:

    cd /data/backup
    sudo touch file
    sudo ln -s file symlink
    sudo ln symlink hardlink
    ls -la
    

    If the ln symlink hardlink command completes successfully, the filesystem is supported.

  • Performance: Use high-performance storage with low latency and high IOPS to avoid slow backups and restores.

  • NFS: Avoid using an NFS mount for the backup directory (typically /data/backup), as this can lead to timeouts and degraded performance.

Configuring the backup service

You can configure GitHub Enterprise Server Backup Service through the Management Console.

Setting up the backup target

Before configuring the service, you must prepare the storage volume where backups will be stored.

Using a new block device

If you're using a dedicated block device as your backup target, you need to initialize it via SSH before proceeding in the Management Console. This process will format the device and erase all existing data.

  1. Connect to your instance via SSH as the admin user. See Accessing the administrative shell (SSH).

  2. Attach your backup block device to the instance.

  3. Identify the device name using lsblk to list available block devices. Make sure you select the correct device to avoid data loss.

    lsblk
    
  4. Run the initialization command, replacing YOUR_DEVICE_NAME with the actual device name identified in the previous step.

    Warning

    This command will permanently erase all data on the specified device. Double-check the device name and back up any important data before proceeding.

    ghe-storage-init-backup /dev/YOUR_DEVICE_NAME
    

    This command:

    • Formats the device (erases all data).
    • Prepares it for use by the backup service.
    • Sets it to mount automatically at /data/backup on boot.
    • If in a clustered environment, configures the node in cluster.conf with the backup-server role.

Increasing the data partition size

  1. Resize the existing backup disk volume mounted at /data/backup using your virtualization platform's tools.

  2. Connect via SSH as the admin user to the node where the backup disk is mounted. See Accessing the administrative shell (SSH).

  3. Put the appliance in maintenance mode. For more information, see Enabling and scheduling maintenance mode.

  4. Reboot the appliance to detect the new storage allocation:

    sudo reboot
    
  5. Run the ghe-backup-disk-extend command to expand the /data/backup filesystem:

    ghe-backup-disk-extend
    
  6. Ensure system services are functioning correctly, then release maintenance mode. For more information, see Enabling and scheduling maintenance mode.

Warning

If the ghe-backup-disk-extend command (or a prior automatic check) reports: ghe_backup_data contains a file system with errors, you must repair the filesystem before retrying the resize. Do not rerun ghe-backup-disk-extend until the check completes cleanly. For recovery instructions, see below.

Repairing filesystem errors

If the filesystem check fails during ghe-backup-disk-extend, follow these steps to repair it.

  1. Ensure the appliance is in maintenance mode and no background jobs are running:

    Shell
    ghe-maintenance -s
    ghe-resque-info
    
  2. Stop and activate the user volume, then run a forced filesystem check (auto‑answer yes):

    Shell
    sudo systemctl stop ghe-backup-disk
    VGNAME=$(sudo lvs --noheadings -o vg_name | grep ghe_backup_ | awk '{ print $1 }')
    sudo vgchange -ay "$VGNAME"
    sudo vgscan --mknodes
    sudo fsck -fy /dev/mapper/${VGNAME}-ghe_backup_data
    
  3. Retry the resize:

    Shell
    ghe-backup-disk-extend
    
  4. Remount and verify new size:

    Shell
    sudo systemctl start ghe-backup-disk
    df -h /data/backup
    
  5. Reboot and verify the new size.

  6. After the appliance restarts, reconnect via SSH to the node on which the backup disk is mounted, then verify the new size:

    Shell
    df -h /data/backup
    

Detach a backup disk

Warning

Before detaching a backup disk, ensure that no backups or restores are currently in progress. Detaching a disk while it is in use can result in data loss or service interruption.

In case you need to detach backup disk from GitHub Enterprise Server, please use following steps

  1. List block devices and unmount /data/backup.

    sudo lsblk
    sudo umount /data/backup
    
  2. List logical volumes and deactivate logical volume.

    sudo lvs
    sudo lvchange -an <backup_VG>/<backup_LV>
    
  3. Detach disk using console or CLI provided by cloud provider or hypervisor.

  4. Remove mount point.

    sudo rmdir /data/backup
    

Reusing a previously initialized disk

If the device was already initialized using ghe-storage-init-backup, you can reuse it without reformatting:

  1. Connect to your instance via SSH as the admin user.

  2. Attach the disk to the instance.

  3. Create the mount point, if it doesn't exist.

    sudo mkdir -p /data/backup
    
  4. Enable and start the mount service.

    sudo systemctl enable ghe-backup-disk.service
    sudo systemctl start ghe-backup-disk.service
    

    This will mount the device at /data/backup and ensures it's mounted automatically in the future.

  5. If using a cluster or high availability (HA) configuration, set the backup-server role for the node on which the disk is mounted and apply the configuration.

    This is also required when you add a replica to a standalone instance that already uses the backup service, even if the disk remains mounted. Keep the initialized disk and do not run ghe-storage-init-backup again. Only one node can have the backup-server role.

    Replace HOSTNAME with the hostname of the node on which the disk is mounted, as listed in cluster.conf.

    ghe-config cluster.HOSTNAME.backup-server true
    ghe-config-apply
    

Configuring backup settings

After the backup target is mounted, the Backup Service page will become available in the Management Console in the "Backup" section. If your instance is part of a clustered environment, the Backup Service page will be available after ghe-config-apply.

Note

The settings page won’t appear until the backup storage is mounted at /data/backup by completing the initialization or mount steps above.

If you're migrating from GitHub Enterprise Server Backup Utilities, you can transfer your configuration in one of two ways:

  1. Manual configuration: Recreate your settings directly in the Management Console.

  2. Command-line migration: SSH into your instance, copy your backup.config file from backup-utils, and run:

    ghe-migrate-backup-config /path/to/your/backup.config
    

    Use the --dry-run flag to preview changes without applying them.

Take a backup

Once the service is configured, you can take a backup manually using the following steps:

  1. In the Management Console, open the "Backups" tab from the top menu.
  2. Click Backup Now.

A GitHub Enterprise Server backup will be taken, and displayed in a list.

Scheduling automated backups

Once the service is configured, you can define a backup schedule.

  1. In the Management Console, open the "Settings" tab from the top menu.
  2. In the "Backup" section, choose a predefined schedule (e.g., Daily) or enter a custom cron expression.
  3. Click Save settings to apply the changes.

The first run will be a full backup. Future runs will be incremental. If a new backup attempt starts while a previous one is still running, it may be skipped or fail. In that case, adjust the schedule to avoid overlap.

Using Elasticsearch snapshots for search index data

By default, search index data is backed up by copying files directly from disk. You can optionally configure your GitHub Enterprise Server instance to use Elasticsearch's native, incremental snapshot functionality with a customer-managed cloud storage provider instead. For more information, see Configuring Elasticsearch snapshots.