Some standard maintenance procedures, such as upgrading your GitHub Enterprise instance or restoring backups, require that the GitHub Enterprise instance be taken offline for normal use.

In this guide:

About maintenance mode

Some types of operations require that you take GitHub offline and put it into maintenance mode:

  • Upgrading to a new version of GitHub Enterprise
  • Increasing CPU, memory, or storage resources allocated to the virtual machine
  • Migrating data from one virtual machine to another
  • Restoring data from a GitHub Enterprise Backup Utilities snapshot
  • Troubleshooting certain types of critical application issues

While you can choose to put an instance into maintenance mode immediately, we recommend you schedule a maintenance window for 30 minutes, one, or two hours in the future in order to give users time to prepare.

When a maintenance window is scheduled, all users will see a banner when accessing the site.

End user banner about scheduled maintenance

When the instance is in maintenance mode, all normal HTTP and Git access is refused. Visiting the site in a browser results in a maintenance page.

The maintenance mode splash screen

Git fetch, clone, and push operations are also rejected with an error message indicating that the site is temporarily unavailable.

Enabling maintenance mode immediately or scheduling a maintenance window for a later time

  1. In the upper-right corner of any page, click . Rocketship icon for accessing site admin settings

  2. In the left sidebar, click Management Console. Management Console tab in the left sidebar

  3. At the top of the Management Console, click Maintenance. Maintenance tab

  4. Under "Enable and schedule", decide whether to enable maintenance mode immediately or to schedule a maintenance window for a future time.
    • To enable maintenance mode immediately, use the drop-down menu and click now. Drop-down menu with the option to enable maintenance mode now selected
    • To schedule a maintenance window for a future time, use the drop-down menu and click a start time. Drop-down menu with the option to schedule a maintenance window in two hours selected
  5. Select Enable maintenance mode. Checkbox for enabling or scheduling maintenance mode

Scheduling maintenance mode with the GitHub Enterprise API

You can schedule maintenance for different times or dates with the GitHub Enterprise API. For more information, see "Management Console" in the GitHub Developer documentation.

Enabling or disabling maintenance mode for all nodes in a cluster

With the ghe-cluster-maintenance utility, you can set or unset maintenance mode for every node in a cluster.

ghe-cluster-maintenance -h
# Shows options
ghe-cluster-maintenance -q
# Queries the current mode
ghe-cluster-maintenance -s
# Sets maintenance mode
ghe-cluster-maintenance -u
# Unsets maintenance mode