Конечные точки REST API для консоли управления
Используйте REST API для управления установкой GitHub Enterprise Server.
About the Management Console endpoints
The full functionality of the Management Console endpoints was added to the Manage GHES endpoints in GitHub Enterprise Server version 3.12. With feature parity achieved, the Management Console API endpoints will be removed in version 3.15.
About the Management Console
You should explicitly set the port number when making API calls to the Management Console. If TLS is enabled on your enterprise, the port number is 8443
. Otherwise, the port number is 8080
.
If you cannot provide a port number, you'll need to configure your tool to automatically follow redirects.
You may also need to add the -k
flag when using curl
, since GitHub Enterprise Server uses a self-signed certificate before you add your own TLS certificate.
Authentication as the root site administrator
You need to pass your root site administrator password as an authentication token to every endpoint in this category except "Create a GitHub license."
Use the api_key
parameter to send this token with each request. For example:
curl -L 'https://HOSTNAME:ADMIN-PORT/setup/api?api_key=YOUR_PASSWORD'
You can also use standard HTTP authentication to send this token. For example:
curl -L -u "api_key:YOUR_PASSWORD" 'https://HOSTNAME:ADMIN-PORT/setup/api'
Authentication as a Management Console user
Management Console user accounts can also authenticate to access this endpoint.
To authenticate with the password for a Management Console user account, use standard HTTP authentication. In the following example, replace YOUR_USER_NAME and YOUR_PASSWORD with the account's user name and 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 |
Коды состояния http-ответа для "Get the configuration status"
Код состояния | Описание |
---|---|
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:
Коды состояния http-ответа для "Start a configuration process"
Код состояния | Описание |
---|---|
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:
Коды состояния http-ответа для "Get the maintenance status"
Код состояния | Описание |
---|---|
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"
Имя., Тип, Description |
---|
maintenance string Обязательное полеA JSON string with the attributes The possible values for The possible values for |
Коды состояния http-ответа для "Enable or disable maintenance mode"
Код состояния | Описание |
---|---|
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.
Коды состояния http-ответа для "Get settings"
Код состояния | Описание |
---|---|
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"
Имя., Тип, Description |
---|
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. |
Коды состояния http-ответа для "Set settings"
Код состояния | Описание |
---|---|
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
Коды состояния http-ответа для "Get all authorized SSH keys"
Код состояния | Описание |
---|---|
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"
Имя., Тип, Description |
---|
authorized_key string Обязательное полеThe public SSH key. |
Коды состояния http-ответа для "Add an authorized SSH key"
Код состояния | Описание |
---|---|
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"
Имя., Тип, Description |
---|
authorized_key string Обязательное полеThe public SSH key. |
Коды состояния http-ответа для "Remove an authorized SSH key"
Код состояния | Описание |
---|---|
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"
Имя., Тип, Description |
---|
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. |
Коды состояния http-ответа для "Create a GitHub license"
Код состояния | Описание |
---|---|
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"
Имя., Тип, Description |
---|
license string The content of your new .ghl license file. |
Коды состояния http-ответа для "Upgrade a license"
Код состояния | Описание |
---|---|
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