Puntos de conexión de API de REST para administrar GitHub Enterprise Server

Acerca de la API Manage GitHub Enterprise Server

Puede administrar tu instancia de GitHub Enterprise Server mediante la API Manage GitHub Enterprise Server. Por ejemplo, puede recuperar información sobre la versión del software GitHub Enterprise Server que se ejecuta en la instancia, o en instancias con varios nodos, ver el estado de replicación.

Especifica el número de puerto al realizar llamadas API a puntos de conexión para la API Manage GitHub Enterprise Server. Si la instancia usa TLS, el número de puerto es 8443. De lo contrario, el número de puerto es 8080. Si no quieres proporcionar un número de puerto, necesitarás configurar tu herramienta para seguir automáticamente los redireccionamientos. Para más información, consulta Configurar TLS.

También puede usar la extensión GitHub Enterprise Server de GitHub CLI para invocar puntos de conexión en la API AdministrarGitHub Enterprise Server. Para más información, consulte el repositorio github/gh-es.

Autenticación

Para autenticar las solicitudes a los puntos de conexión de la API Manage GitHub Enterprise Server, especifica la contraseña de la cuenta de administrador del sitio raíz de la instancia como token de autenticación. Usa la autenticación HTTP estándar para enviar la contraseña. El usuario api_key identifica al administrador del sitio raíz. En el ejemplo siguiente se muestra la autenticación de esta API. Reemplaza ROOT-SITE-ADMINISTRATOR-PASSWORD por la contraseña y ADMINISTRATION-PORT por 8443 u 8080.

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

Autenticación como usuario de la Consola de administración

Las cuentas de usuario de Consola de administración también se pueden autenticar para acceder a estos puntos de conexión. Para más información, consulta Administración del acceso a la Consola de administración.

Para autenticarse con la contraseña de una cuenta de usuario de Consola de administración, usa la autenticación HTTP estándar. En el ejemplo siguiente, reemplaza YOUR_USER_NAME y YOUR_PASSWORD por el nombre de usuario y la contraseña de la cuenta.

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

Parámetros de consulta

De forma predeterminada, la respuesta incluye información de todos los nodos configurados para la instancia. En una instancia con varios nodos, los detalles se originan en /data/user/common/cluster.conf. Puede usar los siguientes parámetros de consulta para filtrar la respuesta para obtener información sobre nodos específicos.

Parámetro de consulta	Descripción
`uuid`	Identificador único para el nodo.
`cluster_role`	En el caso de los nodos de un clúster, los roles que se aplican al nodo. Para más información, consulta Acerca de los nodos de agrupación.

Puede especificar varios valores para el parámetro de consulta delimitando los valores con una coma. Por ejemplo, la siguiente solicitud usa curl para devolver los nodos con el rol web-server o 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 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.

Códigos de estado de respuesta HTTP para "Get the status of services running on all cluster nodes"

status code	Descripción
`200`	OK
`401`	Unauthorized
`500`	Internal error

Ejemplos de código para "Get the status of services running on all cluster nodes"

Ejemplo de solicitud

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

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

Parámetros de consulta
Nombre, Tipo, Descripción
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

Códigos de estado de respuesta HTTP para "Get GHES node metadata for all nodes"

status code	Descripción
`200`	OK
`401`	Unauthorized
`500`	Internal error

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

Ejemplo de solicitud

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
Nombre, Tipo, Descripción
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

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

status code	Descripción
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

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

Ejemplo de solicitud

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 del cuerpo
Nombre, Tipo, Descripción
`enabled` boolean Requerido 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 estado de respuesta HTTP para "Set the status of maintenance mode"

status code	Descripción
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

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

Ejemplo de solicitud

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
Nombre, Tipo, Descripción
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

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

status code	Descripción
`200`	OK
`401`	Unauthorized
`500`	Internal error

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

Ejemplo de solicitud

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
Nombre, Tipo, Descripción
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

Códigos de estado de respuesta HTTP para "Get all GHES release versions for all nodes"

status code	Descripción
`200`	OK
`401`	Unauthorized
`500`	Internal error

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

Ejemplo de solicitud

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"
    }
  }
]