Skip to main content
Ahora la API de REST tiene control de versiones. Para obtener más información, consulta "Acerca del control de versiones de la API".

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.

FinOperación de API de la Consola de administraciónOperación de API de Administrar GHES
Obtención del estado de configuraciónGET /setup/api/configcheckGET /manage/v1/config/apply
Inicio del proceso de configuraciónPOST /setup/api/configurePOST /manage/v1/config/apply
Obtención del estado de mantenimientoGET /setup/api/maintenanceGET /manage/v1/maintenance
Habilitar o inhabilitar el modo de mantenimientoPOST /setup/api/maintenancePOST /manage/v1/maintenance
Obtención de la configuraciónGET /setup/api/settingsGET /manage/v1/config/settings
Definición de la configuraciónPUT /setup/api/settingsPUT /manage/v1/config/settings
Obtención de todas las claves SSH autorizadasGET /setup/api/settings/authorized-keysGET /manage/v1/access/ssh
Adición de una clave SSH autorizadaPOST /setup/api/settings/authorized-keysPOST /manage/v1/access/ssh
Eliminación de una clave SSH autorizadaDELETE /setup/api/settings/authorized-keysDELETE /manage/v1/access/ssh
Creación de una licencia de GitHubPOST /setup/api/startPOST /manage/v1/config/init
Actualización de una licenciaPOST /setup/api/upgradePUT /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:

StatusDescription
PENDINGThe job has not started yet
CONFIGURINGThe job is running
DONEThe job has finished correctly
FAILEDThe job has finished unexpectedly

Códigos de estado de respuesta HTTP para "Get the configuration status"

status codeDescripción
200

OK

401

Unauthorized

Ejemplos de código para "Get the configuration status"

Ejemplo de solicitud

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:

Códigos de estado de respuesta HTTP para "Start a configuration process"

status codeDescripción
202

Accepted

401

Unauthorized

Ejemplos de código para "Start a configuration process"

Ejemplo de solicitud

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:

Códigos de estado de respuesta HTTP para "Get the maintenance status"

status codeDescripción
200

OK

401

Unauthorized

Ejemplos de código para "Get the maintenance status"

Ejemplo de solicitud

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.

Parámetros para "Enable or disable maintenance mode"

Parámetros del cuerpo
Nombre, Tipo, Descripción
maintenance string Requerido

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.

Códigos de estado de respuesta HTTP para "Enable or disable maintenance mode"

status codeDescripción
200

OK

401

Unauthorized

Ejemplos de código para "Enable or disable maintenance mode"

Ejemplo de solicitud

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.

Códigos de estado de respuesta HTTP para "Get settings"

status codeDescripción
200

OK

401

Unauthorized

Ejemplos de código para "Get settings"

Ejemplo de solicitud

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

Parámetros para "Set settings"

Parámetros del cuerpo
Nombre, Tipo, Descripción
settings string Requerido

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.

Códigos de estado de respuesta HTTP para "Set settings"

status codeDescripción
204

No Content

401

Unauthorized

Ejemplos de código para "Set settings"

Ejemplo de solicitud

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

Ejemplos de código para "Get all authorized SSH keys"

Ejemplo de solicitud

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.

Parámetros para "Add an authorized SSH key"

Parámetros del cuerpo
Nombre, Tipo, Descripción
authorized_key string Requerido

The public SSH key.

Códigos de estado de respuesta HTTP para "Add an authorized SSH key"

status codeDescripción
201

Created

401

Unauthorized

Ejemplos de código para "Add an authorized SSH key"

Ejemplo de solicitud

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.

Parámetros para "Remove an authorized SSH key"

Parámetros del cuerpo
Nombre, Tipo, Descripción
authorized_key string Requerido

The public SSH key.

Códigos de estado de respuesta HTTP para "Remove an authorized SSH key"

status codeDescripción
200

OK

401

Unauthorized

Ejemplos de código para "Remove an authorized SSH key"

Ejemplo de solicitud

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:

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

Parámetros del cuerpo
Nombre, Tipo, Descripción
license string Requerido

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.

Códigos de estado de respuesta HTTP para "Create a GitHub license"

status codeDescripción
202

Accepted

401

Unauthorized

Ejemplos de código para "Create a GitHub license"

Ejemplo de solicitud

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.

Parámetros para "Upgrade a license"

Parámetros del cuerpo
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 codeDescripción
202

Accepted

401

Unauthorized

Ejemplos de código para "Upgrade a license"

Ejemplo de solicitud

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