# GitHub Enterprise Server を管理するための REST API エンドポイント

REST API を使用して、 GitHub Enterprise Server インスタンスを管理します。

## GitHub Enterprise Server管理 API について

お使いの GitHub Enterprise Server インスタンス管理 API を使用してGitHub Enterprise Serverを管理できます。 たとえば、インスタンスで実行されている GitHub Enterprise Server ソフトウェアのバージョンに関する情報を取得したり、複数のノードを持つインスタンスでレプリケーションの状態を表示したりできます。

> \[!TIP] この API を使用して、\*\*\*\* バージョン 3.15 で削除されたGitHub Enterprise Server の機能を置き換えることができます。

Manage GitHub Enterprise Server API のエンドポイントに対して API 呼び出しを行うときにポート番号を指定します。 インスタンスで TLS が使われる場合、ポート番号は 8443 です。 それ以外の場合、ポート番号は 8080 です。 ポート番号を提供できない場合は、自動的にリダイレクトに従うようにクライアントを構成する必要があります。 詳しくは、「[TLSの設定](/ja/enterprise-server@3.22/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-tls)」をご覧ください。

GitHub Enterprise ServerのGitHub CLI拡張機能を使用して、manage GitHub Enterprise Server API でエンドポイントを呼び出すこともできます。 詳細については、[`github/gh-es`](https://github.com/github/gh-es/blob/main/README.md) リポジトリを参照してください。

### 認証

Manage GitHub Enterprise Server API のエンドポイントに対する要求を認証するには、インスタンスのルート サイト管理者アカウントのパスワードを認証トークンとして指定します。 標準の HTTP 認証を使ってパスワードを送ります。
`api_key` ユーザーがルート サイト管理者を特定します。 次のサンプルは、この API の認証の例になっています。 ROOT-SITE-ADMINISTRATOR-PASSWORD をパスワードに変え、ADMINISTRATION-PORT を 8443 か 8080 に変えます。

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

### \[Management Console] ユーザーとしての認証

\[Management Console] ユーザー アカウントは、これらのエンドポイントにアクセスするために認証することもできます。 詳しくは、「[管理コンソールへのアクセスの管理](/ja/enterprise-server@3.22/admin/administering-your-instance/administering-your-instance-from-the-web-ui/managing-access-to-the-management-console#management-console-user)」をご覧ください。

\[Management Console] ユーザー アカウントのパスワードで認証するには、標準の HTTP 認証を使用します。 次の例では、YOUR\_USER\_NAME と YOUR\_PASSWORD をアカウントのユーザー名とパスワードに置き換えます。

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

### クエリ パラメーター

既定では、応答には、インスタンスに対して構成されているすべてのノードに関する情報が含まれます。 複数のノードを持つインスタンスでは、詳細は `/data/user/common/cluster.conf` から生成されます。 次のクエリ パラメーターを使用して、特定のノードに関する情報の応答をフィルター処理できます。

| Query parameter (クエリ パラメーター) | 説明                                                                                                                                                                          |
| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                       | ノード用の一意の識別子。                                                                                                                                                                |
| `cluster_role`               | クラスター内のノードの場合、ノードに適用されるロール。 詳しくは、「[クラスタノードについて](/ja/enterprise-server@3.22/admin/monitoring-and-managing-your-instance/configuring-clustering/about-cluster-nodes)」をご覧ください。 |

値をコンマで区切ることで、クエリ パラメーターに複数の値を指定できます。 たとえば、次の要求は curl を使用して、`web-server` または `storage-server` ロールを持つノードを返します。

```shell
curl -L -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" 'http(s)://HOSTNAME:ADMINISTRATION-PORT/manage/v1/config/nodes?cluster_role=WebServer,StorageServer'
```

> \[!NOTE]
> Most endpoints use `Authorization: Bearer <YOUR-TOKEN>` and `Accept: application/vnd.github+json` headers, plus `X-GitHub-Api-Version: 2026-03-10`. Curl examples below omit these standard headers for brevity.

## Get the configured SSH keys

```
GET /manage/v1/access/ssh
```

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

### HTTP response status codes

* **200** - OK

* **400** - Bad request

* **401** - Unauthorized

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/manage/v1/access/ssh
```

**Response schema (Status: 200):**

Array of objects:

* `key`: string, format: ssh-key
* `fingerprint`: string, format: ssh-key fingerprint

## Set a new SSH key

```
POST /manage/v1/access/ssh
```

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

### Parameters

#### Body parameters

* **`key`** (string) (required)
  The public SSH key to add to the authorized\_keys file.

### HTTP response status codes

* **200** - OK

* **400** - Bad request

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X POST \
  http(s)://HOSTNAME/manage/v1/access/ssh \
  -d '{
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADCIABAAAAgQCY/ZiDDOFWcZnYXPwMbvwQDofXPdHxLfxPK+HWGVPd1DLcDncYBUSB0bmCU2g9Sc+oHKLoHhXp0ivau9h+EpmQJ7V8vqsRdD9pc4aL/WAnUyF4o3Y7xL94rlRpVbVo/tNjzcvqxxyzBiYyy3GciCMpYQh/uKt56B94/5PNyIGEEw=="
}'
```

**Response schema (Status: 200):**

Array of objects:

* `hostname`: string, format: hostname
* `uuid`: string, format: uuid
* `message`: string
* `error`: string
* `modified`: boolean

## Delete a SSH key

```
DELETE /manage/v1/access/ssh
```

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

### Parameters

#### Body parameters

* **`key`** (string) (required)
  The public SSH key to remove from the authorized\_keys file.

### HTTP response status codes

* **200** - OK

* **400** - Bad request

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X DELETE \
  http(s)://HOSTNAME/manage/v1/access/ssh \
  -d '{
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADCIABAAAAgQCY/ZiDDOFWcZnYXPwMbvwQDofXPdHxLfxPK+HWGVPd1DLcDncYBUSB0bmCU2g9Sc+oHKLoHhXp0ivau9h+EpmQJ7V8vqsRdD9pc4aL/WAnUyF4o3Y7xL94rlRpVbVo/tNjzcvqxxyzBiYyy3GciCMpYQh/uKt56B94/5PNyIGEEw=="
}'
```

**Response schema (Status: 200):**

Array of objects:

* `hostname`: string, format: hostname
* `uuid`: string, format: uuid
* `message`: string
* `error`: string

## Get the system requirement check results for configured cluster nodes

```
GET /manage/v1/checks/system-requirements
```

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 response status codes

* **200** - OK

* **400** - Bad request

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/manage/v1/checks/system-requirements
```

**Response schema (Status: 200):**

* `status`: string, enum: `OK`, `FAILED`
* `nodes`: array of objects:
  * `hostname`: string
  * `status`: string, enum: `OK`, `FAILED`
  * `roles_status`: array of objects:
    * `status`: string, enum: `OK`, `FAILED`
    * `role`: string

## Get the status of services running on all cluster nodes

```
GET /manage/v1/cluster/status
```

Gets the status of all services running on each cluster node.
This endpoint may take several seconds to reply.

### HTTP response status codes

* **200** - OK

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/manage/v1/cluster/status
```

**Response schema (Status: 200):**

* `status`: string, enum: `UNKNOWN`, `OK`, `WARNING`, `CRITICAL`
* `nodes`: array of objects:
  * `hostname`: string
  * `status`: string, enum: `UNKNOWN`, `OK`, `WARNING`, `CRITICAL`
  * `services`: array of objects:
    * `status`: string, enum: `UNKNOWN`, `OK`, `WARNING`, `CRITICAL`
    * `name`: string
    * `details`: string

## Get the status of a ghe-config-apply run

```
GET /manage/v1/config/apply
```

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

### Parameters

#### Path and query parameters

* **`run_id`** (string)
  The unique run ID of the ghe-config-apply run.

### HTTP response status codes

* **200** - OK

* **400** - Bad request

* **401** - Unauthorized

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/manage/v1/config/apply
```

**Response schema (Status: 200):**

* `running`: boolean
* `successful`: boolean
* `nodes`: array of objects:
  * `run_id`: string
  * `hostname`: string
  * `running`: boolean
  * `successful`: boolean

## Trigger a ghe-config-apply run

```
POST /manage/v1/config/apply
```

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.

### Parameters

#### Body parameters

* **`run_id`** (string)
  The run ID to execute ghe-config-apply with. If not provided, a run ID will be generated randomly.

### HTTP response status codes

* **200** - OK

* **400** - Bad request

* **401** - Unauthorized

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X POST \
  http(s)://HOSTNAME/manage/v1/config/apply \
  -d '{
  "run_id": "d34db33f"
}'
```

**Response schema (Status: 200):**

* `run_id`: string

## List events from ghe-config-apply

```
GET /manage/v1/config/apply/events
```

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

### Parameters

#### Path and query parameters

* **`last_request_id`** (string)
  The unique ID of the last response from a host, used for pagination.

### HTTP response status codes

* **200** - OK

* **400** - Bad request

* **401** - Unauthorized

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/manage/v1/config/apply/events
```

**Response schema (Status: 200):**

* `nodes`: array of objects:
  * `node`: string
  * `last_request_id`: string
  * `events`: array of objects:
    * `timestamp`: string
    * `severity_text`: string
    * `body`: string
    * `event_name`: string
    * `topology`: string
    * `hostname`: string
    * `config_run_id`: string
    * `trace_id`: string
    * `span_id`: string
    * `span_parent_id`: string
    * `span_depth`: integer

## Initialize instance configuration with license and password

```
POST /manage/v1/config/init
```

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.

### Parameters

#### Body parameters

* **`license`** (string) (required)
  The content of your .ghl license file.

* **`password`** (string) (required)
  The root site administrator password.

### HTTP response status codes

* **202** - Accepted

* **400** - Bad request

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X POST \
  http(s)://HOSTNAME/manage/v1/config/init \
  -d '{
  "license": "@enterprise.ghl",
  "password": "provide-password-here!"
}'
```

**Response schema (Status: 202):**

## Get the enterprise license information

```
GET /manage/v1/config/license
```

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

### HTTP response status codes

* **200** - OK

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/manage/v1/config/license
```

**Response schema (Status: 200):**

* `advancedSecurityEnabled`: boolean
* `advancedSecuritySeats`: integer
* `clusterSupport`: boolean
* `company`: string
* `croquetSupport`: boolean
* `customTerms`: boolean
* `evaluation`: boolean
* `expireAt`: string, format: date-time
* `insightsEnabled`: boolean
* `insightsExpireAt`: string, format: date-time
* `learningLabEvaluationExpires`: string, format: date-time
* `learningLabSeats`: integer
* `perpetual`: boolean
* `referenceNumber`: string
* `seats`: integer
* `sshAllowed`: boolean
* `supportKey`: string
* `unlimitedSeating`: boolean

## Upload an enterprise license

```
PUT /manage/v1/config/license
```

Uploads a new enterprise license. In order to apply it right away, use the apply query parameter.
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.

### Parameters

#### Path and query parameters

* **`apply`** (boolean)
  Whether to instantly apply changes from the license. Otherwise the new license can be applied using the /manage/v1/config/apply endpoint.

#### Body parameters

* **`license`** (string) (required)
  The content of your .ghl license file.

### HTTP response status codes

* **201** - Created

* **202** - Accepted

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example 1: Status Code 201

**Request:**

```curl
curl -L \
  -X PUT \
  http(s)://HOSTNAME/manage/v1/config/license \
  -d '{
  "license": "@enterprise.ghl"
}'
```

**Response schema (Status: 201):**

#### Example 2: Status Code 202

**Request:**

```curl
curl -L \
  -X PUT \
  http(s)://HOSTNAME/manage/v1/config/license \
  -d '{
  "license": "@enterprise.ghl"
}'
```

**Response schema (Status: 202):**

## Check a license

```
GET /manage/v1/config/license/check
```

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

### HTTP response status codes

* **200** - OK

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/manage/v1/config/license/check
```

**Response schema (Status: 200):**

* `status`: string, enum: `valid`, `invalid`, `expired`, `cluster mode not supported`

## Get GHES node metadata for all nodes

```
GET /manage/v1/config/nodes
```

Get node metadata for all configured nodes in the current cluster. For more information, see "About clustering."

### Parameters

#### Path and query parameters

* **`uuid`** (string)
  The UUID which identifies a node.

* **`cluster_roles`** (string)
  The cluster roles from the cluster configuration file.

### HTTP response status codes

* **200** - OK

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/manage/v1/config/nodes
```

**Response schema (Status: 200):**

* `topology`: string, enum: `SingleNode`, `Ha`, `Cluster`
* `nodes`: array of objects:
  * `hostname`: string
  * `uuid`: string
  * `replica`: boolean
  * `cluster_roles`: array of string, enum: `Blank`, `ActionsServer`, `ConsulServer`, `ElasticsearchServer`, `GitServer`, `JobServer`, `LaunchServer`, `MemcacheServer`, `MetricsServer`, `MssqlServer`, `MysqlServer`, `PagesServer`, `RedisServer`, `StorageServer`, `WebServer`

## Get the GHES settings

```
GET /manage/v1/config/settings
```

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

### HTTP response status codes

* **200** - OK

* **400** - Bad request

* **401** - Unauthorized

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/manage/v1/config/settings
```

**Response schema (Status: 200):**

* `private_mode`: boolean
* `public_pages`: boolean
* `subdomain_isolation`: boolean
* `signup_enabled`: boolean
* `github_hostname`: string
* `identicons_host`: string
* `http_proxy`: string or null
* `auth_mode`: string
* `expire_sessions`: boolean
* `admin_password`: string or null
* `configuration_id`: integer
* `configuration_run_count`: integer
* `avatar`: object:
  * `enabled`: boolean
  * `uri`: string
* `customer`: object:
  * `name`: string
  * `email`: string
  * `uuid`: string
  * `secret_key_data`: string
  * `public_key_data`: string
* `license`: object:
  * `seats`: integer
  * `evaluation`: boolean
  * `perpetual`: boolean
  * `unlimited_seating`: boolean
  * `support_key`: string
  * `ssh_allowed`: boolean
  * `cluster_support`: boolean
  * `expire_at`: string
* `github_ssl`: object:
  * `enabled`: boolean
  * `cert`: string or null
  * `key`: string or null
* `ldap`: object:
  * `host`: string or null
  * `port`: integer
  * `base`: array of string
  * `uid`: string or null
  * `bind_dn`: string or null
  * `password`: string or null
  * `method`: string
  * `search_strategy`: string
  * `user_groups`: array of string
  * `admin_group`: string or null
  * `virtual_attribute_enabled`: boolean
  * `recursive_group_search`: boolean
  * `posix_support`: boolean
  * `user_sync_emails`: boolean
  * `user_sync_keys`: boolean
  * `user_sync_interval`: integer
  * `team_sync_interval`: integer
  * `sync_enabled`: boolean
  * `reconciliation`: object:
    * `user`: string or null
    * `org`: string or null
  * `profile`: object:
    * `uid`: string
    * `name`: string or null
    * `mail`: string or null
    * `key`: string or null
* `cas`: object:
  * `url`: string or null
* `saml`: object:
  * `sso_url`: string or null
  * `certificate`: string or null
  * `certificate_path`: string or null
  * `issuer`: string or null
  * `idp_initiated_sso`: boolean
  * `disable_admin_demote`: boolean
* `github_oauth`: object:
  * `client_id`: string
  * `client_secret`: string
  * `organization_name`: string
  * `organization_team`: string
* `smtp`: object:
  * `enabled`: boolean
  * `address`: string
  * `authentication`: string
  * `port`: string
  * `domain`: string
  * `username`: string
  * `user_name`: string
  * `enable_starttls_auto`: boolean
  * `password`: string
  * `discard-to-noreply-address`: boolean
  * `support_address`: string
  * `support_address_type`: string
  * `noreply_address`: string
* `ntp`: object:
  * `primary_server`: string
  * `secondary_server`: string
* `timezone`: string or null
* `snmp`: object:
  * `enabled`: boolean
  * `community`: string
* `syslog`: object:
  * `enabled`: boolean
  * `server`: string or null
  * `protocol_name`: string
* `assets`: string or null
* `pages`: object:
  * `enabled`: boolean
* `collectd`: object:
  * `enabled`: boolean
  * `server`: string or null
  * `port`: integer
  * `encryption`: string or null
  * `username`: string or null
  * `password`: string or null
* `mapping`: object:
  * `enabled`: boolean
  * `tileserver`: string or null
  * `basemap`: string
  * `token`: string or null
* `load_balancer`: string or null
* `prometheus`: object:
  * `enabled`: boolean
  * `trusted_ips`: string or null

## Set settings

```
PUT /manage/v1/config/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 response status codes

* **204** - No Content

* **400** - Bad request

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X PUT \
  http(s)://HOSTNAME/manage/v1/config/settings \
  -d '{
  "public_pages": true
}'
```

**Response schema (Status: 204):**

## Get the status of maintenance mode

```
GET /manage/v1/maintenance
```

Gets the status and details of maintenance mode on all available nodes. For more information, see "Enabling and scheduling maintenance mode."

### Parameters

#### Path and query parameters

* **`uuid`** (string)
  The UUID which identifies a node.

* **`cluster_roles`** (string)
  The cluster roles from the cluster configuration file.

### HTTP response status codes

* **200** - OK

* **400** - Bad request

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/manage/v1/maintenance
```

**Response schema (Status: 200):**

Array of objects:

* `hostname`: string, format: hostname
* `uuid`: string, format: uuid
* `status`: string, enum: `on`, `off`, `scheduled`
* `scheduled_time`: string, format: date
* `connection_services`: array of objects:
  * `name`: string
  * `number`: integer
* `can_unset_maintenance`: boolean
* `ip_exception_list`: array of string, format: ip/cidr
* `maintenance_mode_message`: string

## Set the status of maintenance mode

```
POST /manage/v1/maintenance
```

Sets or schedules the maintenance mode. For more information, see "Enabling and scheduling maintenance mode."

### Parameters

#### Body parameters

* **`enabled`** (boolean) (required)
  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 response status codes

* **200** - OK

* **400** - Bad request

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X POST \
  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 schema (Status: 200):**

Same response schema as [Delete a SSH key](#delete-a-ssh-key).

## Get the status of services running on all replica nodes

```
GET /manage/v1/replication/status
```

Gets the status of all services running on each replica node.
This endpoint may take several seconds to reply.

### Parameters

#### Path and query parameters

* **`uuid`** (string)
  The UUID which identifies a node.

* **`cluster_roles`** (string)
  The cluster roles from the cluster configuration file.

### HTTP response status codes

* **200** - OK

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/manage/v1/replication/status
```

**Response schema (Status: 200):**

Same response schema as [Get the status of services running on all cluster nodes](#get-the-status-of-services-running-on-all-cluster-nodes).

## Apply an upgrade

```
POST /manage/v1/upgrade/apply
```

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.

### Parameters

#### Body parameters

* **`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.
  Can be one of: `pre-upgrade`, `upgrade`

* **`skip_reboot`** (boolean)
  Whether to skip the reboot after the upgrade completes. Default is false.
  Default: `false`

* **`uuid`** (string)
  The UUID of a specific node to upgrade. When omitted, the upgrade is applied to all nodes.

### HTTP response status codes

* **200** - OK

* **400** - Bad request

* **401** - Unauthorized

* **404** - Not found

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X POST \
  https://HOSTNAME/manage/v1/upgrade/apply \
  -d '{
  "version": "3.19.3"
}'
```

**Response schema (Status: 200):**

Array of objects:

* `hostname`: string
* `uuid`: string
* `message`: string
* `error`: string

## Download an upgrade package

```
POST /manage/v1/upgrade/download
```

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.

### Parameters

#### Body parameters

* **`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.
  Default: `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.
  Default: `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.
  Default: `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.
  Default: `3`

### HTTP response status codes

* **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

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X POST \
  https://HOSTNAME/manage/v1/upgrade/download \
  -d '{
  "version": "3.19.3",
  "force": false
}'
```

**Response schema (Status: 200):**

Array of objects:

* `hostname`: string
* `uuid`: string
* `download_id`: string
* `message`: string
* `error`: string

## Get the upgrade package download status

```
GET /manage/v1/upgrade/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.

### Parameters

#### Path and query parameters

* **`uuid`** (string)
  The UUID which identifies a node.

### HTTP response status codes

* **200** - OK

* **400** - Bad request

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example 1: Status Code 200

**Request:**

```curl
curl -L \
  -X GET \
  https://HOSTNAME/manage/v1/upgrade/download/status
```

**Response schema (Status: 200):**

* `download_id`: string
* `package_name`: string
* `status`: string, enum: `not_started`, `downloading`, `completed`, `failed`
* `error_message`: string
* `nodes`: array of objects:
  * `hostname`: string
  * `uuid`: string
  * `download_id`: string
  * `package_name`: string
  * `status`: string, enum: `not_started`, `downloading`, `completed`, `failed`
  * `progress`: string
  * `error`: string
* `orchestration`: object:
  * `phase`: string, enum: `running`, `completed`, `failed`
  * `error_message`: string
  * `max_parallel`: integer
  * `queued`: integer
  * `in_flight`: integer
  * `completed`: integer
  * `failed`: integer
  * `total`: integer

#### Example 2: Status Code 200

**Request:**

```curl
curl -L \
  -X GET \
  https://HOSTNAME/manage/v1/upgrade/download/status
```

**Response schema (Status: 200):**

* `download_id`: string
* `package_name`: string
* `status`: string, enum: `not_started`, `downloading`, `completed`, `failed`
* `error_message`: string
* `nodes`: array of objects:
  * `hostname`: string
  * `uuid`: string
  * `download_id`: string
  * `package_name`: string
  * `status`: string, enum: `not_started`, `downloading`, `completed`, `failed`
  * `progress`: string
  * `error`: string
* `orchestration`: object:
  * `phase`: string, enum: `running`, `completed`, `failed`
  * `error_message`: string
  * `max_parallel`: integer
  * `queued`: integer
  * `in_flight`: integer
  * `completed`: integer
  * `failed`: integer
  * `total`: integer

## Get the upgrade status

```
GET /manage/v1/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.

### Parameters

#### Path and query parameters

* **`uuid`** (string)
  The UUID which identifies a node.

* **`is_verbose`** (boolean)
  Whether to include detailed step information.

### HTTP response status codes

* **200** - OK

* **400** - Bad request

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  https://HOSTNAME/manage/v1/upgrade/status
```

**Response schema (Status: 200):**

Array of objects:

* `hostname`: string
* `uuid`: string
* `release_version`: string or null
* `release_sha`: string or null
* `status`: string, enum: `not_started`, `in_progress`, `completed`, `failed`
* `pre_upgrade_status`: string, enum: `not_started`, `in_progress`, `completed`, `failed`
* `upgrade_last_completed_step`: string or null
* `is_running`: boolean
* `failed`: boolean
* `steps`: array of objects:
  * `phase`: string
  * `step`: string
  * `status`: string
  * `started_at`: string, format: date-time
  * `ended_at`: string, format: date-time
  * `error`: string
* `messages`: array of string
* `error`: string

## Get all GHES release versions for all nodes

```
GET /manage/v1/version
```

Gets the GitHub Enterprise Server release versions that are currently installed on all available nodes. For more information, see "GitHub Enterprise Server releases."

### Parameters

#### Path and query parameters

* **`uuid`** (string)
  The UUID which identifies a node.

* **`cluster_roles`** (string)
  The cluster roles from the cluster configuration file.

### HTTP response status codes

* **200** - OK

* **401** - Unauthorized

* **500** - Internal error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/manage/v1/version
```

**Response schema (Status: 200):**

Array of objects:

* `hostname`: string, format: hostname
* `version`: object:
  * `version`: string, pattern: `[0-9]\.[0-9]{2}\.[0-9]`
  * `platform`: string, enum: `ami`, `azure`, `esx`, `gce`, `hyperv`, `kvm`
  * `build_id`: string, pattern: `[0-9a-f]{8}`
  * `build_date`: string, format: date