Pontos de extremidade da API REST para gerenciar o 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 saber mais, confira Configurar o TLS.

Você também pode usar a extensão do GitHub Enterprise Server da GitHub CLI para invocar pontos de extremidade na API Manage do GitHub Enterprise Server. Para obter mais informações, confira o repositório github/gh-es.

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 saber mais, 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 consulta	Descrição
`uuid`	Identificador exclusivo para o nó.
`cluster_role`	Para nós em um cluster, as funções que se aplicam ao nó. Para saber mais, confira Sobre nós de cluster.

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"

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 status	Descriçã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 \
  -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"

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 status	Descriçã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 \
  -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"

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 status	Descriçã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 \
  -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"

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 status	Descriçã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 \
  -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"

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 status	Descriçã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 \
  -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"
    }
  }
]