Puntos de conexión de API de REST para la consola de administración
Usa la API de REST para administrar la instalación de GitHub Enterprise Server.
Acerca de los puntos de conexión de la consola de administración
La funcionalidad completa de los puntos de conexión de la Consola de administración se agregó a los puntos de conexión Administrar GHES en GitHub Enterprise Server versión 3.12. Tras lograr la paridad de características, los puntos de conexión de API de la Consola de administración serán eliminados en la versión 3.15.
Para ayudarte a hacer la migración, la tabla de asignaciones siguiente muestra la operación Administrar GHES equivalente para cada operación de la Consola de administración. Migra a los puntos de conexión de API de Administrar GHES lo antes posible.
Fin | Operación de API de la Consola de administración | Operación de API de Administrar GHES |
---|---|---|
Obtención del estado de configuración | GET /setup/api/configcheck | GET /manage/v1/config/apply |
Inicio del proceso de configuración | POST /setup/api/configure | POST /manage/v1/config/apply |
Obtención del estado de mantenimiento | GET /setup/api/maintenance | GET /manage/v1/maintenance |
Habilitar o inhabilitar el modo de mantenimiento | POST /setup/api/maintenance | POST /manage/v1/maintenance |
Obtención de la configuración | GET /setup/api/settings | GET /manage/v1/config/settings |
Definición de la configuración | PUT /setup/api/settings | PUT /manage/v1/config/settings |
Obtención de todas las claves SSH autorizadas | GET /setup/api/settings/authorized-keys | GET /manage/v1/access/ssh |
Adición de una clave SSH autorizada | POST /setup/api/settings/authorized-keys | POST /manage/v1/access/ssh |
Eliminación de una clave SSH autorizada | DELETE /setup/api/settings/authorized-keys | DELETE /manage/v1/access/ssh |
Creación de una licencia de GitHub | POST /setup/api/start | POST /manage/v1/config/init |
Actualización de una licencia | POST /setup/api/upgrade | PUT /manage/v1/config/license |
Acerca de Consola de administración
Debes configurar el número de puerto explícitamente cuando haces llamadas API a la consola de administración. Si TLS está habilitado en la empresa, el número de puerto es 8443
. De lo contrario, el número de puerto es 8080
.
Si no quieres proporcionar un número de puerto, necesitarás configurar tu herramienta para seguir automáticamente los redireccionamientos.
Es posible que también tenga que agregar la marca -k
al usar curl
, ya que GitHub Enterprise Server usa un certificado autofirmado antes de que agregue un certificado TLS propio .
Autenticación como administrador del sitio raíz
Debes pasar tu contraseña de administrador del sitio raíz como token de autenticación a todos los puntos de conexión de esta categoría, excepto "Crear una licencia de GitHub".
Usa el parámetro api_key
para enviar este token con cada solicitud. Por ejemplo:
curl -L 'https://HOSTNAME:ADMIN-PORT/setup/api?api_key=YOUR_PASSWORD'
También puede utilizar la autenticación HTTP estándar para enviar este token. Por ejemplo:
curl -L -u "api_key:YOUR_PASSWORD" 'https://HOSTNAME:ADMIN-PORT/setup/api'
Autenticación como usuario de la Consola de administración
Las cuentas de usuario de la consola de administración también se pueden autenticar para acceder a este punto de conexión.
Para autenticarse con la contraseña de una cuenta de usuario de Consola de administración, usa la autenticación HTTP estándar. En el ejemplo siguiente, reemplaza YOUR_USER_NAME y YOUR_PASSWORD por el nombre de usuario y la contraseña de la cuenta.
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 |
Códigos de estado de respuesta HTTP para "Get the configuration status"
status code | Descripción |
---|---|
200 | OK |
401 | Unauthorized |
Ejemplos de código para "Get the configuration status"
Ejemplo de solicitud
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:
Códigos de estado de respuesta HTTP para "Start a configuration process"
status code | Descripción |
---|---|
202 | Accepted |
401 | Unauthorized |
Ejemplos de código para "Start a configuration process"
Ejemplo de solicitud
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:
Códigos de estado de respuesta HTTP para "Get the maintenance status"
status code | Descripción |
---|---|
200 | OK |
401 | Unauthorized |
Ejemplos de código para "Get the maintenance status"
Ejemplo de solicitud
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.
Parámetros para "Enable or disable maintenance mode"
Nombre, Tipo, Descripción |
---|
maintenance string RequeridoA JSON string with the attributes The possible values for The possible values for |
Códigos de estado de respuesta HTTP para "Enable or disable maintenance mode"
status code | Descripción |
---|---|
200 | OK |
401 | Unauthorized |
Ejemplos de código para "Enable or disable maintenance mode"
Ejemplo de solicitud
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.
Códigos de estado de respuesta HTTP para "Get settings"
status code | Descripción |
---|---|
200 | OK |
401 | Unauthorized |
Ejemplos de código para "Get settings"
Ejemplo de solicitud
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."
Parámetros para "Set settings"
Nombre, Tipo, Descripción |
---|
settings string RequeridoA 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. |
Códigos de estado de respuesta HTTP para "Set settings"
status code | Descripción |
---|---|
204 | No Content |
401 | Unauthorized |
Ejemplos de código para "Set settings"
Ejemplo de solicitud
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
Códigos de estado de respuesta HTTP para "Get all authorized SSH keys"
status code | Descripción |
---|---|
200 | OK |
401 | Unauthorized |
Ejemplos de código para "Get all authorized SSH keys"
Ejemplo de solicitud
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.
Parámetros para "Add an authorized SSH key"
Nombre, Tipo, Descripción |
---|
authorized_key string RequeridoThe public SSH key. |
Códigos de estado de respuesta HTTP para "Add an authorized SSH key"
status code | Descripción |
---|---|
201 | Created |
401 | Unauthorized |
Ejemplos de código para "Add an authorized SSH key"
Ejemplo de solicitud
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.
Parámetros para "Remove an authorized SSH key"
Nombre, Tipo, Descripción |
---|
authorized_key string RequeridoThe public SSH key. |
Códigos de estado de respuesta HTTP para "Remove an authorized SSH key"
status code | Descripción |
---|---|
200 | OK |
401 | Unauthorized |
Ejemplos de código para "Remove an authorized SSH key"
Ejemplo de solicitud
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.
Parámetros para "Create a GitHub license"
Nombre, Tipo, Descripción |
---|
license string RequeridoThe 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. |
Códigos de estado de respuesta HTTP para "Create a GitHub license"
status code | Descripción |
---|---|
202 | Accepted |
401 | Unauthorized |
Ejemplos de código para "Create a GitHub license"
Ejemplo de solicitud
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.
Parámetros para "Upgrade a license"
Nombre, Tipo, Descripción |
---|
license string The content of your new .ghl license file. |
Códigos de estado de respuesta HTTP para "Upgrade a license"
status code | Descripción |
---|---|
202 | Accepted |
401 | Unauthorized |
Ejemplos de código para "Upgrade a license"
Ejemplo de solicitud
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