Die REST-API ist jetzt versioniert. Weitere Informationen findest du unter Informationen zur API-Versionsverwaltung.

REST-API-Endpunkte zum Verwalten von GitHub Enterprise Server

Verwenden Sie die REST-API, um Ihre GitHub Enterprise Server Instanz zu verwalten.

Informationen zur Api "Verwalten"GitHub Enterprise Server

Sie können Ihre GitHub Enterprise Server-Instance mit der Verwaltungs-API GitHub Enterprise Server verwalten. Sie können z. B. 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.

Tipp

Sie können diese API verwenden, um die Funktionalität der Verwaltungskonsolen-API zu ersetzen, die in GitHub Enterprise Server Version 3.15 entfernt wurde.

Geben Sie die Portnummer an, wenn API-Aufrufe an Endpunkte für die Manage-API GitHub Enterprise Server ausgeführt werden. 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 TLS konfigurieren.

Sie können auch die GitHub Enterprise Server-Erweiterung von GitHub CLI verwenden, um Endpunkte in der GitHub Enterprise Server-Verwaltungs-API aufzurufen. Weitere Informationen findest du unter dem github/gh-es Repository.

Authentifizierung

Um Anforderungen an Endpunkte für die Manage-API GitHub Enterprise Server zu authentifizieren, geben Sie das Kennwort für das Stammwebsiteadministratorkonto 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

Verwaltungskonsole Benutzerkonten können sich auch für den Zugriff auf diese Endpunkte authentifizieren. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf die Verwaltungskonsole.

Verwenden Sie die standardmäßige HTTP-Authentifizierung, um sich mit dem Kennwort für ein Verwaltungskonsole Benutzerkonto 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 finden Sie unter Informationen zu Clusterknoten.

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 the configured SSH keys

Gets the configured SSH keys on all available nodes. For more information, see "Accessing the administrative shell (SSH)."

HTTP-Antwortstatuscodes für "Get the configured SSH keys"

Statuscode	BESCHREIBUNG
`200`	OK
`400`	Bad request
`401`	Unauthorized

Codebeispiele für "Get the configured SSH keys"

Anforderungsbeispiel

get/manage/v1/access/ssh

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/access/ssh

Response

Status: 200

[
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCwcd9tu20xsJVBMWbIs+JDVQTvkLtrJ8A7eblSwC+zECver22QExC9d6zHy10MAyk1Ck7Bu6/0Z+rr/31vMcAOmNOLjExzWxBCXbtDf3758Qfw7FuvkaTE1sHztwSFi/yNhZSw7uPEWeGQiRY4UldSKG9zZvrZmxpnP8mNZzPriQ==",
    "fingeprint": "bd:26:d3:a2:ad:97:c0:7c:2d:57:a4:64:f3:fb:44:45"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCg73sgCdLL9rWcmVTmvcOgAWZaokZTeNnMFEoaZWZcVtsP4Ed+ICuSbT1wDuyL/XXzr0O2u2bKwx8Np/3UGHb4R9Re+qiz//l5OCBd3KonO2GFICQwKGmVeZ+ki89aN2JDKgfemHbvclHYBD/r56lnbt/kinw7JqGPp+ndzH8nBw==",
    "fingeprint": "e1:1e:a0:f1:3f:a9:70:2d:99:dd:02:9d:39:1c:8b:a4"
  }
]

Set a new SSH key

Adds a SSH key to the authorized_keys file for your GitHub Enterprise Server instance. This will grant access via SSH to your instance. For more information, see "Accessing the administrative shell (SSH)."

Parameter für "Set a new SSH key"

Körperparameter
Name, Typ, BESCHREIBUNG
`key` string Erforderlich The public SSH key to add to the `authorized_keys` file.

HTTP-Antwortstatuscodes für "Set a new SSH key"

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

Codebeispiele für "Set a new SSH key"

Anforderungsbeispiel

post/manage/v1/access/ssh

curl -L \
  -X POST \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/access/ssh \
  -d '{"key":"ssh-rsa AAAAB3NzaC1yc2EAAAADCIABAAAAgQCY/ZiDDOFWcZnYXPwMbvwQDofXPdHxLfxPK+HWGVPd1DLcDncYBUSB0bmCU2g9Sc+oHKLoHhXp0ivau9h+EpmQJ7V8vqsRdD9pc4aL/WAnUyF4o3Y7xL94rlRpVbVo/tNjzcvqxxyzBiYyy3GciCMpYQh/uKt56B94/5PNyIGEEw=="}'

Response

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
    "message": "SSH key added successfully",
    "modified": true
  }
]

Delete a SSH key

Deletes a SSH key from the authorized_keys file for your GitHub Enterprise Server instance. This will remove access via SSH to your instance. For more information, see "Accessing the administrative shell (SSH)."

Parameter für "Delete a SSH key"

Körperparameter
Name, Typ, BESCHREIBUNG
`key` string Erforderlich The public SSH key to remove from the `authorized_keys` file.

HTTP-Antwortstatuscodes für "Delete a SSH key"

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

Codebeispiele für "Delete a SSH key"

Anforderungsbeispiel

delete/manage/v1/access/ssh

curl -L \
  -X DELETE \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/access/ssh \
  -d '{"key":"ssh-rsa AAAAB3NzaC1yc2EAAAADCIABAAAAgQCY/ZiDDOFWcZnYXPwMbvwQDofXPdHxLfxPK+HWGVPd1DLcDncYBUSB0bmCU2g9Sc+oHKLoHhXp0ivau9h+EpmQJ7V8vqsRdD9pc4aL/WAnUyF4o3Y7xL94rlRpVbVo/tNjzcvqxxyzBiYyy3GciCMpYQh/uKt56B94/5PNyIGEEw=="}'

Response

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
    "message": "SSH key removed successfully"
  }
]

Get the system requirement check results for configured cluster nodes

Checks if the minimum requirements for system hardware resources are met on each configured cluster node. This endpoint may take several seconds to reply.

HTTP-Antwortstatuscodes für "Get the system requirement check results for configured cluster nodes"

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

Codebeispiele für "Get the system requirement check results for configured cluster nodes"

Anforderungsbeispiel

get/manage/v1/checks/system-requirements

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/checks/system-requirements

Response

Status: 200

{
  "status": "OK",
  "nodes": [
    {
      "hostname": "ghe-local-app",
      "status": "OK",
      "roles_status": [
        {
          "status": "OK",
          "role": "ConsulServer"
        },
        {
          "status": "OK",
          "role": "JobServer"
        },
        {
          "status": "OK",
          "role": "WebServer"
        }
      ]
    },
    {
      "hostname": "ghe-local-app2",
      "status": "OK",
      "roles_status": [
        {
          "status": "OK",
          "role": "ConsulServer"
        },
        {
          "status": "OK",
          "role": "GitServer"
        }
      ]
    }
  ]
}

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.

HTTP-Antwortstatuscodes für "Get the status of services running on all cluster nodes"

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

Codebeispiele für "Get the status of services running on all cluster nodes"

Anforderungsbeispiel

get/manage/v1/cluster/status

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  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 the status of a ghe-config-apply run

Displays the current status of ghe-config-apply in the environment or the status of a historical run by ID.

Parameter für "Get the status of a ghe-config-apply run"

Abfrageparameter
Name, Typ, BESCHREIBUNG
`run_id` string The unique run ID of the `ghe-config-apply` run.

HTTP-Antwortstatuscodes für "Get the status of a ghe-config-apply run"

Statuscode	BESCHREIBUNG
`200`	OK
`400`	Bad request
`401`	Unauthorized

Codebeispiele für "Get the status of a ghe-config-apply run"

Anforderungsbeispiel

get/manage/v1/config/apply

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/apply

Response

Status: 200

{
  "running": true,
  "successful": false,
  "nodes": [
    {
      "run_id": "d34db33f",
      "hostname": "ghes-01.lan",
      "running": true,
      "successful": false
    }
  ]
}

Trigger a ghe-config-apply run

Triggers a run of ghe-config-apply from the ghes-manage agent on your Nomad Delegate instance. You can provide a run ID or allow one to be generated randomly.

Parameter für "Trigger a ghe-config-apply run"

Körperparameter
Name, Typ, BESCHREIBUNG
`run_id` string The run ID to execute `ghe-config-apply` with. If not provided, a run ID will be generated randomly.

HTTP-Antwortstatuscodes für "Trigger a ghe-config-apply run"

Statuscode	BESCHREIBUNG
`200`	OK
`400`	Bad request
`401`	Unauthorized

Codebeispiele für "Trigger a ghe-config-apply run"

Anforderungsbeispiel

post/manage/v1/config/apply

curl -L \
  -X POST \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/apply \
  -d '{"run_id":"d34db33f"}'

Response

Status: 200

{
  "run_id": "d34db33f"
}

List events from ghe-config-apply

Lists events from an in-process ghe-config-apply run on your Github Enterprise Server instance.

Parameter für "List events from ghe-config-apply"

Abfrageparameter
Name, Typ, BESCHREIBUNG
`last_request_id` string The unique ID of the last response from a host, used for pagination.

HTTP-Antwortstatuscodes für "List events from ghe-config-apply"

Statuscode	BESCHREIBUNG
`200`	OK
`400`	Bad request
`401`	Unauthorized

Codebeispiele für "List events from ghe-config-apply"

Anforderungsbeispiel

get/manage/v1/config/apply/events

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/apply/events

Response

Status: 200

{
  "nodes": [
    {
      "node": "ghes-01.lan",
      "last_request_id": "387cd628c06d606700e79be368e5e574:0cde553750689c76:0000000000000000",
      "events": [
        {
          "timestamp": "2023-01-01T13:00:00+00:00",
          "severity_text": "INFO",
          "body": "Validating services",
          "event_name": "Enterprise::ConfigApply::PhaseValidation#config_phase_validation",
          "topology": "multinode",
          "hostname": "ghes-01.lan",
          "config_run_id": "d34db33f",
          "trace_id": "387cd628c06d606700e79be368e5e574",
          "span_id": "0cde553750689c76",
          "span_parent_id": 0,
          "span_depth": 0
        }
      ]
    }
  ]
}

Initialize instance configuration with license and password

When you boot and set up a GitHub instance for the first time, you can use this endpoint to upload a license and set the initial root site administrator password.

Important

To start the configuration process and apply the license, you need to POST to /manage/v1/config/apply

The root site administrator password provided when calling this endpoint is used to authenticate for all other endpoints in the GHES Manage API and the Management Console UI.

Note

The request body for this operation must be submitted as multipart/form-data data. You can can reference the license file by prefixing the filename with the @ symbol using curl. For more information, see the curl documentation.

Parameter für "Initialize instance configuration with license and password"

Körperparameter
Name, Typ, BESCHREIBUNG
`license` string Erforderlich The content of your .ghl license file.
`password` string Erforderlich The root site administrator password.

HTTP-Antwortstatuscodes für "Initialize instance configuration with license and password"

Statuscode	BESCHREIBUNG
`202`	Accepted
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Codebeispiele für "Initialize instance configuration with license and password"

Anforderungsbeispiel

post/manage/v1/config/init

curl -L \
  -X POST \
  -u "api_key:your-password" \
  -H "Content-Type: multipart/form-data" \
  http(s)://HOSTNAME/manage/v1/config/init \
   --form 'license=@enterprise.ghl' --form 'password=provide-password-here!'

Response

Status: 202

Get the enterprise license information

Gets information about the license that is currently set for the enterprise.

HTTP-Antwortstatuscodes für "Get the enterprise license information"

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

Codebeispiele für "Get the enterprise license information"

Anforderungsbeispiel

get/manage/v1/config/license

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/license

Response

Status: 200

[
  {
    "advancedSecurityEnabled": true,
    "advancedSecuritySeats": 0,
    "clusterSupport": false,
    "company": "GitHub",
    "croquetSupport": true,
    "customTerms": true,
    "evaluation": false,
    "expireAt": "2025-01-02T07:59:59Z",
    "insightsEnabled": true,
    "insightsExpireAt": "2025-01-02T07:59:59.999Z",
    "learningLabEvaluationExpires": "2023-01-02T07:59:59Z",
    "learningLabSeats": 100,
    "perpetual": false,
    "referenceNumber": "32a145",
    "seats": 0,
    "sshAllowed": true,
    "supportKey\"": "",
    "unlimitedSeating": true
  }
]

Upload an enterprise license

Uploads a new enterprise license. In order to apply it right away, use the apply query parameter.

Note

Parameter für "Upload an enterprise license"

Abfrageparameter
Name, Typ, BESCHREIBUNG
`apply` boolean Whether to instantly apply changes from the license. Otherwise the new license can be applied using the `/manage/v1/config/apply` endpoint.

Körperparameter
Name, Typ, BESCHREIBUNG
`license` string Erforderlich The content of your .ghl license file.

HTTP-Antwortstatuscodes für "Upload an enterprise license"

Statuscode	BESCHREIBUNG
`201`	Created
`202`	Accepted
`401`	Unauthorized
`500`	Internal error

Codebeispiele für "Upload an enterprise license"

Beispiele für Anfragen

Select the example type

put/manage/v1/config/license

curl -L \
  -X PUT \
  -u "api_key:your-password" \
  -H "Content-Type: multipart/form-data" \
  http(s)://HOSTNAME/manage/v1/config/license \
   --form 'license=@enterprise.ghl'

Created

Status: 201

Check a license

Check the status of the license that is currently set for the enterprise.

HTTP-Antwortstatuscodes für "Check a license"

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

Codebeispiele für "Check a license"

Anforderungsbeispiel

get/manage/v1/config/license/check

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/license/check

Response

Status: 200

[
  {
    "status": "valid"
  }
]

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"

Abfrageparameter
Name, Typ, 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"

Anforderungsbeispiel

get/manage/v1/config/nodes

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  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 GHES settings

Gets a list of settings for a GitHub Enterprise Server instance.

HTTP-Antwortstatuscodes für "Get the GHES settings"

Statuscode	BESCHREIBUNG
`200`	OK
`400`	Bad request
`401`	Unauthorized

Codebeispiele für "Get the GHES settings"

Anforderungsbeispiel

get/manage/v1/config/settings

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/settings

Response

Status: 200

{
  "private_mode": false,
  "public_pages": false,
  "subdomain_isolation": true,
  "signup_enabled": false,
  "github_hostname": "ghe.local",
  "identicons_host": "dotcom",
  "auth_mode": "default",
  "expire_sessions": false,
  "configuration_id": 1401777404,
  "configuration_run_count": 4,
  "avatar": {
    "enabled": false,
    "uri": ""
  },
  "customer": {
    "name": "GitHub",
    "email": "stannis@themannis.biz",
    "uuid": "af6cac80-e4e1-012e-d822-1231380e52e9",
    "secret_key_data": "-----BEGIN PGP PRIVATE KEY BLOCK-----\nVersion: GnuPG v1.4.10 (GNU/Linux)\nlQcYBE5TCgsBEACk4yHpUcapplebaumBMXYMiLF+nCQ0lxpx...\n-----END PGP PRIVATE KEY BLOCK-----\n",
    "public_key_data": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: GnuPG v1.4.10 (GNU/Linux)\nmI0ETqzZYgEEALSe6snowdenXyqvLfSQ34HWD6C7....\n-----END PGP PUBLIC KEY BLOCK-----\n"
  },
  "license": {
    "seats": 0,
    "evaluation": false,
    "perpetual": false,
    "unlimited_seating": true,
    "support_key": "ssh-rsa AAAAB3N....",
    "ssh_allowed": true,
    "cluster_support": false,
    "expire_at": "2016-04-27T00:00:00-07:00"
  },
  "github_ssl": {
    "enabled": false,
    "cert": null,
    "key": null
  },
  "ldap": {
    "host": null,
    "port": 0,
    "base": [],
    "uid": null,
    "bind_dn": null,
    "password": null,
    "method": "Plain",
    "search_strategy": "detect",
    "user_groups": [],
    "admin_group": null,
    "virtual_attribute_enabled": false,
    "recursive_group_search": false,
    "posix_support": true,
    "user_sync_emails": false,
    "user_sync_keys": false,
    "user_sync_interval": 4,
    "team_sync_interval": 4,
    "sync_enabled": false,
    "reconciliation": {
      "user": null,
      "org": null
    },
    "profile": {
      "uid": "uid",
      "name": null,
      "mail": null,
      "key": null
    }
  },
  "cas": {
    "url": null
  },
  "saml": {
    "sso_url": null,
    "certificate": null,
    "certificate_path": null,
    "issuer": null,
    "idp_initiated_sso": false,
    "disable_admin_demote": false
  },
  "github_oauth": {
    "client_id": "12313412",
    "client_secret": "kj123131132",
    "organization_name": "Homestar Runners",
    "organization_team": "homestarrunners/characters"
  },
  "smtp": {
    "enabled": true,
    "address": "smtp.example.com",
    "authentication": "plain",
    "port": "1234",
    "domain": "blah",
    "username": "foo",
    "user_name": "mr_foo",
    "enable_starttls_auto": true,
    "password": "bar",
    "discard-to-noreply-address": true,
    "support_address": "enterprise@github.com",
    "support_address_type": "email",
    "noreply_address": "noreply@github.com"
  },
  "ntp": {
    "primary_server": "0.pool.ntp.org",
    "secondary_server": "1.pool.ntp.org"
  },
  "snmp": {
    "enabled": false,
    "community": ""
  },
  "syslog": {
    "enabled": false,
    "server": null,
    "protocol_name": "udp"
  },
  "pages": {
    "enabled": true
  },
  "collectd": {
    "enabled": false,
    "server": null,
    "port": 0,
    "encryption": null,
    "username": null,
    "password": null
  },
  "mapping": {
    "enabled": true,
    "tileserver": null,
    "basemap": "company.map-qsz2zrvs",
    "token": null
  },
  "prometheus": {
    "enabled": false,
    "trusted_ips": "10.0.0.1, 192.168.1.0/8"
  }
}

Set settings

Updates the settings on your instance. For a list of the available settings, see the Get settings endpoint.

Notes:

The request body only requires the settings parameters that should be updated to be specified, all other parameters will be unmodified or populated from the default values.
You cannot set the Management Console root site administrator password with this API endpoint. Use the ghe-set-password utility to change the management console password. For more information, see "Command-line utilities."

HTTP-Antwortstatuscodes für "Set settings"

Statuscode	BESCHREIBUNG
`204`	No Content
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Codebeispiele für "Set settings"

Anforderungsbeispiel

put/manage/v1/config/settings

curl -L \
  -X PUT \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  http(s)://HOSTNAME/manage/v1/config/settings \
  -d '{"public_pages":true}'

Response

Status: 204

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"

Abfrageparameter
Name, Typ, 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"

Anforderungsbeispiel

get/manage/v1/maintenance

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  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"

Körperparameter
Name, Typ, 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"

Anforderungsbeispiel

post/manage/v1/maintenance

curl -L \
  -X POST \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  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"

Abfrageparameter
Name, Typ, 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"

Anforderungsbeispiel

get/manage/v1/replication/status

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  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"
        }
      ]
    }
  ]
}

Apply an upgrade

Applies an upgrade package on a GitHub Enterprise Server node. You can run a full upgrade (pre-upgrade + upgrade), or a specific phase. Either upgrade_package_file or version is required. When phase is omitted, both pre-upgrade and upgrade phases run sequentially.

Parameter für "Apply an upgrade"

Körperparameter
Name, Typ, BESCHREIBUNG
`upgrade_package_file` string Absolute path to the upgrade package file. Must be under `/var/lib/ghe-updates/` and the path must be canonical (no `..` or duplicate slashes).
`version` string Target upgrade version in semantic version format (e.g. `3.19.3`). The version is normalized to `major.minor.patch` format.
`target_partition` string Target block device partition for the upgrade.
`phase` string Upgrade phase to run. Valid values are `pre-upgrade` or `upgrade`. Omit for a full upgrade. Kann eine der folgenden sein: `pre-upgrade`, `upgrade`
`skip_reboot` boolean Whether to skip the reboot after the upgrade completes. Default is `false`. Standard: `false`
`uuid` string The UUID of a specific node to upgrade. When omitted, the upgrade is applied to all nodes.

HTTP-Antwortstatuscodes für "Apply an upgrade"

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

Codebeispiele für "Apply an upgrade"

Anforderungsbeispiel

post/manage/v1/upgrade/apply

curl -L \
  -X POST \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  https://HOSTNAME/manage/v1/upgrade/apply \
  -d '{"version":"3.19.3"}'

OK

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
    "message": "upgrade started",
    "error": ""
  }
]

Download an upgrade package

Starts an asynchronous GitHub Enterprise Server upgrade package download on the targeted node set.

On single-node and high availability topologies, the gateway fans out directly to the targeted nodes and returns a 200 OK response containing one result per node, unless an orchestration option is provided. On cluster topologies, or whenever max_parallel, node_timeout, or max_attempts is provided, the gateway starts an in-memory throttled orchestration and returns 202 Accepted.

If version is omitted, each agent resolves the latest eligible upgrade package version for that node. The download runs in the background; use the upgrade download status endpoint to monitor progress.

Parameter für "Download an upgrade package"

Körperparameter
Name, Typ, BESCHREIBUNG
`version` string Semantic version of the upgrade package to download. If omitted, the agent resolves the latest eligible version.
`force` boolean Whether to remove an existing package file before starting a new download. Standard: `false`
`uuids` array of strings Node UUIDs to target after gateway query filters are applied. Blank values are ignored; if all supplied values are blank, the request is rejected.
`max_parallel` integer Selects gateway-side orchestration and limits the number of nodes downloading at the same time. Non-positive values use the gateway default, and values above the target node count are capped to that count. Standard: `2`
`node_timeout` string Selects gateway-side orchestration and marks an in-flight node download as stuck after this Go duration. Defaults to 30m and must be at most 2h. Standard: `30m0s`
`max_attempts` integer Selects gateway-side orchestration and sets the maximum number of attempts per node. Non-positive values use the gateway default. The maximum accepted value is 5. Standard: `3`

HTTP-Antwortstatuscodes für "Download an upgrade package"

Statuscode	BESCHREIBUNG
`200`	Direct fan-out accepted the download request on the targeted nodes. Individual node failures are returned in each node result and do not change the HTTP status code.
`202`	Gateway-side throttled orchestration was accepted and started in the background.
`400`	Bad request
`401`	Unauthorized
`404`	Not found
`409`	Download orchestration could not start because another orchestration is running, or because a targeted node is already downloading a package.
`500`	Internal error

Codebeispiele für "Download an upgrade package"

Anforderungsbeispiel

post/manage/v1/upgrade/download

curl -L \
  -X POST \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  https://HOSTNAME/manage/v1/upgrade/download \
  -d '{"version":"3.19.3","force":false}'

Direct fan-out accepted the download request on the targeted nodes. Individual node failures are returned in each node result and do not change the HTTP status code.

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
    "message": "download started",
    "error": ""
  }
]

Get the upgrade package download status

Returns the aggregate and per-node status for GitHub Enterprise Server upgrade package downloads.

While a gateway-side throttled orchestration is running, the response includes an orchestration object with queue-level counts and the status is scoped to the gateway-filtered node set. When no orchestration is active, the gateway fans out to the targeted agents and aggregates their per-node download status.

Use uuid query filters to inspect a subset of nodes.

Parameter für "Get the upgrade package download status"

Abfrageparameter
Name, Typ, BESCHREIBUNG
`uuid` string The UUID which identifies a node.

HTTP-Antwortstatuscodes für "Get the upgrade package download status"

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

Codebeispiele für "Get the upgrade package download status"

Beispiele für Anfragen

Select the example type

get/manage/v1/upgrade/download/status

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  https://HOSTNAME/manage/v1/upgrade/download/status

OK

Status: 200

{
  "upgrade_id": "550e8400-e29b-41d4-a716-446655440000",
  "package_name": "github-enterprise-3.19.3-kvm.pkg",
  "status": "downloading",
  "error_message": "",
  "distribution_progress": {
    "completed_nodes": 2,
    "total_nodes": 5
  },
  "nodes": [
    {
      "hostname": "node-1",
      "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
      "upgrade_id": "550e8400-e29b-41d4-a716-446655440000",
      "package_name": "github-enterprise-3.19.3-kvm.pkg",
      "status": "completed",
      "progress": "100%",
      "error": ""
    },
    {
      "hostname": "node-2",
      "uuid": "228406d4-f97c-11ed-ab01-062281bbcf03",
      "upgrade_id": "550e8400-e29b-41d4-a716-446655440000",
      "package_name": "github-enterprise-3.19.3-kvm.pkg",
      "status": "downloading",
      "progress": "63%",
      "error": ""
    }
  ]
}

Get the upgrade status

Gets the upgrade status from all configured nodes of a GitHub Enterprise Server instance. Returns information about the current upgrade phase, completion status, and individual step details when is_verbose mode is enabled.

Parameter für "Get the upgrade status"

Abfrageparameter
Name, Typ, BESCHREIBUNG
`uuid` string The UUID which identifies a node.
`is_verbose` boolean Whether to include detailed step information.

HTTP-Antwortstatuscodes für "Get the upgrade status"

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

Codebeispiele für "Get the upgrade status"

Anforderungsbeispiel

get/manage/v1/upgrade/status

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  https://HOSTNAME/manage/v1/upgrade/status

OK

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
    "release_version": "3.19.2",
    "release_sha": "abc123def456",
    "status": "in_progress",
    "pre_upgrade_status": "completed",
    "upgrade_last_completed_step": "extract_root_filesystem",
    "is_running": true,
    "failed": false,
    "steps": [
      {
        "phase": "pre-upgrade",
        "step": "signature_verification",
        "status": "completed",
        "started_at": "2024-06-02T10:30:00Z",
        "ended_at": "2024-06-02T10:31:00Z",
        "error": ""
      }
    ],
    "messages": [],
    "error": ""
  }
]

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"

Abfrageparameter
Name, Typ, 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"

Anforderungsbeispiel

get/manage/v1/version

curl -L \
  -u "api_key:your-password" \
  -H "Content-Type: application/json" \
  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"
    }
  }
]