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 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, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.

クエリパラメーター
名前, 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 \
  -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 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, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.

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

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.

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