GitHub Enterprise Server の管理用の REST API エンドポイント

Manage GitHub Enterprise Server API について

Manage GitHub Enterprise Server API を使いお使いの GitHub Enterprise Server インスタンスを管理できます。たとえば、複数のノードがあるインスタンス上で実行されている GitHub Enterprise Server ソフトウェアのバージョンに関する情報を取得したり、レプリケーションの状態を表示したりできます。

Manage GitHub Enterprise Server API のエンドポイントに API 呼び出しを行うときのポート番号を指定します。インスタンスで TLS が使われる場合、ポート番号は 8443 です。それ以外の場合、ポート番号は 8080 です。ポート番号を提供できない場合は、自動的にリダイレクトに従うようにクライアントを構成する必要があります。詳しくは、「TLSの設定」をご覧ください。

また、GitHub CLI の GitHub Enterprise Server 拡張機能を使用して、 Manage GitHub Enterprise Server API でエンドポイントを呼び出すこともできます。詳細については、github/gh-es リポジトリを参照してください。

認証

Manage 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'

[Management Console] ユーザーとしての認証

[Management Console] ユーザーアカウントは、これらのエンドポイントにアクセスするために認証することもできます。詳しくは、「管理コンソールへのアクセスの管理」をご覧ください。

[Management Console] ユーザーアカウントのパスワードを使って認証を行うには、標準の 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 から生成されます。次のクエリパラメーターを使用して、特定のノードに関する情報の応答をフィルター処理できます。

Query parameter (クエリパラメーター)	説明
`uuid`	ノードの一意識別子。
`cluster_role`	クラスター内のノードの場合、ノードに適用されるロール。詳しくは、「クラスタノードについて」をご覧ください。

値をコンマで区切ることで、クエリパラメーターに複数の値を指定できます。たとえば、次の要求は 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 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.

"Get the status of services running on all cluster nodes" の HTTP 応答状態コード

状態コード	説明
`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" のパラメーター

クエリパラメーター
名前, Type, 説明
`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 \
  -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" のパラメーター

クエリパラメーター
名前, Type, 説明
`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 \
  -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" のパラメーター

本文のパラメーター
名前, Type, 説明
`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 \
  -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" のパラメーター

クエリパラメーター
名前, Type, 説明
`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 \
  -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" のパラメーター

クエリパラメーター
名前, Type, 説明
`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 \
  -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"
    }
  }
]