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

关于管理控制台终结点

管理控制台终结点的完整功能已添加到 GitHub Enterprise Server 版本 3.12 中的管理 GHES 终结点。实现功能奇偶一致性后，将版本 3.15 中弃用管理控制台 API 终结点。

关于管理控制台

在对管理控制台进行 API 调用时，应显式设置端口号。如果企业启用了 TLS，则端口号为 8443。否则，端口号为 8080。

如果无法提供端口号，则需要将工具配置为自动遵循重定向。

使用 curl 时可能还需要添加 -k 标志，因为在添加自己的 TLS 证书之前，GitHub Enterprise Server 使用自签名证书。

以根站点管理员身份进行身份验证

你需要将根站点管理员密码作为身份验证令牌传递给此类别中的每个端点，“创建 GitHub 许可证”除外。

使用 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'

以管理控制台用户身份进行身份验证

管理控制台用户帐户还可以通过身份验证来访问此终结点。

若要使用管理控制台用户帐户密码进行身份验证，请使用标准 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”的示例代码

请求示例

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”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`401`	Unauthorized

“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:

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”的参数

正文参数
名称, 类型, 说明
`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