Points de terminaison d’API REST pour la gestion de GitHub Enterprise Server

À propos de l’API Gérer GitHub Enterprise Server

Vous pouvez gérer votre instance GitHub Enterprise Server à l’aide de l’API Gérer GitHub Enterprise Server. Par exemple, vous pouvez récupérer des informations sur la version du logiciel GitHub Enterprise Server exécuté sur l’instance, ou sur les instances à plusieurs nœuds, afficher l’état de réplication.

Spécifiez le numéro de port lorsque vous effectuez des appels d’API aux points de terminaison de l’API Gérer GitHub Enterprise Server. Si votre instance utilise TLS, le numéro de port est 8443. Sinon, le numéro de port est 8080. Si vous ne pouvez pas fournir un numéro de port, vous devez configurer votre client pour suivre automatiquement les redirections. Pour plus d’informations, consultez « Configuration de TLS ».

Vous pouvez également utiliser l’extension GitHub Enterprise Server des GitHub CLI pour appeler des points de terminaison dans l’API Gérer les données GitHub Enterprise Server. Pour plus d'informations, consultez le dépôt github/gh-es.

Authentification

Pour authentifier les demandes adressées aux points de terminaison de l’API Gérer GitHub Enterprise Server, spécifiez le mot de passe du compte administrateur de site racine de l’instance comme jeton d’authentification. Utilisez une authentification HTTP standard pour envoyer le mot de passe. L’utilisateur api_key identifie l’administrateur de site racine. L’exemple suivant illustre l’authentification pour cette API. Remplacez ROOT-SITE-ADMINISTRATOR-PASSWORD par le mot de passe et ADMINISTRATION-PORT par 8443 ou 8080.

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

Authentification en tant qu’Management Consoleutilisateur

Les comptes d’utilisateur Management Console peuvent également s’authentifier pour accéder à ces points de terminaison. Pour plus d’informations, consultez « Gestion de l’accès à la console de gestion ».

Pour s’authentifier avec le mot de passe d’un Management Console compte d'utilisateur, utilisez l’authentification HTTP standard. Dans l’exemple suivant, remplacez YOUR_USER_NAME et YOUR_PASSWORD par le nom d’utilisateur et le mot de passe du compte.

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

Paramètres de requête

Par défaut, la réponse inclut des informations sur tous les nœuds configurés pour l’instance. Sur une instance avec plusieurs nœuds, les détails proviennent de /data/user/common/cluster.conf. Vous pouvez utiliser les paramètres de requête suivants pour filtrer la réponse et obtenir des informations sur des nœuds spécifiques.

Paramètre de requête.	Description
`uuid`	Identificateur unique du nœud.
`cluster_role`	Pour les nœuds d’un cluster, les rôles qui s’appliquent au nœud. Pour plus d’informations, consultez « [AUTOTITLE)(/admin/enterprise-management/configuring-clustering/about-cluster-nodes) ».

Vous pouvez spécifier plusieurs valeurs pour le paramètre de requête en séparant les valeurs par une virgule. Par exemple, la requête suivante utilise curl pour retourner tous les nœuds ayant le rôle web-server ou 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."

Paramètres pour « Get GHES node metadata for all nodes »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de requête
Nom, Type, Description
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

Codes d’état de la réponse HTTP pour « Get GHES node metadata for all nodes »

Code d’état	Description
`200`	OK
`401`	Unauthorized
`500`	Internal error

Exemples de code pour « Get GHES node metadata for all nodes »

Exemple de requête

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

Paramètres pour « Get the status of maintenance mode »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de requête
Nom, Type, Description
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

Codes d’état de la réponse HTTP pour « Get the status of maintenance mode »

Code d’état	Description
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Exemples de code pour « Get the status of maintenance mode »

Exemple de requête

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

Paramètres pour « Set the status of maintenance mode »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres du corps
Nom, Type, Description
`enabled` boolean Obligatoire 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.

Codes d’état de la réponse HTTP pour « Set the status of maintenance mode »

Code d’état	Description
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Exemples de code pour « Set the status of maintenance mode »

Exemple de requête

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.

Paramètres pour « Get the status of services running on all replica nodes »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de requête
Nom, Type, Description
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

Codes d’état de la réponse HTTP pour « Get the status of services running on all replica nodes »

Code d’état	Description
`200`	OK
`401`	Unauthorized
`500`	Internal error

Exemples de code pour « Get the status of services running on all replica nodes »

Exemple de requête

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

Paramètres pour « Get all GHES release versions for all nodes »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de requête
Nom, Type, Description
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

Codes d’état de la réponse HTTP pour « Get all GHES release versions for all nodes »

Code d’état	Description
`200`	OK
`401`	Unauthorized
`500`	Internal error

Exemples de code pour « Get all GHES release versions for all nodes »

Exemple de requête

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