Skip to main content
O controle de versão da API REST já foi feito. Para obter mais informações, confira "Sobre o controle de versão da API".

Pontos de extremidade da API REST para gerenciar o GitHub Enterprise Server

Use a API REST para gerenciar a instância do GitHub Enterprise Server.

Sobre a API de gerenciamento do GitHub Enterprise Server

É possível gerenciar o sua instância do GitHub Enterprise Server por meio da API de gerenciamento do GitHub Enterprise Server. Por exemplo, é possível recuperar informações sobre a versão do software GitHub Enterprise Server em execução na instância ou, em instâncias com diversos nós, exibir o status da replicação.

Especifique o número da porta ao fazer chamadas de API para pontos de extremidade com relação à API de gerenciamento do GitHub Enterprise Server. Se a instância usar TLS, o número da porta será 8443. Caso contrário, o número da porta será 8080. Se não for possível fornecer um número de porta, configure o cliente para seguir redirecionamentos automaticamente. Para obter mais informações, confira "Configurar o TLS".

Autenticação

Para autenticar solicitações a pontos de extremidade com relação à API de gerenciamento do GitHub Enterprise Server, especifique a senha da conta de administrador do site raiz da instância como um token de autenticação. Use a autenticação HTTP padrão para enviar a senha. O usuário api_key identifica o administrador do site raiz. O exemplo a seguir demonstra a autenticação para essa API. Substitua ROOT-SITE-ADMINISTRATOR-PASSWORD pela senha e ADMINISTRATION-PORT por 8443 ou 8080.

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

Autenticação como um usuário Console de Gerenciamento

As contas de usuário do Console de Gerenciamento também podem ser autenticadas para acessar esses pontos de extremidade. Para obter mais informações, confira "Como gerenciar o acesso ao Console de Gerenciamento".

Para autenticar com a senha de uma conta de usuário do Console de Gerenciamento, use a autenticação HTTP padrão. No exemplo a seguir, substitua YOUR_USER_NAME e YOUR_PASSWORD pelo nome de usuário e senha da conta.

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

Parâmetros de consulta

Por padrão, a resposta inclui informações de sobre todos os nós configurados para a instância. Em uma instância com vários nós, os detalhes se originam de /data/user/common/cluster.conf. Você pode usar os parâmetros de consulta a seguir para filtrar a resposta para obter informações sobre nós específicos.

Parâmetro de consultaDescrição
uuidIdentificador exclusivo para o nó.
cluster_rolePara nós em um cluster, as funções que se aplicam ao nó. Para saber mais, confira "[AUTOTITLE)(/admin/enterprise-management/configuring-clustering/about-cluster-nodes)".

Você pode especificar vários valores para o parâmetro de consulta delimitando os valores com uma vírgula. Por exemplo, a solicitação a seguir usa curl para retornar quaisquer nós com a função web-server ou storage-server.

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."

Parâmetros para "Get GHES node metadata for all nodes"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de consulta
Nome, Tipo, Descrição
uuid string

The UUID which identifies a node.

cluster_roles string

The cluster roles from the cluster configuration file.

Códigos de status de resposta HTTP para "Get GHES node metadata for all nodes"

Código de statusDescrição
200

OK

401

Unauthorized

500

Internal error

Exemplos de código para "Get GHES node metadata for all nodes"

Exemplo de solicitação

get/manage/v1/config/nodes
curl -L \ -H "Accept: application/vnd.github+json" \ -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."

Parâmetros para "Get the status of maintenance mode"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de consulta
Nome, Tipo, Descrição
uuid string

The UUID which identifies a node.

cluster_roles string

The cluster roles from the cluster configuration file.

Códigos de status de resposta HTTP para "Get the status of maintenance mode"

Código de statusDescrição
200

OK

400

Bad request

401

Unauthorized

500

Internal error

Exemplos de código para "Get the status of maintenance mode"

Exemplo de solicitação

get/manage/v1/maintenance
curl -L \ -H "Accept: application/vnd.github+json" \ -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."

Parâmetros para "Set the status of maintenance mode"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros do corpo
Nome, Tipo, Descrição
enabled boolean Obrigatório

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.

Códigos de status de resposta HTTP para "Set the status of maintenance mode"

Código de statusDescrição
200

OK

400

Bad request

401

Unauthorized

500

Internal error

Exemplos de código para "Set the status of maintenance mode"

Exemplo de solicitação

post/manage/v1/maintenance
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -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.

Parâmetros para "Get the status of services running on all replica nodes"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de consulta
Nome, Tipo, Descrição
uuid string

The UUID which identifies a node.

cluster_roles string

The cluster roles from the cluster configuration file.

Códigos de status de resposta HTTP para "Get the status of services running on all replica nodes"

Código de statusDescrição
200

OK

401

Unauthorized

500

Internal error

Exemplos de código para "Get the status of services running on all replica nodes"

Exemplo de solicitação

get/manage/v1/replication/status
curl -L \ -H "Accept: application/vnd.github+json" \ -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."

Parâmetros para "Get all GHES release versions for all nodes"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de consulta
Nome, Tipo, Descrição
uuid string

The UUID which identifies a node.

cluster_roles string

The cluster roles from the cluster configuration file.

Códigos de status de resposta HTTP para "Get all GHES release versions for all nodes"

Código de statusDescrição
200

OK

401

Unauthorized

500

Internal error

Exemplos de código para "Get all GHES release versions for all nodes"

Exemplo de solicitação

get/manage/v1/version
curl -L \ -H "Accept: application/vnd.github+json" \ -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" } } ]