管理コンソール用の REST API エンドポイント
REST API を使って、GitHub Enterprise Server のインストールを管理します。
管理コンソール エンドポイントについて
管理コンソール エンドポイントの完全な機能は、GitHub Enterprise Server バージョン 3.12 のGHES の管理 エンドポイントに追加されました。 機能パリティの実現により、管理コンソール API エンドポイントはバージョン 3.15 で削除されます。
移行を支援するために、次のマッピング テーブルに、各管理コンソールの操作に相当する GHES の管理の操作を示します。できるだけ早く GHES API エンドポイントの管理に移行してください。
パーパス | 管理コンソール API の操作 | GHES API の管理の操作 |
---|---|---|
構成の状態を取得する | GET /setup/api/configcheck | GET /manage/v1/config/apply |
構成プロセスを開始する | POST /setup/api/configure | POST /manage/v1/config/apply |
メンテナンスの状態を取得する | GET /setup/api/maintenance | GET /manage/v1/maintenance |
メンテナンス モードを有効または無効にする | POST /setup/api/maintenance | POST /manage/v1/maintenance |
設定を取得する | GET /setup/api/settings | GET /manage/v1/config/settings |
設定をセットする | PUT /setup/api/settings | PUT /manage/v1/config/settings |
すべての認証済み SSH キーを取得する | GET /setup/api/settings/authorized-keys | GET /manage/v1/access/ssh |
認証済み SSH キーを追加する | POST /setup/api/settings/authorized-keys | POST /manage/v1/access/ssh |
認証済み SSH キーを削除する | DELETE /setup/api/settings/authorized-keys | DELETE /manage/v1/access/ssh |
GitHub ライセンスを作成する | POST /setup/api/start | POST /manage/v1/config/init |
ライセンスをアップグレードする | POST /setup/api/upgrade | PUT /manage/v1/config/license |
[Management Console]について
管理コンソールへの API 呼び出しを行うときは、ポート番号を明示的に設定する必要があります。 エンタープライズで TLS が有効になっている場合、ポート番号は 8443
です。 それ以外の場合、ポート番号は 8080
です。
ポート番号を提供できない場合は、自動的にリダイレクトに従うようにツールを構成する必要があります。
また、GitHub Enterprise Server では、独自の TLS 証明書を追加する前は自己署名証明書が使われるため、curl
を使うとき、場合によっては -k
フラグ を追加する必要があります。
ルート サイト管理者としての認証
「Create a GitHub license」を除く、このカテゴリのすべてのエンドポイントにルート サイト管理者のパスワードを渡す必要があります。
各要求でこのトークンを送るには、api_key
パラメーターを使います。 たとえば、次のような点です。
curl -L 'https://HOSTNAME:ADMIN-PORT/setup/api?api_key=YOUR_PASSWORD'
標準の HTTP 認証を使用してこのトークンを送信することもできます。 次に例を示します。
curl -L -u "api_key:YOUR_PASSWORD" 'https://HOSTNAME:ADMIN-PORT/setup/api'
[Management Console] ユーザーとしての認証
Management Console のユーザー アカウントで、このエンドポイントにアクセスするための認証を行うこともできます。
[Management Console] ユーザー アカウントのパスワードを使って認証を行うには、標準の HTTP 認証を使います。 次の例では、YOUR_USER_NAME と YOUR_PASSWORD をアカウントのユーザー名とパスワードに置き換えます。
curl -L -u "YOUR_USER_NAME:YOUR_PASSWORD" 'https://HOSTNAME:ADMIN-PORT/setup/api'
Get the configuration status
This endpoint allows you to check the status of the most recent configuration process:
Note that you may need to wait several seconds after you start a process before you can check its status.
The different statuses are:
Status | Description |
---|---|
PENDING | The job has not started yet |
CONFIGURING | The job is running |
DONE | The job has finished correctly |
FAILED | The job has finished unexpectedly |
"Get the configuration status" の HTTP 応答状態コード
状態コード | 説明 |
---|---|
200 | OK |
401 | Unauthorized |
"Get the configuration status" のコード サンプル
要求の例
curl -L \
-u "api_key:your-password" \
http(s)://HOSTNAME/setup/api/configcheck
Response
Status: 200
{
"status": "running",
"progress": [
{
"status": "DONE",
"key": "Appliance core components"
},
{
"status": "DONE",
"key": "GitHub utilities"
},
{
"status": "DONE",
"key": "GitHub applications"
},
{
"status": "CONFIGURING",
"key": "GitHub services"
},
{
"status": "PENDING",
"key": "Reloading appliance services"
}
]
}
Start a configuration process
This endpoint allows you to start a configuration process at any time for your updated settings to take effect:
"Start a configuration process" の HTTP 応答状態コード
状態コード | 説明 |
---|---|
202 | Accepted |
401 | Unauthorized |
"Start a configuration process" のコード サンプル
要求の例
curl -L \
-X POST \
-u "api_key:your-password" \
http(s)://HOSTNAME/setup/api/configure
Response
Status: 202
Get the maintenance status
Check your installation's maintenance status:
"Get the maintenance status" の HTTP 応答状態コード
状態コード | 説明 |
---|---|
200 | OK |
401 | Unauthorized |
"Get the maintenance status" のコード サンプル
要求の例
curl -L \
-u "api_key:your-password" \
http(s)://HOSTNAME/setup/api/maintenance
Response
Status: 200
{
"status": "scheduled",
"scheduled_time": "Tuesday, January 22 at 15:34 -0800",
"connection_services": [
{
"name": "git operations",
"number": 0
},
{
"name": "mysql queries",
"number": 233
},
{
"name": "aqueduct jobs",
"number": 34
},
{
"name": "resque jobs",
"number": 54
}
]
}
Enable or disable maintenance mode
Note
The request body for this operation must be submitted as application/x-www-form-urlencoded
data. You can submit a parameter value as a string, or you can use a tool such as curl
to submit a parameter value as the contents of a text file. For more information, see the curl
documentation.
"Enable or disable maintenance mode" のパラメーター
名前, Type, 説明 |
---|
maintenance string 必須A JSON string with the attributes The possible values for The possible values for |
"Enable or disable maintenance mode" の HTTP 応答状態コード
状態コード | 説明 |
---|---|
200 | OK |
401 | Unauthorized |
"Enable or disable maintenance mode" のコード サンプル
要求の例
curl -L \
-X POST \
-u "api_key:your-password" \
http(s)://HOSTNAME/setup/api/maintenance \
--data-urlencode 'maintenance={"enabled":true, "when":"now"}'
Response
Status: 200
{
"status": "scheduled",
"scheduled_time": "Tuesday, January 22 at 15:34 -0800",
"connection_services": [
{
"name": "git operations",
"number": 0
},
{
"name": "mysql queries",
"number": 233
},
{
"name": "aqueduct jobs",
"number": 34
},
{
"name": "resque jobs",
"number": 54
}
]
}
Get settings
Gets the settings for your instance. To change settings, see the Set settings endpoint.
Note
You cannot retrieve the management console password with the Enterprise administration API.
"Get settings" の HTTP 応答状態コード
状態コード | 説明 |
---|---|
200 | OK |
401 | Unauthorized |
"Get settings" のコード サンプル
要求の例
curl -L \
-u "api_key:your-password" \
http(s)://HOSTNAME/setup/api/settings
Response
Status: 200
{
"enterprise": {
"private_mode": false,
"public_pages": false,
"subdomain_isolation": true,
"signup_enabled": false,
"github_hostname": "ghe.local",
"identicons_host": "dotcom",
"http_proxy": null,
"auth_mode": "default",
"expire_sessions": false,
"admin_password": null,
"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)\n\nlQcYBE5TCgsBEACk4yHpUcapplebaumBMXYMiLF+nCQ0lxpx...\n-----END PGP PRIVATE KEY BLOCK-----\n",
"public_key_data": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: GnuPG v1.4.10 (GNU/Linux)\n\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"
},
"timezone": null,
"snmp": {
"enabled": false,
"community": ""
},
"syslog": {
"enabled": false,
"server": null,
"protocol_name": "udp"
},
"assets": null,
"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
},
"load_balancer": null
},
"run_list": [
"recipe[enterprise-configure]"
]
}
Set settings
Applies settings on your instance. For a list of the available settings, see the Get settings endpoint.
Notes:
- The request body for this operation must be submitted as
application/x-www-form-urlencoded
data. You can submit a parameter value as a string, or you can use a tool such ascurl
to submit a parameter value as the contents of a text file. For more information, see thecurl
documentation. - You cannot set the management console password with the Enterprise administration API. Use the
ghe-set-password
utility to change the management console password. For more information, see "Command-line utilities."
"Set settings" のパラメーター
名前, Type, 説明 |
---|
settings string 必須A JSON string with the new settings. Note that you only need to pass the specific settings you want to modify. For a list of the available settings, see the Get settings endpoint. |
"Set settings" の HTTP 応答状態コード
状態コード | 説明 |
---|---|
204 | No Content |
401 | Unauthorized |
"Set settings" のコード サンプル
要求の例
curl -L \
-X PUT \
-u "api_key:your-password" \
http(s)://HOSTNAME/setup/api/settings \
--data-urlencode 'settings={ "enterprise": { "public_pages": true }}'
Response
Status: 204
Get all authorized SSH keys
"Get all authorized SSH keys" の HTTP 応答状態コード
状態コード | 説明 |
---|---|
200 | OK |
401 | Unauthorized |
"Get all authorized SSH keys" のコード サンプル
要求の例
curl -L \
-u "api_key:your-password" \
http(s)://HOSTNAME/setup/api/settings/authorized-keys
Response
Status: 200
[
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
},
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
},
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
}
]
Add an authorized SSH key
Note: The request body for this operation must be submitted as application/x-www-form-urlencoded
data. You can submit a parameter value as a string, or you can use a tool such as curl
to submit a parameter value as the contents of a text file. For more information, see the curl
documentation.
"Add an authorized SSH key" のパラメーター
名前, Type, 説明 |
---|
authorized_key string 必須The public SSH key. |
"Add an authorized SSH key" の HTTP 応答状態コード
状態コード | 説明 |
---|---|
201 | Created |
401 | Unauthorized |
"Add an authorized SSH key" のコード サンプル
要求の例
curl -L \
-X POST \
-u "api_key:your-password" \
http(s)://HOSTNAME/setup/api/settings/authorized-keys \
--data-urlencode 'authorized_key=ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCssTL/Vtu/ODLTj0VtZoRAbvf7uiv5997GyDq0MoAZUjb5jmA5wYe2/wF6sFuhiZTnZoF1ZtCHunPp0hM/GHrn6VySBhNncx14YO8FPt1CIhEeRMSEjUK9cY3xAbS365oXY8vnUHJsS9+1tr/2bx/+4NJfcUt/Ezf1OR/0LStQXw=='
Response
Status: 201
[
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
},
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
},
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
}
]
Remove an authorized SSH key
Note: The request body for this operation must be submitted as application/x-www-form-urlencoded
data. You can submit a parameter value as a string, or you can use a tool such as curl
to submit a parameter value as the contents of a text file. For more information, see the curl
documentation.
"Remove an authorized SSH key" のパラメーター
名前, Type, 説明 |
---|
authorized_key string 必須The public SSH key. |
"Remove an authorized SSH key" の HTTP 応答状態コード
状態コード | 説明 |
---|---|
200 | OK |
401 | Unauthorized |
"Remove an authorized SSH key" のコード サンプル
要求の例
curl -L \
-X DELETE \
-u "api_key:your-password" \
http(s)://HOSTNAME/setup/api/settings/authorized-keys \
--data-urlencode 'authorized_key=ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCssTL/Vtu/ODLTj0VtZoRAbvf7uiv5997GyDq0MoAZUjb5jmA5wYe2/wF6sFuhiZTnZoF1ZtCHunPp0hM/GHrn6VySBhNncx14YO8FPt1CIhEeRMSEjUK9cY3xAbS365oXY8vnUHJsS9+1tr/2bx/+4NJfcUt/Ezf1OR/0LStQXw=='
Response
Status: 200
[
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
},
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
},
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
}
]
Create a GitHub license
When you boot a GitHub instance for the first time, you can use the following endpoint to upload a license.
Note that you need to POST
to /setup/api/configure
to start the actual configuration process.
When using this endpoint, your GitHub instance must have a password set. This can be accomplished two ways:
- If you're working directly with the API before accessing the web interface, you must pass in the password parameter to set your password.
- If you set up your instance via the web interface before accessing the API, your calls to this endpoint do not need the password 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.
"Create a GitHub license" のパラメーター
名前, Type, 説明 |
---|
license string 必須The content of your .ghl license file. |
password string You must provide a password only if you are uploading your license for the first time. If you previously set a password through the web interface, you don't need this parameter. |
settings string An optional JSON string containing the installation settings. For a list of the available settings, see the Get settings endpoint. |
"Create a GitHub license" の HTTP 応答状態コード
状態コード | 説明 |
---|---|
202 | Accepted |
401 | Unauthorized |
"Create a GitHub license" のコード サンプル
要求の例
curl -L \
-X POST \
-u "api_key:your-password" \
-H "Content-Type: multipart/form-data" \
http(s)://HOSTNAME/setup/api/start \
--form 'license=@enterprise.ghl' --form 'password=secret'
Response
Status: 202
Upgrade a license
This API upgrades your license and also triggers the configuration process.
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.
"Upgrade a license" のパラメーター
名前, Type, 説明 |
---|
license string The content of your new .ghl license file. |
"Upgrade a license" の HTTP 応答状態コード
状態コード | 説明 |
---|---|
202 | Accepted |
401 | Unauthorized |
"Upgrade a license" のコード サンプル
要求の例
curl -L \
-X POST \
-u "api_key:your-password" \
-H "Content-Type: multipart/form-data" \
http(s)://HOSTNAME/setup/api/upgrade \
--form 'license=@enterprise.ghl'
Response
Status: 202