Management Console

The Management Console API helps you manage your GitHub Enterprise installation.

You must explicitly set the port number when making API calls to the Management Console. If TLS is enabled on your Enterprise instance, the port number is 8443; otherwise, the port number is 8080.

If you don't want to provide a port number, you'll need to configure your tool to automatically follow redirects.

You may also need to add the -k flag when using curl, since GitHub Enterprise uses a self-signed certificate before you add your own TLS certificate.

Authentication

You need to pass your Management Console password as an authentication token to every Management Console API endpoint except /setup/api/start.

Use the api_key parameter to send this token with each request. For example:

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

You can also use standard HTTP authentication to send this token. For example:

curl -L 'https://api_key:your-amazing-password@hostname:admin_port/setup/api'

Upload a license for the first time

When you boot a virtual machine for the first time, you can use the following endpoint to upload a license:

POST /setup/api/start

Note that you need to POST to /setup/api/configure to start the actual configuration process.

When using this endpoint, your Enterprise 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.

Parameters

Name Type Description
license string Required. 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 /setup/api/settings endpoint.

Response

HTTP/1.1 202 Created
Location: http://hostname:admin_port/setup/api/configcheck

Example

curl -L -X POST 'https://hostname:admin_port/setup/api/start' -F license=@/path/to/github-enterprise.ghl -F "password=your-amazing-password" -F settings=</path/to/settings.json

Upgrade a license

This API upgrades your license and also triggers the configuration process:

POST /setup/api/upgrade

Parameters

Name Type Description
license string The content of your new .ghl license file.

Response

HTTP/1.1 202 Accepted
Location: http://hostname:admin_port/setup/api/configcheck

Example

curl -L -X POST 'https://api_key:your-amazing-password@hostname:admin_port/setup/api/upgrade'

Check configuration status

This endpoint allows you to check the status of the most recent configuration process:

GET /setup/api/configcheck

Note that you may need to wait several seconds after you start a process before you can check its status.

Response

Status: 200 OK
{
  "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"
    }
  ]
}

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

Example

curl -L 'https://api_key:your-amazing-password@hostname:admin_port/setup/api/configcheck'

Start a configuration process

This endpoint allows you to start a configuration process at any time for your updated settings to take effect:

POST /setup/api/configure

Response

HTTP/1.1 202 Accepted
Location: http://hostname:admin_port/setup/api/configcheck

Example

curl -L -X POST 'https://api_key:your-amazing-password@hostname:admin_port/setup/api/configure'

Retrieve settings

GET /setup/api/settings

Response

Status: 200 OK
{
  "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",
      "support_address": "enterprise@github.com",
      "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]"
  ]
}

Example

curl -L 'https://api_key:your-amazing-password@hostname:admin_port/setup/api/settings'

Modify settings

PUT /setup/api/settings

Parameters

Name Type Description
settings string Required. A JSON string with the new settings. Note that you only need to pass the specific settings you want to modify.

Response

HTTP/1.1 204 No Content

Example

curl -L -X PUT 'https://api_key:your-amazing-password@hostname:admin_port/setup/api/settings' --data-urlencode "settings=`cat /path/to/settings.json`"

Check maintenance status

Check your installation's maintenance status:

GET /setup/api/maintenance

Response

Status: 200 OK
{
  "status": "scheduled",
  "scheduled_time": "Tuesday, January 22 at 15 => 34 -0800",
  "connection_services": [
    {
      "name": "git operations",
      "number": 0
    },
    {
      "name": "mysql queries",
      "number": 233
    },
    {
      "name": "resque jobs",
      "number": 54
    }
  ]
}

Example

curl -L 'https://api_key:your-amazing-password@hostname:admin_port/setup/api/maintenance'

Enable or disable maintenance mode

POST /setup/api/maintenance

Parameters

Name Type Description
maintenance string Required. 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.

Response

Status: 200 OK
{
  "status": "scheduled",
  "scheduled_time": "Tuesday, January 22 at 15 => 34 -0800",
  "connection_services": [
    {
      "name": "git operations",
      "number": 0
    },
    {
      "name": "mysql queries",
      "number": 233
    },
    {
      "name": "resque jobs",
      "number": 54
    }
  ]
}

Example

curl -L -X POST 'https://api_key:your-amazing-password@hostname:admin_port/setup/api/maintenance' -d 'maintenance={"enabled":true, "when":"now"}'

Retrieve authorized SSH keys

GET /setup/api/settings/authorized-keys

Response

Status: 200 OK
[
  {
    "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"
  }
]

Example

curl -L 'https://api_key:your-amazing-password@hostname:admin_port/setup/api/settings/authorized-keys'

Add a new authorized SSH key

POST /setup/api/settings/authorized-keys

Parameters

Name Type Description
authorized_key string Required. The path to the public SSH key.

Response

Status: 201 Created
[
  {
    "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"
  }
]

Example

curl -L -X POST 'https://api_key:your-amazing-password@hostname:admin_port/setup/api/settings/authorized-keys' -F authorized_key=@/path/to/key.pub

Remove an authorized SSH key

DELETE /setup/api/settings/authorized-keys

Parameters

Name Type Description
authorized_key string Required. The path to the public SSH key.

Response

Status: 200 OK
[
  {
    "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"
  }
]

Example

curl -L -X DELETE 'https://api_key:your-amazing-password@hostname:admin_port/setup/api/settings/authorized-keys' -F authorized_key=@/path/to/key.pub