REST API теперь версия. Дополнительные сведения см. в разделе "О управлении версиями API".

Конечные точки REST API для консоли управления

Используйте REST API для управления установкой GitHub Enterprise Server.

Сведения о конечных точках консоли управления

Полная функциональность конечных точек консоли управления была добавлена в конечные точки управления GHES в GitHub Enterprise Server версии 3.12. При достижении четности функций конечные точки API консоли управления были удалены в версии 3.15.

Чтобы упростить миграцию, в таблице сопоставления ниже показана эквивалентная операция управления GHES для каждой операции консоли управления. Перейдите к конечным точкам API управления GHES как можно скорее.

Характер использования	Операция API консоли управления	Управление операцией API GHES
Получение состояния конфигурации	`GET /setup/api/configcheck`	`GET /manage/v1/config/apply`
Запуск процесса настройки	`POST /setup/api/configure`	`POST /manage/v1/config/apply`
Получение состояния обслуживания	`GET /setup/api/maintenance`	`GET /manage/v1/maintenance`
Включение или отключение режима обслуживания	`POST /setup/api/maintenance`	`POST /manage/v1/maintenance`
Получение параметров	`GET /setup/api/settings`	`GET /manage/v1/config/settings`
Настройка параметров	`PUT /setup/api/settings`	`PUT /manage/v1/config/settings`
Получение всех авторизованных ключей SSH	`GET /setup/api/settings/authorized-keys`	`GET /manage/v1/access/ssh`
Добавление авторизованного ключа SSH	`POST /setup/api/settings/authorized-keys`	`POST /manage/v1/access/ssh`
Удаление авторизованного ключа SSH	`DELETE /setup/api/settings/authorized-keys`	`DELETE /manage/v1/access/ssh`
Создание лицензии GitHub	`POST /setup/api/start`	`POST /manage/v1/config/init`
Обновление лицензии	`POST /setup/api/upgrade`	`PUT /manage/v1/config/license`

Сведения о Консоль управления

При вызове API в консоли управления необходимо явно задать номер порта. Если протокол TLS включен в вашей организации, номер порта равен 8443. В противном случае номер порта равен 8080.

Если вы не можете указать номер порта, необходимо настроить средство для автоматического выполнения перенаправлений.

При использовании curlтакже может потребоваться добавить -k флаг, так как GitHub использует самозаверяющий сертификат перед добавлением собственного сертификата TLS.

Проверка подлинности от имени администратора корневого сайта

Необходимо передать пароль администратора корневого сайта в качестве маркера проверки подлинности в каждую конечную точку этой категории, за исключением лицензии GitHub .

Используйте параметр api_key для отправки этого маркера с каждым запросом. Например:

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

Для отправки этого маркера можно также использовать стандартную проверку подлинности HTTP. Например:

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

Проверка подлинности в качестве пользователя Консоль управления

Учетные записи пользователей консоли управления также могут проходить проверку подлинности для доступа к этой конечной точке.

Для проверки подлинности с помощью пароля для учетной записи пользователя Консоль управления используйте стандартную проверку подлинности HTTP. В следующем примере замените YOUR_USER_NAME и YOUR_PASSWORD именем пользователя и паролем учетной записи.

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

Коды состояния http-ответа для "Get the configuration status"

Код состояния	Описание
`200`	OK
`401`	Unauthorized

Примеры кода для "Get the configuration status"

Пример запроса

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:

Коды состояния http-ответа для "Start a configuration process"

Код состояния	Описание
`202`	Accepted
`401`	Unauthorized

Примеры кода для "Start a configuration process"

Пример запроса

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:

Коды состояния http-ответа для "Get the maintenance status"

Код состояния	Описание
`200`	OK
`401`	Unauthorized

Примеры кода для "Get the maintenance status"

Пример запроса

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.

Параметры для "Enable or disable maintenance mode"

Параметры запроса
Имя., Тип, Description
`maintenance` string Обязательное поле 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-ответа для "Enable or disable maintenance mode"

Код состояния	Описание
`200`	OK
`401`	Unauthorized

Примеры кода для "Enable or disable maintenance mode"

Пример запроса

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.

Коды состояния http-ответа для "Get settings"

Код состояния	Описание
`200`	OK
`401`	Unauthorized

Примеры кода для "Get settings"

Пример запроса

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

Параметры для "Set settings"

Параметры запроса
Имя., Тип, Description
`settings` string Обязательное поле 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-ответа для "Set settings"

Код состояния	Описание
`204`	No Content
`401`	Unauthorized

Примеры кода для "Set settings"

Пример запроса

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

Коды состояния http-ответа для "Get all authorized SSH keys"

Код состояния	Описание
`200`	OK
`401`	Unauthorized

Примеры кода для "Get all authorized SSH keys"

Пример запроса

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.

Параметры для "Add an authorized SSH key"

Параметры запроса
Имя., Тип, Description
`authorized_key` string Обязательное поле The public SSH key.

Коды состояния http-ответа для "Add an authorized SSH key"

Код состояния	Описание
`201`	Created
`401`	Unauthorized

Примеры кода для "Add an authorized SSH key"

Пример запроса

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

Параметры для "Remove an authorized SSH key"

Параметры запроса
Имя., Тип, Description
`authorized_key` string Обязательное поле The public SSH key.

Коды состояния http-ответа для "Remove an authorized SSH key"

Код состояния	Описание
`200`	OK
`401`	Unauthorized

Примеры кода для "Remove an authorized SSH key"

Пример запроса

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:

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.

Параметры для "Create a GitHub license"

Параметры запроса
Имя., Тип, Description
`license` string Обязательное поле 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-ответа для "Create a GitHub license"

Код состояния	Описание
`202`	Accepted
`401`	Unauthorized

Примеры кода для "Create a GitHub license"

Пример запроса

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

Параметры для "Upgrade a license"

Параметры запроса
Имя., Тип, Description
`license` string The content of your new .ghl license file.

Коды состояния http-ответа для "Upgrade a license"

Код состояния	Описание
`202`	Accepted
`401`	Unauthorized

Примеры кода для "Upgrade a license"

Пример запроса

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