Consola de administración

La API de la Consola de Administración te ayuda a administrar tu instalación de GitHub Enterprise Server.

Debes configurar el número de puerto explícitamente cuando haces llamadas de la API hacia la Consola de Administración. Si habilitaste TLS en tu 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 las redirecciones.

Podría que también necesites agregar el marcador -k cuando utilices curl, ya que GitHub Enterprise Server utiliza un certificado auto-firmado antes de que agregues tu propio certificado TLS.

Autenticación

Necesitas pasar tu Contraseña de la Consola de Administración como un token de autenticación para cada terminal de la API de ésta, con excepción de /setup/api/start.

Utiliza el parámetro de api_key para enviar este token con cada solicitud. Por ejemplo:

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

También puedes utilizar la autenticación HTTP estándar para enviar este token. Por ejemplo:

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

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

Código de estado	Descripción
`200`	OK

Ejemplos de código

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:

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`202`	Accepted

Ejemplos de código

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:

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`200`	OK

Ejemplos de código

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.

Parámetros

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de cuerpo
Nombre, Tipo, Descripción
`maintenance`stringRequerido 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

Código de estado	Descripción
`200`	OK

Ejemplos de código

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.

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`200`	OK

Ejemplos de código

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

Parámetros

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de cuerpo
Nombre, Tipo, Descripción
`settings`stringRequerido 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

Código de estado	Descripción
`204`	No Content

Ejemplos de código

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

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`200`	OK

Ejemplos de código

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.

Parámetros

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de cuerpo
Nombre, Tipo, Descripción
`authorized_key`stringRequerido The public SSH key.

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`201`	Created

Ejemplos de código

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.

Parámetros

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de cuerpo
Nombre, Tipo, Descripción
`authorized_key`stringRequerido The public SSH key.

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`200`	OK

Ejemplos de código

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:

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

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de cuerpo
Nombre, Tipo, Descripción
`license`stringRequerido 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

Código de estado	Descripción
`202`	Accepted

Ejemplos de código

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.

Parámetros

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de cuerpo
Nombre, Tipo, Descripción
`license`string The content of your new .ghl license file.

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`202`	Accepted

Ejemplos de código

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