REST API теперь версия. Дополнительные сведения см. в разделе "О управлении версиями API".

Конечные точки REST API для управления GitHub Enterprise Server

Используйте REST API для управления экземпляром 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.

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 parameterDescription
uuidUnique identifier for the node.
cluster_roleFor 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 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-ответа для "Get the status of services running on all cluster nodes"

Код состоянияОписание
200

OK

401

Unauthorized

500

Internal error

Примеры кода для "Get the status of services running on all cluster nodes"

Пример запроса

get/manage/v1/cluster/status
curl -L \ -u "api_key:your-password" \ 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 GHES node metadata for all nodes

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

Параметры для "Get GHES node metadata for all nodes"

Параметры запроса
uuid string

The UUID which identifies a node.

cluster_roles string

The cluster roles from the cluster configuration file.

Коды состояния http-ответа для "Get GHES node metadata for all nodes"

Код состоянияОписание
200

OK

401

Unauthorized

500

Internal error

Примеры кода для "Get GHES node metadata for all nodes"

Пример запроса

get/manage/v1/config/nodes
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 maintenance mode

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

Параметры для "Get the status of maintenance mode"

Параметры запроса
uuid string

The UUID which identifies a node.

cluster_roles string

The cluster roles from the cluster configuration file.

Коды состояния http-ответа для "Get the status of maintenance mode"

Код состоянияОписание
200

OK

400

Bad request

401

Unauthorized

500

Internal error

Примеры кода для "Get the status of maintenance mode"

Пример запроса

get/manage/v1/maintenance
curl -L \ -u "api_key:your-password" \ 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."

Параметры для "Set the status of maintenance mode"

Параметры запроса
enabled boolean Обязательное поле

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-ответа для "Set the status of maintenance mode"

Код состоянияОписание
200

OK

400

Bad request

401

Unauthorized

500

Internal error

Примеры кода для "Set the status of maintenance mode"

Пример запроса

post/manage/v1/maintenance
curl -L \ -X POST \ -u "api_key:your-password" \ 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.

Параметры для "Get the status of services running on all replica nodes"

Параметры запроса
uuid string

The UUID which identifies a node.

cluster_roles string

The cluster roles from the cluster configuration file.

Коды состояния http-ответа для "Get the status of services running on all replica nodes"

Код состоянияОписание
200

OK

401

Unauthorized

500

Internal error

Примеры кода для "Get the status of services running on all replica nodes"

Пример запроса

get/manage/v1/replication/status
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."

Параметры для "Get all GHES release versions for all nodes"

Параметры запроса
uuid string

The UUID which identifies a node.

cluster_roles string

The cluster roles from the cluster configuration file.

Коды состояния http-ответа для "Get all GHES release versions for all nodes"

Код состоянияОписание
200

OK

401

Unauthorized

500

Internal error

Примеры кода для "Get all GHES release versions for all nodes"

Пример запроса

get/manage/v1/version
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" } } ]