适用于管理 GitHub Enterprise Server 的 REST API 终结点

关于管理 GitHub Enterprise Server API

可以使用管理 GitHub Enterprise Server API 管理你的 GitHub Enterprise Server 实例。例如，可以检索有关实例或具有多个节点的实例上运行的 GitHub Enterprise Server 软件版本的信息，查看复制状态。

在对管理 GitHub Enterprise Server API 的终结点进行 API 调用时指定端口号。如果实例使用 TLS，则端口号为 8443。否则，端口号为 8080。如果无法提供端口号，则需要将客户端配置为自动遵循重定向。有关详细信息，请参阅“配置 TLS”。

还可以使用 GitHub CLI 的 GitHub Enterprise Server 扩展的来调用管理 GitHub Enterprise Server API 中的终结点。有关详细信息，请参阅 github/gh-es 存储库。

身份验证

若要对针对管理 GitHub Enterprise Server API 终结点的请求进行身份验证，请将实例的根站点管理员帐户的密码指定为身份验证令牌。使用标准 HTTP 身份验证发送密码。 api_key 用户标识根站点管理员。以下示例演示此 API 的身份验证。将 ROOT-SITE-ADMINISTRATOR-PASSWORD 替换为密码，将 ADMINISTRATION-PORT 替换为 8443 或 8080。

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

以管理控制台用户身份进行身份验证

管理控制台用户帐户也可以进行身份验证以访问这些终结点。有关详细信息，请参阅“管理对管理控制台的访问”。

若要使用管理控制台用户帐户密码进行身份验证，请使用标准 HTTP 身份验证。在以下示例中，将 YOUR_USER_NAME 和 YOUR_PASSWORD 替换为帐户的用户名和密码。

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

查询参数

默认情况下，响应包括有关实例的所有已配置节点的信息。在具有多个节点的实例上，详细信息源自 /data/user/common/cluster.conf。可以使用以下查询参数来筛选响应，以获取有关特定节点的信息。

查询参数	说明
`uuid`	节点的唯一标识符。
`cluster_role`	对于群集中的节点，是应用于该节点的角色。有关详细信息，请参阅“[AUTOTITLE)(/admin/enterprise-management/configuring-clustering/about-cluster-nodes)”。

可以通过用逗号分隔值来为查询参数指定多个值。例如，以下请求使用 curl 返回具有 web-server 或 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."

“Get GHES node metadata for all nodes”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

查询参数
名称, 类型, 说明
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

“Get GHES node metadata for all nodes”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`401`	Unauthorized
`500`	Internal error

“Get GHES node metadata for all nodes”的示例代码

请求示例

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

“Get the status of maintenance mode”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

查询参数
名称, 类型, 说明
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

“Get the status of maintenance mode”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

“Get the status of maintenance mode”的示例代码

请求示例

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

“Set the status of maintenance mode”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

正文参数
名称, 类型, 说明
`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.

“Set the status of maintenance mode”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

“Set the status of maintenance mode”的示例代码

请求示例

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.

“Get the status of services running on all replica nodes”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

查询参数
名称, 类型, 说明
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

“Get the status of services running on all replica nodes”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`401`	Unauthorized
`500`	Internal error

“Get the status of services running on all replica nodes”的示例代码

请求示例

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

“Get all GHES release versions for all nodes”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

查询参数
名称, 类型, 说明
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

“Get all GHES release versions for all nodes”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`401`	Unauthorized
`500`	Internal error

“Get all GHES release versions for all nodes”的示例代码

请求示例

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