The GitHub Setup API is the administrative interface for GitHub Enterprise Server that lets you automate tasks normally done in the Management Console during first-time and ongoing configuration. It provides endpoints to upload and apply your license, set the hostname and TLS certificates, configure system services like SMTP, create or reset the initial admin credentials, start and monitor reconfiguration runs, and query setup status and health.
openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Setup API
description: >-
The GitHub Setup APIs provide endpoints for configuring and managing the
initial setup and administrative settings of GitHub Enterprise Server
instances. These APIs allow system administrators to programmatically
control enterprise-level configurations such as authentication settings,
license management, maintenance mode operations, server statistics and
health checks, and other foundational setup tasks required to deploy and
maintain a GitHub Enterprise Server installation. This API is primarily used
by DevOps teams and system administrators to automate GitHub Enterprise
Server deployments, integrate server management into infrastructure-as-code
workflows, monitor server health and performance, and ensure consistent
configuration across multiple enterprise instances.
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://docs.github.com/articles/github-terms-of-service
contact:
name: Support
url: https://support.github.com/contact?tags=dotcom-rest-api
x-github-plan: ghes
x-github-release: 3.9
tags:
- name: Add
- name: All
- name: Authorized
- name: Configuration
- name: Create
- name: Disables
- name: Enables
- name: Get
- name: Keys
- name: Licenses
- name: Maintenance
- name: Modes
- name: Process
- name: Remove
- name: Sets
- name: Settings
- name: Ssh
- name: Start
- name: Status
- name: Upgrade
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
externalDocs:
description: GitHub Enterprise Developer Docs
url: https://docs.github.com/[email protected]/rest/
paths:
/setup/api/configcheck:
get:
summary: GitHub Get the Configuration Status
description: >-
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 |
operationId: getTheConfigurationStatus
tags:
- Configuration
- Get
- Status
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#get-the-configuration-status
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
default: HOSTNAME
description: Self-hosted Enterprise Server hostname
protocol:
default: http
description: Self-hosted Enterprise Server protocol
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/configuration-status'
examples:
default:
$ref: '#/components/examples/configuration-status'
'401':
description: Unauthorized
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: management-console
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/setup/api/configure:
post:
summary: GitHub Start Configuration Process
description: >-
The GitHub Setup API's `/setup/api/configure` endpoint accepts POST
requests to initiate the configuration process for a new GitHub
Enterprise Server instance. This endpoint is typically called during the
initial setup phase when administrators need to establish basic system
settings such as management console password, hostname, and other
foundational configurations. The API operation triggers the
configuration workflow that prepares the instance for use, and it
returns a response indicating whether the configuration process has
successfully started or if any errors occurred during initialization.
operationId: startConfigurationProcess
tags:
- Configuration
- Process
- Start
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#start-a-configuration-process
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
default: HOSTNAME
description: Self-hosted Enterprise Server hostname
protocol:
default: http
description: Self-hosted Enterprise Server protocol
responses:
'202':
description: Response
'401':
description: Unauthorized
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: management-console
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/setup/api/maintenance:
get:
summary: GitHub Get the Maintenance Status
description: >-
The GitHub Setup API endpoint `/setup/api/maintenance` using the GET
method retrieves the current maintenance status of a GitHub Enterprise
Server instance. This operation allows administrators and monitoring
systems to programmatically check whether the server is currently in
maintenance mode, which is useful for coordinating deployments,
upgrades, or troubleshooting activities. The endpoint returns
information about the maintenance state, helping teams understand if the
instance is available for normal operations or if maintenance procedures
are currently active, enabling better orchestration of administrative
tasks and communication with users about system availability.
operationId: getTheMaintenanceStatus
tags:
- Get
- Maintenance
- Status
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#get-the-maintenance-status
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
default: HOSTNAME
description: Self-hosted Enterprise Server hostname
protocol:
default: http
description: Self-hosted Enterprise Server protocol
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/maintenance-status'
examples:
default:
$ref: '#/components/examples/maintenance-status'
'401':
description: Unauthorized
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: management-console
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Enable or Disable Maintenance Mode
description: >-
**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](https://curl.se/docs/manpage.html#--data-urlencode).
operationId: enableOrDisableMaintenanceMode
tags:
- Disables
- Enables
- Maintenance
- Modes
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#enable-or-disable-maintenance-mode
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
default: HOSTNAME
description: Self-hosted Enterprise Server hostname
protocol:
default: http
description: Self-hosted Enterprise Server protocol
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/maintenance-status'
examples:
default:
$ref: '#/components/examples/maintenance-status'
'401':
description: Unauthorized
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
maintenance:
type: string
description: >-
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](https://github.com/mojombo/chronic).
required:
- maintenance
examples:
default:
value:
maintenance: '{"enabled":true, "when":"now"}'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: management-console
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/setup/api/settings:
get:
summary: GitHub Get Settings
description: >-
Gets the settings for your instance. To change settings, see the [Set
settings
endpoint](https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#set-settings).
**Note:** You cannot retrieve the management console password with the
Enterprise administration API.
operationId: getSettings
tags:
- Get
- Settings
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#get-settings
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
default: HOSTNAME
description: Self-hosted Enterprise Server hostname
protocol:
default: http
description: Self-hosted Enterprise Server protocol
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/enterprise-settings'
examples:
default:
$ref: '#/components/examples/enterprise-settings'
'401':
description: Unauthorized
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: management-console
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Set Settings
description: >-
Applies settings on your instance. For a list of the available settings,
see the [Get settings
endpoint](https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#get-settings).
**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](https://curl.se/docs/manpage.html#--data-urlencode).
- 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](https://docs.github.com/[email protected]/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-set-password)."
operationId: setSettings
tags:
- Sets
- Settings
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#set-settings
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
default: HOSTNAME
description: Self-hosted Enterprise Server hostname
protocol:
default: http
description: Self-hosted Enterprise Server protocol
responses:
'204':
description: Response
'401':
description: Unauthorized
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
settings:
type: string
description: >-
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](https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#get-settings).
required:
- settings
examples:
'204':
value:
settings: '{ "enterprise": { "public_pages": true }}'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: management-console
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/setup/api/settings/authorized-keys:
get:
summary: GitHub Get All Authorized Ssh Keys
description: >-
The GitHub Setup API endpoint `/setup/api/settings/authorized-keys` with
the GET method retrieves a complete list of all authorized SSH keys that
have been configured for the GitHub instance. This operation allows
administrators to view all SSH public keys that are currently authorized
for authentication purposes, providing visibility into which keys have
access to the system. The endpoint returns information about each
authorized key, which typically includes details such as the key
fingerprint, key type, and associated metadata. This is particularly
useful for security audits, access management, and ensuring that only
approved SSH keys maintain access to the GitHub server.
operationId: getAllAuthorizedSshKeys
tags:
- All
- Authorized
- Get
- Keys
- Ssh
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#get-all-authorized-ssh-keys
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
default: HOSTNAME
description: Self-hosted Enterprise Server hostname
protocol:
default: http
description: Self-hosted Enterprise Server protocol
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ssh-key'
examples:
default:
$ref: '#/components/examples/ssh-key-items'
'401':
description: Unauthorized
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: management-console
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Add an Authorized Ssh Key
description: >-
**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](https://curl.se/docs/manpage.html#--data-urlencode).
operationId: addAnAuthorizedSshKey
tags:
- Add
- Authorized
- Keys
- Ssh
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#add-an-authorized-ssh-key
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
default: HOSTNAME
description: Self-hosted Enterprise Server hostname
protocol:
default: http
description: Self-hosted Enterprise Server protocol
responses:
'201':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ssh-key'
examples:
default:
$ref: '#/components/examples/ssh-key-items'
'401':
description: Unauthorized
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
authorized_key:
type: string
description: The public SSH key.
required:
- authorized_key
examples:
default:
value:
authorized_key: >-
ssh-rsa
AAAAB3NzaC1yc2EAAAADAQABAAAAgQCssTL/Vtu/ODLTj0VtZoRAbvf7uiv5997GyDq0MoAZUjb5jmA5wYe2/wF6sFuhiZTnZoF1ZtCHunPp0hM/GHrn6VySBhNncx14YO8FPt1CIhEeRMSEjUK9cY3xAbS365oXY8vnUHJsS9+1tr/2bx/+4NJfcUt/Ezf1OR/0LStQXw==
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: management-console
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Remove an Authorized Ssh Key
description: >-
**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](https://curl.se/docs/manpage.html#--data-urlencode).
operationId: removeAnAuthorizedSshKey
tags:
- Authorized
- Keys
- Remove
- Ssh
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#remove-an-authorized-ssh-key
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
default: HOSTNAME
description: Self-hosted Enterprise Server hostname
protocol:
default: http
description: Self-hosted Enterprise Server protocol
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ssh-key'
examples:
default:
$ref: '#/components/examples/ssh-key-items'
'401':
description: Unauthorized
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
authorized_key:
type: string
description: The public SSH key.
required:
- authorized_key
examples:
default:
value:
authorized_key: >-
ssh-rsa
AAAAB3NzaC1yc2EAAAADAQABAAAAgQCssTL/Vtu/ODLTj0VtZoRAbvf7uiv5997GyDq0MoAZUjb5jmA5wYe2/wF6sFuhiZTnZoF1ZtCHunPp0hM/GHrn6VySBhNncx14YO8FPt1CIhEeRMSEjUK9cY3xAbS365oXY8vnUHJsS9+1tr/2bx/+4NJfcUt/Ezf1OR/0LStQXw==
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: management-console
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/setup/api/start:
post:
summary: GitHub Create Github License
description: >-
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`](https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#start-a-configuration-process)
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](https://curl.se/docs/manpage.html#-F).
operationId: createGithubLicense
tags:
- Create
- Licenses
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#create-a-github-license
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
default: HOSTNAME
description: Self-hosted Enterprise Server hostname
protocol:
default: http
description: Self-hosted Enterprise Server protocol
responses:
'202':
description: Response
'401':
description: Unauthorized
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
license:
type: string
description: The content of your _.ghl_ license file.
password:
type: string
description: >-
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:
type: string
description: >-
An optional JSON string containing the installation
settings. For a list of the available settings, see the [Get
settings
endpoint](https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#get-settings).
required:
- license
examples:
default:
value:
license: '@enterprise.ghl'
password: secret
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: management-console
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/setup/api/upgrade:
post:
summary: GitHub Upgrade License
description: >-
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](https://curl.se/docs/manpage.html#-F).
operationId: upgradeLicense
tags:
- Licenses
- Upgrade
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/management-console#upgrade-a-license
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
default: HOSTNAME
description: Self-hosted Enterprise Server hostname
protocol:
default: http
description: Self-hosted Enterprise Server protocol
responses:
'202':
description: Response
'401':
description: Unauthorized
requestBody:
required: false
content:
multipart/form-data:
schema:
type: object
properties:
license:
type: string
description: The content of your new _.ghl_ license file.
examples:
default:
value:
license: '@enterprise.ghl'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: management-console
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
examples:
configuration-status:
value:
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
maintenance-status:
value:
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
enterprise-settings:
value:
enterprise:
private_mode: false
public_pages: false
subdomain_isolation: true
signup_enabled: false
github_hostname: ghe.local
identicons_host: dotcom
http_proxy:
auth_mode: default
expire_sessions: false
admin_password:
configuration_id: 1401777404
configuration_run_count: 4
avatar:
enabled: false
uri: ''
customer:
name: GitHub
email: [email protected]
uuid: af6cac80-e4e1-012e-d822-1231380e52e9
secret_key_data: |
--BEGIN PGP PRIVATE KEY BLOCK--
Version: GnuPG v1.4.10 (GNU/Linux)
lQcYBE5TCgsBEACk4yHpUcapplebaumBMXYMiLF+nCQ0lxpx...
--END PGP PRIVATE KEY BLOCK--
public_key_data: |
--BEGIN PGP PUBLIC KEY BLOCK--
Version: GnuPG v1.4.10 (GNU/Linux)
mI0ETqzZYgEEALSe6snowdenXyqvLfSQ34HWD6C7....
--END PGP PUBLIC KEY BLOCK--
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:
key:
ldap:
host:
port: 0
base: []
uid:
bind_dn:
password:
method: Plain
search_strategy: detect
user_groups: []
admin_group:
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:
org:
profile:
uid: uid
name:
mail:
key:
cas:
url:
saml:
sso_url:
certificate:
certificate_path:
issuer:
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: [email protected]
support_address_type: email
noreply_address: [email protected]
ntp:
primary_server: 0.pool.ntp.org
secondary_server: 1.pool.ntp.org
timezone:
snmp:
enabled: false
community: ''
syslog:
enabled: false
server:
protocol_name: udp
assets:
pages:
enabled: true
collectd:
enabled: false
server:
port: 0
encryption:
username:
password:
mapping:
enabled: true
tileserver:
basemap: company.map-qsz2zrvs
token:
load_balancer:
run_list:
- recipe[enterprise-configure]
ssh-key-items:
value:
- 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
reponses: {}
parameters: {}
schemas:
configuration-status:
type: object
properties:
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-setup-openapi.yml