Skip to main content

此版本的 GitHub Enterprise 已停止服务 2022-06-03. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 GitHub Enterprise 的最新版本。 如需升级方面的帮助,请联系 GitHub Enterprise 支持

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.

管理控制台

管理控制台 API 可帮助您管理 GitHub Enterprise Server 安装设施。

在对管理控制台进行 API 调用时,必须明确设置端口号。 如果在企业上启用了 TLS,则端口号为 8443;否则,端口号为 8080

如果您不想提供端口号,则需要将工具配置为自动遵循重定向。

使用 curl 时,您可能还需要添�  -k � �志,� 为 GitHub Enterprise Server 在您添� 自己的 TLS 证书之前会使用自签名证书。

身份验证

您需要将管理控制台密� �作为身份验证令牌� 递给除 /setup/api/start 之外的每个管理控制台 API 端点。

使用 api_key 参数在每个请求中发送此令牌。 例如:

$ curl -L 'https://hostname:admin_port/setup/api?api_key=your-amazing-password'

还可以使用� �准 HTTP 身份验证发送此令牌。 例如:

$ curl -L -u "api_key:your-amazing-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

HTTP 响应状态代� �

状态代� �描述
200

OK

代� �示例

get/setup/api/configcheck
curl \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ 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 响应状态代� �

状态代� �描述
202

Accepted

代� �示例

post/setup/api/configure
curl \ -X POST \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ http(s)://HOSTNAME/setup/api/configure

Response

Status: 202

Get the maintenance status

Check your installation's maintenance status:

HTTP 响应状态代� �

状态代� �描述
200

OK

代� �示例

get/setup/api/maintenance
curl \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ 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.

参数

� �头
名称, 类型, 描述
acceptstring

Setting to application/vnd.github.v3+json is recommended.

正文参数
名称, 类型, 描述
maintenancestring必选

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.

HTTP 响应状态代� �

状态代� �描述
200

OK

代� �示例

post/setup/api/maintenance
curl \ -X POST \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ 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 响应状态代� �

状态代� �描述
200

OK

代� �示例

get/setup/api/settings
curl \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ 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."

参数

� �头
名称, 类型, 描述
acceptstring

Setting to application/vnd.github.v3+json is recommended.

正文参数
名称, 类型, 描述
settingsstring必选

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 响应状态代� �

状态代� �描述
204

No Content

代� �示例

put/setup/api/settings
curl \ -X PUT \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ http(s)://HOSTNAME/setup/api/settings \ --data-urlencode settings={ "enterprise": { "public_pages": true }}

Response

Status: 204

Get all authorized SSH keys

HTTP 响应状态代� �

状态代� �描述
200

OK

代� �示例

get/setup/api/settings/authorized-keys
curl \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ 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.

参数

� �头
名称, 类型, 描述
acceptstring

Setting to application/vnd.github.v3+json is recommended.

正文参数
名称, 类型, 描述
authorized_keystring必选

The public SSH key.

HTTP 响应状态代� �

状态代� �描述
201

Created

代� �示例

post/setup/api/settings/authorized-keys
curl \ -X POST \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ 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.

参数

� �头
名称, 类型, 描述
acceptstring

Setting to application/vnd.github.v3+json is recommended.

正文参数
名称, 类型, 描述
authorized_keystring必选

The public SSH key.

HTTP 响应状态代� �

状态代� �描述
200

OK

代� �示例

delete/setup/api/settings/authorized-keys
curl \ -X DELETE \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ 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 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.

参数

� �头
名称, 类型, 描述
acceptstring

Setting to application/vnd.github.v3+json is recommended.

正文参数
名称, 类型, 描述
licensestring必选

The content of your .ghl license file.

passwordstring

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.

settingsstring

An optional JSON string containing the installation settings. For a list of the available settings, see the Get settings endpoint.

HTTP 响应状态代� �

状态代� �描述
202

Accepted

代� �示例

post/setup/api/start
curl \ -X POST \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ http(s)://HOSTNAME/setup/api/start

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

参数

� �头
名称, 类型, 描述
acceptstring

Setting to application/vnd.github.v3+json is recommended.

正文参数
名称, 类型, 描述
licensestring

The content of your new .ghl license file.

HTTP 响应状态代� �

状态代� �描述
202

Accepted

代� �示例

post/setup/api/upgrade
curl \ -X POST \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ http(s)://HOSTNAME/setup/api/upgrade

Response

Status: 202