Points de terminaison d’API REST pour la console de gestion

À propos des points de terminaison la console de gestion

La fonctionnalité complète des points de terminaison de la console de gestion a été ajoutée aux points de terminaison Manage GHES dans GitHub Enterprise Server version 3.12. La parité des fonctionnalités étant atteinte, les points de terminaison d’API de la console de gestion étaient déconseillés dans la version 3.15.

Pour vous aider à migrer, la table de mappage ci-dessous indique l’opération Gestion GHES équivalente à chaque opération de la console de gestion.

Objectif	Opération d’API de la console de gestion	Opération d’API Manage GHES
Obtenir status de la configuration	`GET /setup/api/configcheck`	`GET /manage/v1/config/apply`
Démarrer le processus de configuration	`POST /setup/api/configure`	`POST /manage/v1/config/apply`
Obtenir le status de maintenance	`GET /setup/api/maintenance`	`GET /manage/v1/maintenance`
Activer ou désactiver le mode maintenance	`POST /setup/api/maintenance`	`POST /manage/v1/maintenance`
Obtenir les paramètres	`GET /setup/api/settings`	`GET /manage/v1/config/settings`
Définir les paramètres	`PUT /setup/api/settings`	`PUT /manage/v1/config/settings`
Obtenir toutes les clés SSH autorisées	`GET /setup/api/settings/authorized-keys`	`GET /manage/v1/access/ssh`
Ajouter une clé SSH autorisée	`POST /setup/api/settings/authorized-keys`	`POST /manage/v1/access/ssh`
Supprimer une clé SSH autorisée	`DELETE /setup/api/settings/authorized-keys`	`DELETE /manage/v1/access/ssh`
Créer une licence GitHub	`POST /setup/api/start`	`POST /manage/v1/config/init`
Mettre à niveau une licence	`POST /setup/api/upgrade`	`PUT /manage/v1/config/license`

À propos de la Management Console

Vous devez définir explicitement le numéro de port lors de l’exécution d’appels d’API à la console de gestion. Si TLS est activé sur votre entreprise, le numéro de port est 8443. Sinon, le numéro de port est 8080.

Si vous ne pouvez pas fournir un numéro de port, vous devez configurer votre outil pour suivre automatiquement les redirections.

Vous devrez peut-être également ajouter l’indicateur -k lors de l’utilisation de curl, car GitHub Enterprise Server utilise un certificat auto-signé avant que vous ajoutiez votre propre certificat TLS.

Authentification en tant qu’administrateur de site racine

Vous devez transmettre votre mot de passed’administrateur de site racine comme jeton d’authentification à tous les points de terminaison de cette catégorie, à l’exception de « Créer une licence GitHub ».

Utilisez le paramètre api_key pour envoyer ce jeton avec chaque requête. Par exemple :

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

Vous pouvez également utiliser l’authentification HTTP standard pour envoyer ce jeton. Par exemple :

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

Authentification en tant qu’Management Consoleutilisateur

Les comptes d’utilisateur de la console de gestion peuvent également s’authentifier pour accéder à ce point de terminaison.

Pour s’authentifier avec le mot de passe d’un Management Console compte d'utilisateur, utilisez l’authentification HTTP standard. Dans l’exemple suivant, remplacez YOUR_USER_NAME et YOUR_PASSWORD par le nom d’utilisateur et le mot de passe du compte.

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

Codes d’état de la réponse HTTP pour « Get the configuration status »

Code d’état	Description
`200`	OK
`401`	Unauthorized

Exemples de code pour « Get the configuration status »

Exemple de requête

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:

Codes d’état de la réponse HTTP pour « Start a configuration process »

Code d’état	Description
`202`	Accepted
`401`	Unauthorized

Exemples de code pour « Start a configuration process »

Exemple de requête

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:

Codes d’état de la réponse HTTP pour « Get the maintenance status »

Code d’état	Description
`200`	OK
`401`	Unauthorized

Exemples de code pour « Get the maintenance status »

Exemple de requête

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.

Paramètres pour « Enable or disable maintenance mode »

Paramètres du corps
Nom, Type, Description
`maintenance` string Obligatoire 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.

Codes d’état de la réponse HTTP pour « Enable or disable maintenance mode »

Code d’état	Description
`200`	OK
`401`	Unauthorized

Exemples de code pour « Enable or disable maintenance mode »

Exemple de requête

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.

Codes d’état de la réponse HTTP pour « Get settings »

Code d’état	Description
`200`	OK
`401`	Unauthorized

Exemples de code pour « Get settings »

Exemple de requête

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

Paramètres pour « Set settings »

Paramètres du corps
Nom, Type, Description
`settings` string Obligatoire 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.

Codes d’état de la réponse HTTP pour « Set settings »

Code d’état	Description
`204`	No Content
`401`	Unauthorized

Exemples de code pour « Set settings »

Exemple de requête

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

Codes d’état de la réponse HTTP pour « Get all authorized SSH keys »

Code d’état	Description
`200`	OK
`401`	Unauthorized

Exemples de code pour « Get all authorized SSH keys »

Exemple de requête

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.

Paramètres pour « Add an authorized SSH key »

Paramètres du corps
Nom, Type, Description
`authorized_key` string Obligatoire The public SSH key.

Codes d’état de la réponse HTTP pour « Add an authorized SSH key »

Code d’état	Description
`201`	Created
`401`	Unauthorized

Exemples de code pour « Add an authorized SSH key »

Exemple de requête

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.

Paramètres pour « Remove an authorized SSH key »

Paramètres du corps
Nom, Type, Description
`authorized_key` string Obligatoire The public SSH key.

Codes d’état de la réponse HTTP pour « Remove an authorized SSH key »

Code d’état	Description
`200`	OK
`401`	Unauthorized

Exemples de code pour « Remove an authorized SSH key »

Exemple de requête

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.

Paramètres pour « Create a GitHub license »

Paramètres du corps
Nom, Type, Description
`license` string Obligatoire 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.

Codes d’état de la réponse HTTP pour « Create a GitHub license »

Code d’état	Description
`202`	Accepted
`401`	Unauthorized

Exemples de code pour « Create a GitHub license »

Exemple de requête

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.

Paramètres pour « Upgrade a license »

Paramètres du corps
Nom, Type, Description
`license` string The content of your new .ghl license file.

Codes d’état de la réponse HTTP pour « Upgrade a license »

Code d’état	Description
`202`	Accepted
`401`	Unauthorized

Exemples de code pour « Upgrade a license »

Exemple de requête

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