콘솔 관리를 위한 REST API 엔드포인트
REST API를 사용하여 GitHub Enterprise Server 설치를 관리할 수 있습니다.
관리 콘솔 엔드포인트 정보
관리 콘솔 엔드포인트의 전체 기능이 GitHub Enterprise Server 버전 3.12의 GHES 관리 엔드포인트에 추가되었습니다. 기능 패리티가 달성되면 관리 콘솔 API 엔드포인트 가 버전 3.15에서 제거.
마이그레이션을 돕기 위해 아래 매핑 표에는 각 관리 콘솔 작업에 해당하는 GHES 관리 작업이 표시됩니다. 가능한 한 빨리 GHES API 관리 엔드포인트로 마이그레이션하세요.
목적 | 관리 콘솔 API 작업 | GHES API 작업 관리 |
---|---|---|
구성 상태 가져오기 | GET /setup/api/configcheck | GET /manage/v1/config/apply |
구성 프로세스 시작 | POST /setup/api/configure | POST /manage/v1/config/apply |
유지 관리 상태 가져오기 | GET /setup/api/maintenance | GET /manage/v1/maintenance |
유지 관리 모드 사용 또는 사용 안 함 | POST /setup/api/maintenance | POST /manage/v1/maintenance |
설정 가져오기 | GET /setup/api/settings | GET /manage/v1/config/settings |
설정 설정하기 | PUT /setup/api/settings | PUT /manage/v1/config/settings |
권한 있는 모든 SSH 키 가져오기 | GET /setup/api/settings/authorized-keys | GET /manage/v1/access/ssh |
권한 있는 SSH 키 추가 | POST /setup/api/settings/authorized-keys | POST /manage/v1/access/ssh |
권한 있는 SSH 키 제거 | DELETE /setup/api/settings/authorized-keys | DELETE /manage/v1/access/ssh |
GitHub 라이선스 만들기 | POST /setup/api/start | POST /manage/v1/config/init |
라이선스 업그레이드 | POST /setup/api/upgrade | PUT /manage/v1/config/license |
관리 콘솔 정보
관리 콘솔에 대한 API를 호출할 때 포트 번호를 명시적으로 설정해야 합니다. 엔터프라이즈에서 TLS를 사용하도록 설정하면 포트 번호가 8443
입니다. 그렇지 않으면 포트 번호는 8080
입니다.
포트 번호를 제공하고 싶지 않다면 리디렉션을 자동으로 따르도록 도구를 구성해야 합니다.
GitHub Enterprise Server은(는) 자체 TLS 인증서를 추가하기 전에 자체 서명된 인증서를 사용하므로 curl
을 사용할 때 -k
플래그를 추가해야 할 수도 있습니다.
루트 사이트 관리자로 인증
루트 사이트 관리자 암호를 "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"에 대한 코드 샘플
요청 예제
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"에 대한 코드 샘플
요청 예제
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"에 대한 코드 샘플
요청 예제
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 RequiredA JSON string with the attributes The possible values for The possible values for |
"Enable or disable maintenance mode"에 대한 HTTP 응답 상태 코드
상태 코드 | 설명 |
---|---|
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.
"Get settings"에 대한 HTTP 응답 상태 코드
상태 코드 | 설명 |
---|---|
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"에 대한 매개 변수
속성, 형식, 설명 |
---|
settings string RequiredA 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"에 대한 코드 샘플
요청 예제
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"에 대한 코드 샘플
요청 예제
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 RequiredThe public SSH key. |
"Add an authorized SSH key"에 대한 HTTP 응답 상태 코드
상태 코드 | 설명 |
---|---|
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"에 대한 매개 변수
속성, 형식, 설명 |
---|
authorized_key string RequiredThe public SSH key. |
"Remove an authorized SSH key"에 대한 HTTP 응답 상태 코드
상태 코드 | 설명 |
---|---|
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"에 대한 매개 변수
속성, 형식, 설명 |
---|
license string RequiredThe 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"에 대한 코드 샘플
요청 예제
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"에 대한 코드 샘플
요청 예제
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