Skip to main content
REST API 现已经过版本控制。 有关详细信息,请参阅“关于 API 版本控制”。

适用于管理控制台的 REST API 终结点

使用 REST API 管理 GitHub Enterprise Server 安装。

Deprecation of 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 deprecated in version 3.14.

To help you migrate, the mapping table below shows the equivalent Manage GHES operation for each Management Console operation. Please migrate to the Manage GHES API endpoints as soon as possible.

PurposeManagement Console API operationManage GHES API operation
Get the configuration statusGET /setup/api/configcheckGET /manage/v1/config/apply
Start a configuration processPOST /setup/api/configurePOST /manage/v1/config/apply
Get the maintenance statusGET /setup/api/maintenanceGET /manage/v1/maintenance
Enable or disable maintenance modePOST /setup/api/maintenancePOST /manage/v1/maintenance
Get settingsGET /setup/api/settingsGET /manage/v1/config/settings
Set settingsPUT /setup/api/settingsPUT /manage/v1/config/settings
Get all authorized SSH keysGET /setup/api/settings/authorized-keysGET /manage/v1/access/ssh
Add an authorized SSH keyPOST /setup/api/settings/authorized-keysPOST /manage/v1/access/ssh
Remove an authorized SSH keyDELETE /setup/api/settings/authorized-keysDELETE /manage/v1/access/ssh
Create a GitHub licensePOST /setup/api/startPOST /manage/v1/config/init
Upgrade a licensePOST /setup/api/upgradePUT /manage/v1/config/license

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:

StatusDescription
PENDINGThe job has not started yet
CONFIGURINGThe job is running
DONEThe job has finished correctly
FAILEDThe job has finished unexpectedly

“Get the configuration status”的 HTTP 响应状态代码

状态代码说明
200

OK

401

Unauthorized

“Get the configuration status”的示例代码

请求示例

get/setup/api/configcheck
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”的示例代码

请求示例

post/setup/api/configure
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”的示例代码

请求示例

get/setup/api/maintenance
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”的参数

正文参数
名称, 类型, 说明
maintenance string 必须

A JSON string with the attributes enabled and when.

The possible values for enabled are true and false. When it's false, the attribute when is ignored and the maintenance mode is turned off. when defines the time period when the maintenance was enabled.

The possible values for when are now or any date parseable by mojombo/chronic.

“Enable or disable maintenance mode”的 HTTP 响应状态代码

状态代码说明
200

OK

401

Unauthorized

“Enable or disable maintenance mode”的示例代码

请求示例

post/setup/api/maintenance
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”的示例代码

请求示例

get/setup/api/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 as curl to submit a parameter value as the contents of a text file. For more information, see the curl 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”的参数

正文参数
名称, 类型, 说明
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”的示例代码

请求示例

put/setup/api/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”的示例代码

请求示例

get/setup/api/settings/authorized-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”的参数

正文参数
名称, 类型, 说明
authorized_key string 必须

The public SSH key.

“Add an authorized SSH key”的 HTTP 响应状态代码

状态代码说明
201

Created

401

Unauthorized

“Add an authorized SSH key”的示例代码

请求示例

post/setup/api/settings/authorized-keys
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”的参数

正文参数
名称, 类型, 说明
authorized_key string 必须

The public SSH key.

“Remove an authorized SSH key”的 HTTP 响应状态代码

状态代码说明
200

OK

401

Unauthorized

“Remove an authorized SSH key”的示例代码

请求示例

delete/setup/api/settings/authorized-keys
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:

  1. If you're working directly with the API before accessing the web interface, you must pass in the password parameter to set your password.
  2. 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”的参数

正文参数
名称, 类型, 说明
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”的示例代码

请求示例

post/setup/api/start
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”的参数

正文参数
名称, 类型, 说明
license string

The content of your new .ghl license file.

“Upgrade a license”的 HTTP 响应状态代码

状态代码说明
202

Accepted

401

Unauthorized

“Upgrade a license”的示例代码

请求示例

post/setup/api/upgrade
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