This version of GitHub Enterprise Server was discontinued on 2024-07-09. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.
REST API endpoints for managing GitHub Enterprise Server
Use the REST API to manage your GitHub Enterprise Server instance.
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.
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 "[AUTOTITLE)(/admin/enterprise-management/configuring-clustering/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 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"
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
curl -L \
-u "api_key:your-password" \
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 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"
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
curl -L \
-u "api_key:your-password" \
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"
}
]
}
]
}
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"
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
curl -L \
-u "api_key:your-password" \
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"
}
}
]