Skip to main content
Die REST-API verfügt jetzt über eine Versionskontrolle. Weitere Informationen findest du unter Informationen zur API-Versionsverwaltung.

Verwaltungskonsole

Verwende die REST-API zum Verwalten deiner GitHub Enterprise Server-Installation.

Informationen zur Verwaltungskonsole

Du musst die Portnummer explizit festlegen, wenn du API-Aufrufe an die Verwaltungskonsole sendest. Wenn TLS in deinem Unternehmen aktiviert ist, lautet die Portnummer 8443. Andernfalls ist die Portnummer 8080.

Wenn du keine Portnummer angeben kannst, musst du dein Tool so konfigurieren, dass bei Weiterleitungen eine automatische Umleitung erfolgt.

Bevor du ein eigenes TLS-Zertifikat hinzufügst, musst du bei Verwendung von curl möglicherweise auch das Flag -k hinzufügen, da GitHub Enterprise Server ein selbstsigniertes Zertifikat verwendet.

Authentifizierung Websiteadministrator*in mit Root-Berechtigungen

Sie müssen Ihr Kennwort für Websiteadministratoren mit Root-Berechtigungen als Authentifizierungstoken an jeden Endpunkt in dieser Kategorie mit Ausnahme von „GitHub-Lizenz erstellen“ übergeben.

Verwende den Parameter api_key, um dieses Token mit jeder Anforderung zu senden. Beispiel:

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

Du kannst auch die HTTP-Standardauthentifizierung verwenden, um dieses Token zu senden. Beispiel:

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

Authentifizierung als Verwaltungskonsole-Benutzer*in

Benutzerkonten der Verwaltungskonsole können sich auch für den Zugriff auf diesen Endpunkt authentifizieren.

Verwende HTTP-Standardauthentifizierung, um sich mit dem Kennwort für ein Benutzerkonto der Verwaltungskonsole zu authentifizieren. Ersetze im folgenden Beispiel YOUR_USER_NAME und YOUR_PASSWORD durch den Benutzernamen und das Kennwort des Kontos.

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

HTTP-Antwortstatuscodes für „Get the configuration status“

StatuscodeBESCHREIBUNG
200

OK

401

Unauthorized

Codebeispiele für „Get the configuration status“

Beispiel für eine Anfrage

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:

HTTP-Antwortstatuscodes für „Start a configuration process“

StatuscodeBESCHREIBUNG
202

Accepted

401

Unauthorized

Codebeispiele für „Start a configuration process“

Beispiel für eine Anfrage

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:

HTTP-Antwortstatuscodes für „Get the maintenance status“

StatuscodeBESCHREIBUNG
200

OK

401

Unauthorized

Codebeispiele für „Get the maintenance status“

Beispiel für eine Anfrage

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.

Parameter für „Enable or disable maintenance mode“

Header
Name, type, BESCHREIBUNG
accept string

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

Textparameter
Name, type, BESCHREIBUNG
maintenance string Erforderlich

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.

HTTP-Antwortstatuscodes für „Enable or disable maintenance mode“

StatuscodeBESCHREIBUNG
200

OK

401

Unauthorized

Codebeispiele für „Enable or disable maintenance mode“

Beispiel für eine Anfrage

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.

HTTP-Antwortstatuscodes für „Get settings“

StatuscodeBESCHREIBUNG
200

OK

401

Unauthorized

Codebeispiele für „Get settings“

Beispiel für eine Anfrage

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

Parameter für „Set settings“

Header
Name, type, BESCHREIBUNG
accept string

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

Textparameter
Name, type, BESCHREIBUNG
settings string Erforderlich

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.

HTTP-Antwortstatuscodes für „Set settings“

StatuscodeBESCHREIBUNG
204

No Content

401

Unauthorized

Codebeispiele für „Set settings“

Beispiel für eine Anfrage

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

HTTP-Antwortstatuscodes für „Get all authorized SSH keys“

StatuscodeBESCHREIBUNG
200

OK

401

Unauthorized

Codebeispiele für „Get all authorized SSH keys“

Beispiel für eine Anfrage

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.

Parameter für „Add an authorized SSH key“

Header
Name, type, BESCHREIBUNG
accept string

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

Textparameter
Name, type, BESCHREIBUNG
authorized_key string Erforderlich

The public SSH key.

HTTP-Antwortstatuscodes für „Add an authorized SSH key“

StatuscodeBESCHREIBUNG
201

Created

401

Unauthorized

Codebeispiele für „Add an authorized SSH key“

Beispiel für eine Anfrage

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.

Parameter für „Remove an authorized SSH key“

Header
Name, type, BESCHREIBUNG
accept string

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

Textparameter
Name, type, BESCHREIBUNG
authorized_key string Erforderlich

The public SSH key.

HTTP-Antwortstatuscodes für „Remove an authorized SSH key“

StatuscodeBESCHREIBUNG
200

OK

401

Unauthorized

Codebeispiele für „Remove an authorized SSH key“

Beispiel für eine Anfrage

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.

Parameter für „Create a GitHub license“

Header
Name, type, BESCHREIBUNG
accept string

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

Textparameter
Name, type, BESCHREIBUNG
license string Erforderlich

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.

HTTP-Antwortstatuscodes für „Create a GitHub license“

StatuscodeBESCHREIBUNG
202

Accepted

401

Unauthorized

Codebeispiele für „Create a GitHub license“

Beispiel für eine Anfrage

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.

Parameter für „Upgrade a license“

Header
Name, type, BESCHREIBUNG
accept string

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

Textparameter
Name, type, BESCHREIBUNG
license string

The content of your new .ghl license file.

HTTP-Antwortstatuscodes für „Upgrade a license“

StatuscodeBESCHREIBUNG
202

Accepted

401

Unauthorized

Codebeispiele für „Upgrade a license“

Beispiel für eine Anfrage

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