Skip to main content

Esta versão do GitHub Enterprise Server foi descontinuada em 2024-03-26. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, segurança aprimorada e novos recursos, atualize para a última versão do GitHub Enterprise Server. Para obter ajuda com a atualização, entre em contato com o suporte do GitHub Enterprise.

Depois que um administrador do site fizer upgrade da sua instância do Enterprise Server para Enterprise Server 3.9 ou posterior, o controle de versão da API REST será feito. Para saber como encontrar a versão da sua instância, confira "Sobre as versões do GitHub Docs". Para obter mais informações, confira "Sobre o controle de versão da API".

Pontos de extremidade da API REST para o console de gerenciamento

Use a API REST para gerenciar sua instalação do GitHub Enterprise Server.

Sobre o Console de Gerenciamento

É necessário definir explicitamente o número da porta ao fazer chamadas de API para o console de gerenciamento. Se o TLS estiver habilitado em sua empresa, o número da porta será 8443. Caso contrário, o número da porta será 8080.

Se não for possível fornecer um número de porta, será preciso configurar sua ferramenta para seguir automaticamente os redirecionamentos.

Talvez você também precise adicionar o -k sinalizador ao usar curl, já que GitHub Enterprise Server usa um certificado autoassinado antes de adicionar seu próprio certificado TLS.

Autenticação como o administrador do site raiz

Você precisa passar a sua senha do administrador do site raiz como um token de autenticação para todos os pontos de extremidade nesta categoria, exceto "Criar uma licença do GitHub".

Use o parâmetro api_key para enviar este token com cada solicitação. Por exemplo:

curl -L 'https://HOSTNAME:ADMIN-PORT/setup/api?api_key=YOUR_PASSWORD'

Você também pode usar a autenticação HTTP padrão para enviar esse token. Por exemplo:

curl -L -u "api_key:YOUR_PASSWORD" 'https://HOSTNAME:ADMIN-PORT/setup/api'

Autenticação como um usuário Console de Gerenciamento

As contas de usuário do Console de Gerenciamento também podem se autenticar para acessar esse ponto de extremidade.

Para autenticar com a senha de uma conta de usuário do Console de Gerenciamento, use a autenticação HTTP padrão. No exemplo a seguir, substitua YOUR_USER_NAME e YOUR_PASSWORD pelo nome de usuário e senha da conta.

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 status de resposta HTTP para "Get the configuration status"

Código de statusDescrição
200

OK

401

Unauthorized

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

Exemplo de solicitação

get/setup/api/configcheck
curl -L \ -H "Accept: application/vnd.github+json" \ -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 status de resposta HTTP para "Start a configuration process"

Código de statusDescrição
202

Accepted

401

Unauthorized

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

Exemplo de solicitação

post/setup/api/configure
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -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 status de resposta HTTP para "Get the maintenance status"

Código de statusDescrição
200

OK

401

Unauthorized

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

Exemplo de solicitação

get/setup/api/maintenance
curl -L \ -H "Accept: application/vnd.github+json" \ -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"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros do corpo
Nome, Tipo, Descrição
maintenance string Obrigatório

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 status de resposta HTTP para "Enable or disable maintenance mode"

Código de statusDescrição
200

OK

401

Unauthorized

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

Exemplo de solicitação

post/setup/api/maintenance
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -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 status de resposta HTTP para "Get settings"

Código de statusDescrição
200

OK

401

Unauthorized

Exemplos de código para "Get settings"

Exemplo de solicitação

get/setup/api/settings
curl -L \ -H "Accept: application/vnd.github+json" \ -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"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros do corpo
Nome, Tipo, Descrição
settings string Obrigatório

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 status de resposta HTTP para "Set settings"

Código de statusDescrição
204

No Content

401

Unauthorized

Exemplos de código para "Set settings"

Exemplo de solicitação

put/setup/api/settings
curl -L \ -X PUT \ -H "Accept: application/vnd.github+json" \ -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 status de resposta HTTP para "Get all authorized SSH keys"

Código de statusDescrição
200

OK

401

Unauthorized

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

Exemplo de solicitação

get/setup/api/settings/authorized-keys
curl -L \ -H "Accept: application/vnd.github+json" \ -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"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros do corpo
Nome, Tipo, Descrição
authorized_key string Obrigatório

The public SSH key.

Códigos de status de resposta HTTP para "Add an authorized SSH key"

Código de statusDescrição
201

Created

401

Unauthorized

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

Exemplo de solicitação

post/setup/api/settings/authorized-keys
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -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"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros do corpo
Nome, Tipo, Descrição
authorized_key string Obrigatório

The public SSH key.

Códigos de status de resposta HTTP para "Remove an authorized SSH key"

Código de statusDescrição
200

OK

401

Unauthorized

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

Exemplo de solicitação

delete/setup/api/settings/authorized-keys
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -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"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros do corpo
Nome, Tipo, Descrição
license string Obrigatório

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 status de resposta HTTP para "Create a GitHub license"

Código de statusDescrição
202

Accepted

401

Unauthorized

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

Exemplo de solicitação

post/setup/api/start
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -u "api_key:your-password" \ 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"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros do corpo
Nome, Tipo, Descrição
license string

The content of your new .ghl license file.

Códigos de status de resposta HTTP para "Upgrade a license"

Código de statusDescrição
202

Accepted

401

Unauthorized

Exemplos de código para "Upgrade a license"

Exemplo de solicitação

post/setup/api/upgrade
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -u "api_key:your-password" \ http(s)://HOSTNAME/setup/api/upgrade \ --form 'license=@enterprise.ghl'

Response

Status: 202