REST API endpoints for managing GitHub Enterprise Server

About the Manage GitHub Enterprise Server API

You can manage your GitHub Enterprise Server instance using the Manage GitHub Enterprise Server API. For example, you can retrieve information about the version of the GitHub Enterprise Server software running on the instance, or on instances with multiple nodes, view the status of replication.

Tip

You can use this API to replace the functionality of the Management Console API, which was removed in GitHub Enterprise Server version 3.15.

Specify the port number when making API calls to endpoints for the Manage GitHub Enterprise Server API. If your instance uses TLS, the port number is 8443. Otherwise, the port number is 8080. If you cannot provide a port number, you'll need to configure your client to automatically follow redirects. For more information, see Configuring TLS.

You can also use the GitHub Enterprise Server extension of the GitHub CLI to invoke endpoints in the Manage GitHub Enterprise Server API. For more information, see the github/gh-es repository.

Authentication

To authenticate requests to endpoints for the Manage GitHub Enterprise Server API, specify the password for the instance's root site administrator account as an authentication token. Use standard HTTP authentication to send the password. The api_key user identifies the root site administrator. The following example demonstrates authentication for this API. Replace ROOT-SITE-ADMINISTRATOR-PASSWORD with the password, and ADMINISTRATION-PORT with either 8443 or 8080.

curl -L -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" 'http(s)://HOSTNAME:ADMINISTRATION-PORT/manage'

Authentication as a Management Console user

Management Console user accounts can also authenticate to access these endpoints. For more information, see Managing access to the Management Console.

To authenticate with the password for a Management Console user account, use standard HTTP authentication. In the following example, replace YOUR_USER_NAME and YOUR_PASSWORD with the account's user name and password.

curl -L -u "YOUR_USER_NAME:YOUR_PASSWORD" 'http(s)://HOSTNAME:ADMINISTRATION-PORT/manage'

Query parameters

By default, the response includes information from about all configured nodes for the instance. On an instance with multiple nodes, the details originate from /data/user/common/cluster.conf. You can use the following query parameters to filter the response for information about specific nodes.

Query parameter	Description
`uuid`	Unique identifier for the node.
`cluster_role`	For nodes in a cluster, the roles that apply to the node. For more information, see About cluster nodes.

You can specify multiple values for the query parameter by delimiting the values with a comma. For example, the following request uses curl to return any nodes with the web-server or storage-server role.

curl -L -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" 'http(s)://HOSTNAME:ADMINISTRATION-PORT/manage/v1/config/nodes?cluster_role=WebServer,StorageServer'

Get the configured SSH keys

Gets the configured SSH keys on all available nodes. For more information, see "Accessing the administrative shell (SSH)."

HTTP response status codes for "Get the configured SSH keys"

Status code	Description
`200`	OK
`400`	Bad request
`401`	Unauthorized

Code samples for "Get the configured SSH keys"

Request example

get/manage/v1/access/ssh

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/access/ssh

Response

Status: 200

[
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCwcd9tu20xsJVBMWbIs+JDVQTvkLtrJ8A7eblSwC+zECver22QExC9d6zHy10MAyk1Ck7Bu6/0Z+rr/31vMcAOmNOLjExzWxBCXbtDf3758Qfw7FuvkaTE1sHztwSFi/yNhZSw7uPEWeGQiRY4UldSKG9zZvrZmxpnP8mNZzPriQ==",
    "fingeprint": "bd:26:d3:a2:ad:97:c0:7c:2d:57:a4:64:f3:fb:44:45"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCg73sgCdLL9rWcmVTmvcOgAWZaokZTeNnMFEoaZWZcVtsP4Ed+ICuSbT1wDuyL/XXzr0O2u2bKwx8Np/3UGHb4R9Re+qiz//l5OCBd3KonO2GFICQwKGmVeZ+ki89aN2JDKgfemHbvclHYBD/r56lnbt/kinw7JqGPp+ndzH8nBw==",
    "fingeprint": "e1:1e:a0:f1:3f:a9:70:2d:99:dd:02:9d:39:1c:8b:a4"
  }
]

Set a new SSH key

Adds a SSH key to the authorized_keys file for your GitHub Enterprise Server instance. This will grant access via SSH to your instance. For more information, see "Accessing the administrative shell (SSH)."

Parameters for "Set a new SSH key"

Body parameters
Name, Type, Description
`key` string Required The public SSH key to add to the `authorized_keys` file.

HTTP response status codes for "Set a new SSH key"

Status code	Description
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Code samples for "Set a new SSH key"

Request example

post/manage/v1/access/ssh

curl -L \
  -X POST \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/access/ssh \
  -d '{"key":"ssh-rsa AAAAB3NzaC1yc2EAAAADCIABAAAAgQCY/ZiDDOFWcZnYXPwMbvwQDofXPdHxLfxPK+HWGVPd1DLcDncYBUSB0bmCU2g9Sc+oHKLoHhXp0ivau9h+EpmQJ7V8vqsRdD9pc4aL/WAnUyF4o3Y7xL94rlRpVbVo/tNjzcvqxxyzBiYyy3GciCMpYQh/uKt56B94/5PNyIGEEw=="}'

Response

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
    "message": "SSH key added successfully",
    "modified": true
  }
]

Delete a SSH key

Deletes a SSH key from the authorized_keys file for your GitHub Enterprise Server instance. This will remove access via SSH to your instance. For more information, see "Accessing the administrative shell (SSH)."

Parameters for "Delete a SSH key"

Body parameters
Name, Type, Description
`key` string Required The public SSH key to remove from the `authorized_keys` file.

HTTP response status codes for "Delete a SSH key"

Status code	Description
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Code samples for "Delete a SSH key"

Request example

delete/manage/v1/access/ssh

curl -L \
  -X DELETE \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/access/ssh \
  -d '{"key":"ssh-rsa AAAAB3NzaC1yc2EAAAADCIABAAAAgQCY/ZiDDOFWcZnYXPwMbvwQDofXPdHxLfxPK+HWGVPd1DLcDncYBUSB0bmCU2g9Sc+oHKLoHhXp0ivau9h+EpmQJ7V8vqsRdD9pc4aL/WAnUyF4o3Y7xL94rlRpVbVo/tNjzcvqxxyzBiYyy3GciCMpYQh/uKt56B94/5PNyIGEEw=="}'

Response

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
    "message": "SSH key removed successfully"
  }
]

Get the system requirement check results for configured cluster nodes

Checks if the minimum requirements for system hardware resources are met on each configured cluster node. This endpoint may take several seconds to reply.

HTTP response status codes for "Get the system requirement check results for configured cluster nodes"

Status code	Description
`200`	OK
`400`	Bad request
`500`	Internal error

Code samples for "Get the system requirement check results for configured cluster nodes"

Request example

get/manage/v1/checks/system-requirements

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/checks/system-requirements

Response

Status: 200

{
  "status": "OK",
  "nodes": [
    {
      "hostname": "ghe-local-app",
      "status": "OK",
      "roles_status": [
        {
          "status": "OK",
          "role": "ConsulServer"
        },
        {
          "status": "OK",
          "role": "JobServer"
        },
        {
          "status": "OK",
          "role": "WebServer"
        }
      ]
    },
    {
      "hostname": "ghe-local-app2",
      "status": "OK",
      "roles_status": [
        {
          "status": "OK",
          "role": "ConsulServer"
        },
        {
          "status": "OK",
          "role": "GitServer"
        }
      ]
    }
  ]
}

Get the status of services running on all cluster nodes

Gets the status of all services running on each cluster node. This endpoint may take several seconds to reply.

HTTP response status codes for "Get the status of services running on all cluster nodes"

Status code	Description
`200`	OK
`401`	Unauthorized
`500`	Internal error

Code samples for "Get the status of services running on all cluster nodes"

Request example

get/manage/v1/cluster/status

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/cluster/status

Response

Status: 200

{
  "status": "OK",
  "nodes": [
    {
      "hostname": "ghe-local-app",
      "status": "OK",
      "services": [
        {
          "status": "OK",
          "name": "es",
          "details": "Elasticsearch cluster is in sync (0 shards initializing, 0 shards unassigned)"
        },
        {
          "status": "OK",
          "name": "git-replication",
          "details": "Git replication is in sync"
        },
        {
          "status": "OK",
          "name": "kafka-lite-admin-healthcheck",
          "details": ""
        },
        {
          "status": "OK",
          "name": "kafka-lite-broker-is-reachable",
          "details": ""
        },
        {
          "status": "OK",
          "name": "memcache",
          "details": ""
        },
        {
          "status": "OK",
          "name": "metrics",
          "details": ""
        },
        {
          "status": "OK",
          "name": "mysql-replication",
          "details": "Replication is running"
        },
        {
          "status": "OK",
          "name": "mysql-failover",
          "details": ""
        },
        {
          "status": "OK",
          "name": "pages",
          "details": "Pages replication is in sync"
        },
        {
          "status": "OK",
          "name": "redis",
          "details": "Redis is OK"
        },
        {
          "status": "OK",
          "name": "storage",
          "details": "Storage replication is in sync"
        }
      ]
    },
    {
      "hostname": "ghe-local-app2",
      "status": "OK",
      "services": [
        {
          "status": "OK",
          "name": "kafka-lite-admin-healthcheck",
          "details": ""
        },
        {
          "status": "OK",
          "name": "kafka-lite-broker-is-reachable",
          "details": ""
        }
      ]
    }
  ]
}

Get the status of a ghe-config-apply run

Displays the current status of ghe-config-apply in the environment or the status of a historical run by ID.

Parameters for "Get the status of a ghe-config-apply run"

Query parameters
Name, Type, Description
`run_id` string The unique run ID of the `ghe-config-apply` run.

HTTP response status codes for "Get the status of a ghe-config-apply run"

Status code	Description
`200`	OK
`400`	Bad request
`401`	Unauthorized

Code samples for "Get the status of a ghe-config-apply run"

Request example

get/manage/v1/config/apply

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/apply

Response

Status: 200

{
  "running": true,
  "successful": false,
  "nodes": [
    {
      "run_id": "d34db33f",
      "hostname": "ghes-01.lan",
      "running": true,
      "successful": false
    }
  ]
}

Trigger a ghe-config-apply run

Triggers a run of ghe-config-apply from the ghes-manage agent on your Nomad Delegate instance. You can provide a run ID or allow one to be generated randomly.

Parameters for "Trigger a ghe-config-apply run"

Body parameters
Name, Type, Description
`run_id` string The run ID to execute `ghe-config-apply` with. If not provided, a run ID will be generated randomly.

HTTP response status codes for "Trigger a ghe-config-apply run"

Status code	Description
`200`	OK
`400`	Bad request
`401`	Unauthorized

Code samples for "Trigger a ghe-config-apply run"

Request example

post/manage/v1/config/apply

curl -L \
  -X POST \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/apply \
  -d '{"run_id":"d34db33f"}'

Response

Status: 200

{
  "run_id": "d34db33f"
}

List events from ghe-config-apply

Lists events from an in-process ghe-config-apply run on your Github Enterprise Server instance.

Parameters for "List events from ghe-config-apply"

Query parameters
Name, Type, Description
`last_request_id` string The unique ID of the last response from a host, used for pagination.

HTTP response status codes for "List events from ghe-config-apply"

Status code	Description
`200`	OK
`400`	Bad request
`401`	Unauthorized

Code samples for "List events from ghe-config-apply"

Request example

get/manage/v1/config/apply/events

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/apply/events

Response

Status: 200

{
  "nodes": [
    {
      "node": "ghes-01.lan",
      "last_request_id": "387cd628c06d606700e79be368e5e574:0cde553750689c76:0000000000000000",
      "events": [
        {
          "timestamp": "2023-01-01T13:00:00+00:00",
          "severity_text": "INFO",
          "body": "Validating services",
          "event_name": "Enterprise::ConfigApply::PhaseValidation#config_phase_validation",
          "topology": "multinode",
          "hostname": "ghes-01.lan",
          "config_run_id": "d34db33f",
          "trace_id": "387cd628c06d606700e79be368e5e574",
          "span_id": "0cde553750689c76",
          "span_parent_id": 0,
          "span_depth": 0
        }
      ]
    }
  ]
}

Initialize instance configuration with license and password

When you boot and set up a GitHub instance for the first time, you can use this endpoint to upload a license and set the initial root site administrator password.

Important

To start the configuration process and apply the license, you need to POST to /manage/v1/config/apply

The root site administrator password provided when calling this endpoint is used to authenticate for all other endpoints in the GHES Manage API and the Management Console UI.

Note

The request body for this operation must be submitted as multipart/form-data data. You can can reference the license file by prefixing the filename with the @ symbol using curl. For more information, see the curl documentation.

Parameters for "Initialize instance configuration with license and password"

Body parameters
Name, Type, Description
`license` string Required The content of your .ghl license file.
`password` string Required The root site administrator password.

HTTP response status codes for "Initialize instance configuration with license and password"

Status code	Description
`202`	Accepted
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Code samples for "Initialize instance configuration with license and password"

Request example

post/manage/v1/config/init

curl -L \
  -X POST \
  -u "api_key:your-password" \
  -H "Content-Type: multipart/form-data" \
  http(s)://HOSTNAME/manage/v1/config/init \
   --form 'license=@enterprise.ghl' --form 'password=provide-password-here!'

Response

Status: 202

Get the enterprise license information

Gets information about the license that is currently set for the enterprise.

HTTP response status codes for "Get the enterprise license information"

Status code	Description
`200`	OK
`401`	Unauthorized
`500`	Internal error

Code samples for "Get the enterprise license information"

Request example

get/manage/v1/config/license

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/license

Response

Status: 200

[
  {
    "advancedSecurityEnabled": true,
    "advancedSecuritySeats": 0,
    "clusterSupport": false,
    "company": "GitHub",
    "croquetSupport": true,
    "customTerms": true,
    "evaluation": false,
    "expireAt": "2025-01-02T07:59:59Z",
    "insightsEnabled": true,
    "insightsExpireAt": "2025-01-02T07:59:59.999Z",
    "learningLabEvaluationExpires": "2023-01-02T07:59:59Z",
    "learningLabSeats": 100,
    "perpetual": false,
    "referenceNumber": "32a145",
    "seats": 0,
    "sshAllowed": true,
    "supportKey\"": "",
    "unlimitedSeating": true
  }
]

Upload an enterprise license

Uploads a new enterprise license. In order to apply it right away, use the apply query parameter.

Note

The request body for this operation must be submitted as multipart/form-data data. You can can reference the license file by prefixing the filename with the @ symbol using curl. For more information, see the curl documentation.

Parameters for "Upload an enterprise license"

Query parameters
Name, Type, Description
`apply` boolean Whether to instantly apply changes from the license. Otherwise the new license can be applied using the `/manage/v1/config/apply` endpoint.

Body parameters
Name, Type, Description
`license` string Required The content of your .ghl license file.

HTTP response status codes for "Upload an enterprise license"

Status code	Description
`201`	Created
`202`	Accepted
`401`	Unauthorized
`500`	Internal error

Code samples for "Upload an enterprise license"

Request examples

Select the example type

put/manage/v1/config/license

curl -L \
  -X PUT \
  -u "api_key:your-password" \
  -H "Content-Type: multipart/form-data" \
  http(s)://HOSTNAME/manage/v1/config/license \
   --form 'license=@enterprise.ghl'

Created

Status: 201

Check a license

Check the status of the license that is currently set for the enterprise.

HTTP response status codes for "Check a license"

Status code	Description
`200`	OK
`401`	Unauthorized
`500`	Internal error

Code samples for "Check a license"

Request example

get/manage/v1/config/license/check

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/license/check

Response

Status: 200

[
  {
    "status": "valid"
  }
]

Get GHES node metadata for all nodes

Get node metadata for all configured nodes in the current cluster. For more information, see "About clustering."

Parameters for "Get GHES node metadata for all nodes"

Query parameters
Name, Type, Description
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

HTTP response status codes for "Get GHES node metadata for all nodes"

Status code	Description
`200`	OK
`401`	Unauthorized
`500`	Internal error

Code samples for "Get GHES node metadata for all nodes"

Request example

get/manage/v1/config/nodes

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/nodes

Response

Status: 200

{
  "topology": "Cluster",
  "nodes": [
    {
      "hostname": "data1",
      "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
      "cluster_roles": [
        "ConsulServer",
        "ElasticsearchServer",
        "GitServer",
        "StorageServer"
      ]
    },
    {
      "hostname": "data2",
      "uuid": "228406d4-f97c-11ed-ab01-062281bbcf03",
      "cluster_roles": [
        "ElasticsearchServer",
        "StorageServer",
        "PagesServer"
      ]
    }
  ]
}

Get the GHES settings

Gets a list of settings for a GitHub Enterprise Server instance.

HTTP response status codes for "Get the GHES settings"

Status code	Description
`200`	OK
`400`	Bad request
`401`	Unauthorized

Code samples for "Get the GHES settings"

Request example

get/manage/v1/config/settings

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/settings

Response

Status: 200

{
  "private_mode": false,
  "public_pages": false,
  "subdomain_isolation": true,
  "signup_enabled": false,
  "github_hostname": "ghe.local",
  "identicons_host": "dotcom",
  "auth_mode": "default",
  "expire_sessions": false,
  "configuration_id": 1401777404,
  "configuration_run_count": 4,
  "avatar": {
    "enabled": false,
    "uri": ""
  },
  "customer": {
    "name": "GitHub",
    "email": "stannis@themannis.biz",
    "uuid": "af6cac80-e4e1-012e-d822-1231380e52e9",
    "secret_key_data": "-----BEGIN PGP PRIVATE KEY BLOCK-----\nVersion: GnuPG v1.4.10 (GNU/Linux)\nlQcYBE5TCgsBEACk4yHpUcapplebaumBMXYMiLF+nCQ0lxpx...\n-----END PGP PRIVATE KEY BLOCK-----\n",
    "public_key_data": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: GnuPG v1.4.10 (GNU/Linux)\nmI0ETqzZYgEEALSe6snowdenXyqvLfSQ34HWD6C7....\n-----END PGP PUBLIC KEY BLOCK-----\n"
  },
  "license": {
    "seats": 0,
    "evaluation": false,
    "perpetual": false,
    "unlimited_seating": true,
    "support_key": "ssh-rsa AAAAB3N....",
    "ssh_allowed": true,
    "cluster_support": false,
    "expire_at": "2016-04-27T00:00:00-07:00"
  },
  "github_ssl": {
    "enabled": false,
    "cert": null,
    "key": null
  },
  "ldap": {
    "host": null,
    "port": 0,
    "base": [],
    "uid": null,
    "bind_dn": null,
    "password": null,
    "method": "Plain",
    "search_strategy": "detect",
    "user_groups": [],
    "admin_group": null,
    "virtual_attribute_enabled": false,
    "recursive_group_search": false,
    "posix_support": true,
    "user_sync_emails": false,
    "user_sync_keys": false,
    "user_sync_interval": 4,
    "team_sync_interval": 4,
    "sync_enabled": false,
    "reconciliation": {
      "user": null,
      "org": null
    },
    "profile": {
      "uid": "uid",
      "name": null,
      "mail": null,
      "key": null
    }
  },
  "cas": {
    "url": null
  },
  "saml": {
    "sso_url": null,
    "certificate": null,
    "certificate_path": null,
    "issuer": null,
    "idp_initiated_sso": false,
    "disable_admin_demote": false
  },
  "github_oauth": {
    "client_id": "12313412",
    "client_secret": "kj123131132",
    "organization_name": "Homestar Runners",
    "organization_team": "homestarrunners/characters"
  },
  "smtp": {
    "enabled": true,
    "address": "smtp.example.com",
    "authentication": "plain",
    "port": "1234",
    "domain": "blah",
    "username": "foo",
    "user_name": "mr_foo",
    "enable_starttls_auto": true,
    "password": "bar",
    "discard-to-noreply-address": true,
    "support_address": "enterprise@github.com",
    "support_address_type": "email",
    "noreply_address": "noreply@github.com"
  },
  "ntp": {
    "primary_server": "0.pool.ntp.org",
    "secondary_server": "1.pool.ntp.org"
  },
  "snmp": {
    "enabled": false,
    "community": ""
  },
  "syslog": {
    "enabled": false,
    "server": null,
    "protocol_name": "udp"
  },
  "pages": {
    "enabled": true
  },
  "collectd": {
    "enabled": false,
    "server": null,
    "port": 0,
    "encryption": null,
    "username": null,
    "password": null
  },
  "mapping": {
    "enabled": true,
    "tileserver": null,
    "basemap": "company.map-qsz2zrvs",
    "token": null
  },
  "prometheus": {
    "enabled": false,
    "trusted_ips": "10.0.0.1, 192.168.1.0/8"
  }
}

Set settings

Updates the settings on your instance. For a list of the available settings, see the Get settings endpoint.

Notes:

The request body only requires the settings parameters that should be updated to be specified, all other parameters will be unmodified or populated from the default values.
You cannot set the Management Console root site administrator password with this API endpoint. Use the ghe-set-password utility to change the management console password. For more information, see "Command-line utilities."

HTTP response status codes for "Set settings"

Status code	Description
`204`	No Content
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Code samples for "Set settings"

Request example

put/manage/v1/config/settings

curl -L \
  -X PUT \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/settings \
  -d '{"public_pages":true}'

Response

Status: 204

Get the status of maintenance mode

Gets the status and details of maintenance mode on all available nodes. For more information, see "Enabling and scheduling maintenance mode."

Parameters for "Get the status of maintenance mode"

Query parameters
Name, Type, Description
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

HTTP response status codes for "Get the status of maintenance mode"

Status code	Description
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Code samples for "Get the status of maintenance mode"

Request example

get/manage/v1/maintenance

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/maintenance

Response

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
    "status": "scheduled",
    "scheduled_time": "2006-01-02T15:04:05+00:00",
    "connection_services": [
      {
        "name": "git operations",
        "number": 15
      },
      {
        "name": "mysql queries",
        "number": 6
      },
      {
        "name": "resque jobs",
        "number": 10
      },
      {
        "name": "aqueduct jobs",
        "number": 0
      }
    ],
    "can_unset_maintenance": true,
    "ip_exception_list": [
      "1.1.1.1"
    ],
    "maintenance_mode_message": "Scheduled maintenance for upgrading."
  }
]

Set the status of maintenance mode

Sets or schedules the maintenance mode. For more information, see "Enabling and scheduling maintenance mode."

Parameters for "Set the status of maintenance mode"

Body parameters
Name, Type, Description
`enabled` boolean Required Whether to enable maintenance mode.
`uuid` string The UUID of the node to target. This parameter is incompatible with maintenance mode scheduling. Only use `uuid` if the value of `when` is empty or `now`.
`when` string The time to enable maintenance mode. If this parameter is empty or set to `now`, maintenance mode is enabled immediately. Otherwise, maintenance mode is enabled at the specified time. The format is ISO 8601.
`ip_exception_list` array of strings The list of IP addresses to exclude from maintenance mode. IPv4, IPv6, and CIDR addresses are supported.
`maintenance_mode_message` string The message to display to users when maintenance mode is enabled.

HTTP response status codes for "Set the status of maintenance mode"

Status code	Description
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Code samples for "Set the status of maintenance mode"

Request example

post/manage/v1/maintenance

curl -L \
  -X POST \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/maintenance \
  -d '{"enabled":true,"when":"2006-01-02T15:04:05+00:00","ip_exception_list":["192.168.1.0/24","1.1.1.1"]}'

Response

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
    "message": "maintenance mode scheduled with exception list [1.1.1.1]"
  }
]

Get the status of services running on all replica nodes

Gets the status of all services running on each replica node. This endpoint may take several seconds to reply.

Parameters for "Get the status of services running on all replica nodes"

Query parameters
Name, Type, Description
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

HTTP response status codes for "Get the status of services running on all replica nodes"

Status code	Description
`200`	OK
`401`	Unauthorized
`500`	Internal error

Code samples for "Get the status of services running on all replica nodes"

Request example

get/manage/v1/replication/status

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/replication/status

Response

Status: 200

{
  "status": "OK",
  "nodes": [
    {
      "hostname": "ghe-local-primary",
      "status": "OK",
      "services": []
    },
    {
      "hostname": "ghe-local-replica",
      "status": "OK",
      "services": [
        {
          "status": "OK",
          "name": "redis",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "elasticsearch",
          "details": "cluster is in sync (0 shards initializing, 0 shards unassigned)"
        },
        {
          "status": "OK",
          "name": "git",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "pages",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "alambic",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "git-hooks",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "consul",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "mysql",
          "details": "replication is in sync"
        }
      ]
    }
  ]
}

Apply an upgrade

Applies an upgrade package on a GitHub Enterprise Server node. You can run a full upgrade (pre-upgrade + upgrade), or a specific phase. Either upgrade_package_file or version is required. When phase is omitted, both pre-upgrade and upgrade phases run sequentially.

Parameters for "Apply an upgrade"

Body parameters
Name, Type, Description
`upgrade_package_file` string Absolute path to the upgrade package file. Must be under `/var/lib/ghe-updates/` and the path must be canonical (no `..` or duplicate slashes).
`version` string Target upgrade version in semantic version format (e.g. `3.19.3`). The version is normalized to `major.minor.patch` format.
`target_partition` string Target block device partition for the upgrade.
`phase` string Upgrade phase to run. Valid values are `pre-upgrade` or `upgrade`. Omit for a full upgrade. Can be one of: `pre-upgrade`, `upgrade`
`skip_reboot` boolean Whether to skip the reboot after the upgrade completes. Default is `false`. Default: `false`
`uuid` string The UUID of a specific node to upgrade. When omitted, the upgrade is applied to all nodes.

HTTP response status codes for "Apply an upgrade"

Status code	Description
`200`	OK
`400`	Bad request
`401`	Unauthorized
`404`	Not found
`500`	Internal error

Code samples for "Apply an upgrade"

Request example

post/manage/v1/upgrade/apply

curl -L \
  -X POST \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  https://HOSTNAME/manage/v1/upgrade/apply \
  -d '{"version":"3.19.3"}'

OK

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
    "message": "upgrade started",
    "error": ""
  }
]

Download an upgrade package

Starts an asynchronous GitHub Enterprise Server upgrade package download on the targeted node set.

On single-node and high availability topologies, the gateway fans out directly to the targeted nodes and returns a 200 OK response containing one result per node, unless an orchestration option is provided. On cluster topologies, or whenever max_parallel, node_timeout, or max_attempts is provided, the gateway starts an in-memory throttled orchestration and returns 202 Accepted.

If version is omitted, each agent resolves the latest eligible upgrade package version for that node. The download runs in the background; use the upgrade download status endpoint to monitor progress.

Parameters for "Download an upgrade package"

Body parameters
Name, Type, Description
`version` string Semantic version of the upgrade package to download. If omitted, the agent resolves the latest eligible version.
`force` boolean Whether to remove an existing package file before starting a new download. Default: `false`
`uuids` array of strings Node UUIDs to target after gateway query filters are applied. Blank values are ignored; if all supplied values are blank, the request is rejected.
`max_parallel` integer Selects gateway-side orchestration and limits the number of nodes downloading at the same time. Non-positive values use the gateway default, and values above the target node count are capped to that count. Default: `2`
`node_timeout` string Selects gateway-side orchestration and marks an in-flight node download as stuck after this Go duration. Defaults to 30m and must be at most 2h. Default: `30m0s`
`max_attempts` integer Selects gateway-side orchestration and sets the maximum number of attempts per node. Non-positive values use the gateway default. The maximum accepted value is 5. Default: `3`

HTTP response status codes for "Download an upgrade package"

Status code	Description
`200`	Direct fan-out accepted the download request on the targeted nodes. Individual node failures are returned in each node result and do not change the HTTP status code.
`202`	Gateway-side throttled orchestration was accepted and started in the background.
`400`	Bad request
`401`	Unauthorized
`404`	Not found
`409`	Download orchestration could not start because another orchestration is running, or because a targeted node is already downloading a package.
`500`	Internal error

Code samples for "Download an upgrade package"

Request example

post/manage/v1/upgrade/download

curl -L \
  -X POST \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  https://HOSTNAME/manage/v1/upgrade/download \
  -d '{"version":"3.19.3","force":false}'

Direct fan-out accepted the download request on the targeted nodes. Individual node failures are returned in each node result and do not change the HTTP status code.

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
    "message": "download started",
    "error": ""
  }
]

Get the upgrade package download status

Returns the aggregate and per-node status for GitHub Enterprise Server upgrade package downloads.

While a gateway-side throttled orchestration is running, the response includes an orchestration object with queue-level counts and the status is scoped to the gateway-filtered node set. When no orchestration is active, the gateway fans out to the targeted agents and aggregates their per-node download status.

Use uuid query filters to inspect a subset of nodes.

Parameters for "Get the upgrade package download status"

Query parameters
Name, Type, Description
`uuid` string The UUID which identifies a node.

HTTP response status codes for "Get the upgrade package download status"

Status code	Description
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Code samples for "Get the upgrade package download status"

Request examples

Select the example type

get/manage/v1/upgrade/download/status

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  https://HOSTNAME/manage/v1/upgrade/download/status

OK

Status: 200

{
  "upgrade_id": "550e8400-e29b-41d4-a716-446655440000",
  "package_name": "github-enterprise-3.19.3-kvm.pkg",
  "status": "downloading",
  "error_message": "",
  "distribution_progress": {
    "completed_nodes": 2,
    "total_nodes": 5
  },
  "nodes": [
    {
      "hostname": "node-1",
      "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
      "upgrade_id": "550e8400-e29b-41d4-a716-446655440000",
      "package_name": "github-enterprise-3.19.3-kvm.pkg",
      "status": "completed",
      "progress": "100%",
      "error": ""
    },
    {
      "hostname": "node-2",
      "uuid": "228406d4-f97c-11ed-ab01-062281bbcf03",
      "upgrade_id": "550e8400-e29b-41d4-a716-446655440000",
      "package_name": "github-enterprise-3.19.3-kvm.pkg",
      "status": "downloading",
      "progress": "63%",
      "error": ""
    }
  ]
}

Get the upgrade status

Gets the upgrade status from all configured nodes of a GitHub Enterprise Server instance. Returns information about the current upgrade phase, completion status, and individual step details when is_verbose mode is enabled.

Parameters for "Get the upgrade status"

Query parameters
Name, Type, Description
`uuid` string The UUID which identifies a node.
`is_verbose` boolean Whether to include detailed step information.

HTTP response status codes for "Get the upgrade status"

Status code	Description
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Code samples for "Get the upgrade status"

Request example

get/manage/v1/upgrade/status

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  https://HOSTNAME/manage/v1/upgrade/status

OK

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
    "release_version": "3.19.2",
    "release_sha": "abc123def456",
    "status": "in_progress",
    "pre_upgrade_status": "completed",
    "upgrade_last_completed_step": "extract_root_filesystem",
    "is_running": true,
    "failed": false,
    "steps": [
      {
        "phase": "pre-upgrade",
        "step": "signature_verification",
        "status": "completed",
        "started_at": "2024-06-02T10:30:00Z",
        "ended_at": "2024-06-02T10:31:00Z",
        "error": ""
      }
    ],
    "messages": [],
    "error": ""
  }
]

Get all GHES release versions for all nodes

Gets the GitHub Enterprise Server release versions that are currently installed on all available nodes. For more information, see "GitHub Enterprise Server releases."

Parameters for "Get all GHES release versions for all nodes"

Query parameters
Name, Type, Description
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

HTTP response status codes for "Get all GHES release versions for all nodes"

Status code	Description
`200`	OK
`401`	Unauthorized
`500`	Internal error

Code samples for "Get all GHES release versions for all nodes"

Request example

get/manage/v1/version

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/version

Response

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "version": {
      "version": "3.9.0",
      "platform": "azure",
      "build_id": "fc542058b5",
      "build_date": "2023-05-02"
    }
  }
]