We've recently moved some of the REST API documentation. If you can't find what you're looking for, you might try the Actions REST API page.
管理控制台
使用 REST API 管理 GitHub Enterprise Server 安装。
关于管理控制台
在对管理控制台进行 API 调用时,应显式设置端口号。 如果企业启用了 TLS,则端口号为 8443
。 否则,端口号为 8080
。
如果无法提供端口号,则需要将工具配置为自动遵循重定向。
使用 curl
时可能还需要添加 -k
标志,因为在添加自己的 TLS 证书之前,GitHub Enterprise Server 使用自签名证书。
身份验证
需要将管理控制台密码作为身份验证令牌传递给此类别中除“创建许可证”之外的每个终结点。
使用 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'
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 response status codes
Status code | 说明 |
---|---|
200 | OK |
Code samples
curl \
-H "Accept: application/vnd.github+json" \
-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 response status codes
Status code | 说明 |
---|---|
202 | Accepted |
Code samples
curl \
-X POST \
-H "Accept: application/vnd.github+json" \
-u "api_key:your-password" \
http(s)://HOSTNAME/setup/api/configure
Response
Status: 202
Get the maintenance status
Code samples
curl \
-H "Accept: application/vnd.github+json" \
-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.
Parameters
Headers |
---|
名称, Type, 说明 |
accept stringSetting to |
Body parameters |
名称, Type, 说明 |
maintenance stringRequiredA JSON string with the attributes The possible values for The possible values for |
HTTP response status codes
Status code | 说明 |
---|---|
200 | OK |
Code samples
curl \
-X POST \
-H "Accept: application/vnd.github+json" \
-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 response status codes
Status code | 说明 |
---|---|
200 | OK |
Code samples
curl \
-H "Accept: application/vnd.github+json" \
-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."
Parameters
Headers |
---|
名称, Type, 说明 |
accept stringSetting to |
Body parameters |
名称, Type, 说明 |
settings stringRequiredA 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 response status codes
Status code | 说明 |
---|---|
204 | No Content |
Code samples
curl \
-X PUT \
-H "Accept: application/vnd.github+json" \
-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 response status codes
Status code | 说明 |
---|---|
200 | OK |
Code samples
curl \
-H "Accept: application/vnd.github+json" \
-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.
Parameters
Headers |
---|
名称, Type, 说明 |
accept stringSetting to |
Body parameters |
名称, Type, 说明 |
authorized_key stringRequiredThe public SSH key. |
HTTP response status codes
Status code | 说明 |
---|---|
201 | Created |
Code samples
curl \
-X POST \
-H "Accept: application/vnd.github+json" \
-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.
Parameters
Headers |
---|
名称, Type, 说明 |
accept stringSetting to |
Body parameters |
名称, Type, 说明 |
authorized_key stringRequiredThe public SSH key. |
HTTP response status codes
Status code | 说明 |
---|---|
200 | OK |
Code samples
curl \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-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.
Parameters
Headers |
---|
名称, Type, 说明 |
accept stringSetting to |
Body parameters |
名称, Type, 说明 |
license stringRequiredThe content of your .ghl license file. |
password stringYou 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 stringAn optional JSON string containing the installation settings. For a list of the available settings, see the Get settings endpoint. |
HTTP response status codes
Status code | 说明 |
---|---|
202 | Accepted |
Code samples
curl \
-X POST \
-H "Accept: application/vnd.github+json" \
-u "api_key:your-password" \
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.
Parameters
Headers |
---|
名称, Type, 说明 |
accept stringSetting to |
Body parameters |
名称, Type, 说明 |
license stringThe content of your new .ghl license file. |
HTTP response status codes
Status code | 说明 |
---|---|
202 | Accepted |
Code samples
curl \
-X POST \
-H "Accept: application/vnd.github+json" \
-u "api_key:your-password" \
http(s)://HOSTNAME/setup/api/upgrade \
--form "license=@enterprise.ghl"
Response
Status: 202