이제 REST API의 버전이 지정되었습니다. 자세한 내용은 "API 버전 관리 정보"를 참조하세요.

GitHub Enterprise Server를 관리하기 위한 REST API 엔드포인트

REST API를 사용하여 인스턴스를 관리합니다 GitHub Enterprise Server .

GitHub Enterprise Server API 관리에 관한 정보

GitHub Enterprise Server 인스턴스를 관리하려면 관리 GitHub Enterprise Server API를 사용할 수 있습니다. 예를 들어 인스턴스 또는 여러 노드가 있는 인스턴스에서 실행되는 소프트웨어 버전 GitHub Enterprise Server 에 대한 정보를 검색하여 복제 상태를 볼 수 있습니다.

팁

이 API를 사용하여 버전 3.15에서 **** 제거된 GitHub Enterprise Server의 기능을 바꿀 수 있습니다.

관리 GitHub Enterprise Server API에 대한 엔드포인트에 대한 API 호출을 할 때 포트 번호를 지정합니다. 인스턴스에서 TLS를 사용하는 경우 포트 번호는 8443입니다. 그렇지 않은 경우 포트 번호는 8080입니다. 포트 번호를 제공할 수 없는 경우 리디렉션을 자동으로 따르도록 클라이언트를 구성해야 합니다. 자세한 내용은 TLS 구성을(를) 참조하세요.

또한 GitHub Enterprise Server의 GitHub CLI 확장을 사용하여 GitHub Enterprise Server API 관리의 엔드포인트를 호출할 수 있습니다. 자세한 내용은 github/gh-es 리포지토리를 참조하세요.

인증

관리 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'

관리 콘솔 사용자로 인증하기

관리 콘솔 사용자 계정은 이러한 엔드포인트에 액세스하도록 인증할 수도 있습니다. 자세한 내용은 관리 콘솔에 대한 액세스 관리을(를) 참조하세요.

사용자 계정의 암호를 사용하여 인증하려면 표준 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에서 시작됩니다. 다음 쿼리 매개 변수를 사용하여 특정 노드에 대한 정보 응답을 필터링할 수 있습니다.

쿼리 매개 변수	설명
`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 configured SSH keys

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

"Get the configured SSH keys"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`400`	Bad request
`401`	Unauthorized

"Get the configured SSH keys"에 대한 코드 샘플

요청 예제

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

"Set a new SSH key"에 대한 매개 변수

본문 매개 변수
이름, 유형, 설명
`key` string 필수 The public SSH key to add to the `authorized_keys` file.

"Set a new SSH key"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

"Set a new SSH key"에 대한 코드 샘플

요청 예제

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

"Delete a SSH key"에 대한 매개 변수

본문 매개 변수
이름, 유형, 설명
`key` string 필수 The public SSH key to remove from the `authorized_keys` file.

"Delete a SSH key"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

"Delete a SSH key"에 대한 코드 샘플

요청 예제

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.

"Get the system requirement check results for configured cluster nodes"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`400`	Bad request
`500`	Internal error

"Get the system requirement check results for configured cluster nodes"에 대한 코드 샘플

요청 예제

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.

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

"Get the status of a ghe-config-apply run"에 대한 매개 변수

쿼리 매개 변수
이름, 유형, 설명
`run_id` string The unique run ID of the `ghe-config-apply` run.

"Get the status of a ghe-config-apply run"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`400`	Bad request
`401`	Unauthorized

"Get the status of a ghe-config-apply run"에 대한 코드 샘플

요청 예제

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.

"Trigger a ghe-config-apply run"에 대한 매개 변수

본문 매개 변수
이름, 유형, 설명
`run_id` string The run ID to execute `ghe-config-apply` with. If not provided, a run ID will be generated randomly.

"Trigger a ghe-config-apply run"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`400`	Bad request
`401`	Unauthorized

"Trigger a ghe-config-apply run"에 대한 코드 샘플

요청 예제

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.

"List events from ghe-config-apply"에 대한 매개 변수

쿼리 매개 변수
이름, 유형, 설명
`last_request_id` string The unique ID of the last response from a host, used for pagination.

"List events from ghe-config-apply"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`400`	Bad request
`401`	Unauthorized

"List events from ghe-config-apply"에 대한 코드 샘플

요청 예제

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.

"Initialize instance configuration with license and password"에 대한 매개 변수

본문 매개 변수
이름, 유형, 설명
`license` string 필수 The content of your .ghl license file.
`password` string 필수 The root site administrator password.

"Initialize instance configuration with license and password"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`202`	Accepted
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

"Initialize instance configuration with license and password"에 대한 코드 샘플

요청 예제

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.

"Get the enterprise license information"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`401`	Unauthorized
`500`	Internal error

"Get the enterprise license information"에 대한 코드 샘플

요청 예제

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

"Upload an enterprise license"에 대한 매개 변수

쿼리 매개 변수
이름, 유형, 설명
`apply` boolean Whether to instantly apply changes from the license. Otherwise the new license can be applied using the `/manage/v1/config/apply` endpoint.

본문 매개 변수
이름, 유형, 설명
`license` string 필수 The content of your .ghl license file.

"Upload an enterprise license"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`201`	Created
`202`	Accepted
`401`	Unauthorized
`500`	Internal error

"Upload an enterprise license"에 대한 코드 샘플

요청 예제

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.

"Check a license"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`401`	Unauthorized
`500`	Internal error

"Check a license"에 대한 코드 샘플

요청 예제

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

"Get GHES node metadata for all nodes"에 대한 매개 변수

쿼리 매개 변수
이름, 유형, 설명
`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" \
  -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.

"Get the GHES settings"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`400`	Bad request
`401`	Unauthorized

"Get the GHES settings"에 대한 코드 샘플

요청 예제

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

"Set settings"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`204`	No Content
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

"Set settings"에 대한 코드 샘플

요청 예제

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

"Get the status of maintenance mode"에 대한 매개 변수

쿼리 매개 변수
이름, 유형, 설명
`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" \
  -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."

"Set the status of maintenance mode"에 대한 매개 변수

본문 매개 변수
이름, 유형, 설명
`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" \
  -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.

"Get the status of services running on all replica nodes"에 대한 매개 변수

쿼리 매개 변수
이름, 유형, 설명
`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" \
  -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.

"Apply an upgrade"에 대한 매개 변수

본문 매개 변수
이름, 유형, 설명
`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. 다음 중 하나일 수 있습니다.: `pre-upgrade`, `upgrade`
`skip_reboot` boolean Whether to skip the reboot after the upgrade completes. Default is `false`. 기본값: `false`
`uuid` string The UUID of a specific node to upgrade. When omitted, the upgrade is applied to all nodes.

"Apply an upgrade"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`400`	Bad request
`401`	Unauthorized
`404`	Not found
`500`	Internal error

"Apply an upgrade"에 대한 코드 샘플

요청 예제

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.

"Download an upgrade package"에 대한 매개 변수

본문 매개 변수
이름, 유형, 설명
`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. 기본값: `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. 기본값: `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. 기본값: `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. 기본값: `3`

"Download an upgrade package"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`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

"Download an upgrade package"에 대한 코드 샘플

요청 예제

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.

"Get the upgrade package download status"에 대한 매개 변수

쿼리 매개 변수
이름, 유형, 설명
`uuid` string The UUID which identifies a node.

"Get the upgrade package download status"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

"Get the upgrade package download status"에 대한 코드 샘플

요청 예제

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.

"Get the upgrade status"에 대한 매개 변수

쿼리 매개 변수
이름, 유형, 설명
`uuid` string The UUID which identifies a node.
`is_verbose` boolean Whether to include detailed step information.

"Get the upgrade status"에 대한 HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

"Get the upgrade status"에 대한 코드 샘플

요청 예제

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

"Get all GHES release versions for all nodes"에 대한 매개 변수

쿼리 매개 변수
이름, 유형, 설명
`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" \
  -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"
    }
  }
]