REST-API-Endpunkte zum Verwalten von GitHub Enterprise Server

Informationen zur GitHub Enterprise Server-Verwaltungs-API

Du kannst den Ihre GitHub Enterprise Server-Instance mithilfe der Verwaltungs-API GitHub Enterprise Server verwalten. Du kannst beispielsweise Informationen zur Version der GitHub Enterprise Server-Software abrufen, die auf der Instanz ausgeführt wird, oder auf Instanzen mit mehreren Knoten den Status der Replikation anzeigen.

Gib die Portnummer an, wenn du API-Aufrufe an Endpunkten für die GitHub Enterprise Server-Verwaltungs-API tätigst. Wenn deine Instanz die TLS verwendet, lautet die Portnummer 8443. Andernfalls lautet die Portnummer 8080. Wenn du keine Portnummer angeben kannst, musst du deinen Client so konfigurieren, dass eine automatische Umleitung erfolgt. Weitere Informationen finden Sie unter unter „TLS konfigurieren“.

Sie können auch die GitHub Enterprise Server-Erweiterung der GitHub CLI verwenden, um Endpunkte in GitHub Enterprise Server-API verwalten aufzurufen. Weitere Informationen finden Sie im github/gh-es-Repository.

Authentifizierung

Um Anforderungen an Endpunkte für die GitHub Enterprise Server-Verwaltungs-API zu authentifizieren, gib das Kennwort für das Stammwebsite-Administratorkonto der Instanz als Authentifizierungstoken an. Verwende zum Senden des Kennworts die HTTP-Standardauthentifizierung. Der api_key-Benutzer ermittelt den Stammwebsiteadministrator. Im folgenden Beispiel wird die Authentifizierung für diese API veranschaulicht. Ersetzen Sie ROOT-SITE-ADMINISTRATOR-PASSWORD durch das Kennwort und ADMINISTRATION-PORT durch 8443 oder 8080.

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

Authentifizierung als Verwaltungskonsole-Benutzer*in

Verwaltungskonsole-Benutzerkonten können sich auch authentifizieren, um auf diese Endpunkte zuzugreifen. Weitere Informationen finden Sie unter unter „Verwalten des Zugriffs auf die Verwaltungskonsole“.

Verwende HTTP-Standardauthentifizierung, um sich mit dem Kennwort für ein Benutzerkonto der Verwaltungskonsole zu authentifizieren. Ersetze im folgenden Beispiel YOUR_USER_NAME und YOUR_PASSWORD durch den Benutzernamen und das Kennwort des Kontos.

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

Abfrageparameter

Standardmäßig enthält die Antwort Informationen zu allen konfigurierten Knoten für die Instanz. Bei einer Instanz mit mehreren Knoten stammen die Details aus /data/user/common/cluster.conf. Du kannst die folgenden Abfrageparameter verwenden, um die Antwort nach Informationen zu bestimmten Knoten zu filtern.

Query parameter (Abfrageparameter)	BESCHREIBUNG
`uuid`	Dies ist der eindeutige Bezeichner für den Knoten.
`cluster_role`	Für Knoten in einem Cluster sind dies die Rollen, die auf den Knoten angewendet werden. Weitere Informationen findest du unter „[AUTOTITLE)(/admin/enterprise-management/configuring-clustering/about-cluster-nodes)“.

Du kannst mehrere Werte für den Abfrageparameter angeben, indem du die Werte durch ein Komma trennst. Die folgende Anforderung verwendet beispielsweise curl, um alle Knoten mit der Rolle web-server oder storage-server zurückzugeben.

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

Parameter für „Get GHES node metadata for all nodes“

Header
Name, type, BESCHREIBUNG
`accept` string Setting to `application/vnd.github+json` is recommended.

Abfrageparameter
Name, type, BESCHREIBUNG
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

HTTP-Antwortstatuscodes für „Get GHES node metadata for all nodes“

Statuscode	BESCHREIBUNG
`200`	OK
`401`	Unauthorized
`500`	Internal error

Codebeispiele für „Get GHES node metadata for all nodes“

Beispiel für eine Anfrage

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

Parameter für „Get the status of maintenance mode“

Header
Name, type, BESCHREIBUNG
`accept` string Setting to `application/vnd.github+json` is recommended.

Abfrageparameter
Name, type, BESCHREIBUNG
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

HTTP-Antwortstatuscodes für „Get the status of maintenance mode“

Statuscode	BESCHREIBUNG
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Codebeispiele für „Get the status of maintenance mode“

Beispiel für eine Anfrage

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

Parameter für „Set the status of maintenance mode“

Header
Name, type, BESCHREIBUNG
`accept` string Setting to `application/vnd.github+json` is recommended.

Textparameter
Name, type, BESCHREIBUNG
`enabled` boolean Erforderlich 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.

HTTP-Antwortstatuscodes für „Set the status of maintenance mode“

Statuscode	BESCHREIBUNG
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Codebeispiele für „Set the status of maintenance mode“

Beispiel für eine Anfrage

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.

Parameter für „Get the status of services running on all replica nodes“

Header
Name, type, BESCHREIBUNG
`accept` string Setting to `application/vnd.github+json` is recommended.

Abfrageparameter
Name, type, BESCHREIBUNG
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

HTTP-Antwortstatuscodes für „Get the status of services running on all replica nodes“

Statuscode	BESCHREIBUNG
`200`	OK
`401`	Unauthorized
`500`	Internal error

Codebeispiele für „Get the status of services running on all replica nodes“

Beispiel für eine Anfrage

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

Parameter für „Get all GHES release versions for all nodes“

Header
Name, type, BESCHREIBUNG
`accept` string Setting to `application/vnd.github+json` is recommended.

Abfrageparameter
Name, type, BESCHREIBUNG
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

HTTP-Antwortstatuscodes für „Get all GHES release versions for all nodes“

Statuscode	BESCHREIBUNG
`200`	OK
`401`	Unauthorized
`500`	Internal error

Codebeispiele für „Get all GHES release versions for all nodes“

Beispiel für eine Anfrage

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