This version of GitHub Enterprise was discontinued on 2021-03-02. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

GitHub Enterprise administration

In this article

You can use these endpoints to administer your enterprise.

Endpoint URLs

REST API endpoints—except Management Console API endpoints— are prefixed with the following URL:

http(s)://[hostname]/api/v3

Management Console API endpoints are only prefixed with a hostname:

http(s)://hostname/

Authentication

Your GitHub Enterprise Server installation's API endpoints accept the same authentication methods as the GitHub.com API. You can authenticate yourself with OAuth tokens (which can be created using the Authorizations API) or basic authentication. OAuth tokens must have the site_admin OAuth scope when used with Enterprise-specific endpoints.

Enterprise administration API endpoints are only accessible to authenticated GitHub Enterprise Server site administrators, except for the Management Console API, which requires the Management Console password.

Version information

The current version of your enterprise is returned in the response header of every API: X-GitHub-Enterprise-Version: enterprise-server@2.20.0 You can also read the current version by calling the meta endpoint.

Admin stats

The Admin Stats API provides a variety of metrics about your installation. It is only available to authenticated site administrators. Normal users will receive a 404 response if they try to access it.

Get statistics

There are a variety of types to choose from:

TypeDescription
issuesThe number of open and closed issues.
hooksThe number of active and inactive hooks.
milestonesThe number of open and closed milestones.
orgsThe number of organizations, teams, team members, and disabled organizations.
commentsThe number of comments on issues, pull requests, commits, and gists.
pagesThe number of GitHub Pages sites.
usersThe number of suspended and admin users.
gistsThe number of private and public gists.
pullsThe number of merged, mergeable, and unmergeable pull requests.
reposThe number of organization-owned repositories, root repositories, forks, pushed commits, and wikis.
allAll of the statistics listed above.

These statistics are cached and will be updated approximately every 10 minutes.

get /enterprise/stats/{type}

Parameters

Name Type In Description
accept string header

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

type string path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/TYPE
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/{type}', {
  type: 'type'
})

Default response

Status: 200 OK
{
  "repos": {
    "total_repos": 212,
    "root_repos": 194,
    "fork_repos": 18,
    "org_repos": 51,
    "total_pushes": 3082,
    "total_wikis": 15
  },
  "hooks": {
    "total_hooks": 27,
    "active_hooks": 23,
    "inactive_hooks": 4
  },
  "pages": {
    "total_pages": 36
  },
  "orgs": {
    "total_orgs": 33,
    "disabled_orgs": 0,
    "total_teams": 60,
    "total_team_members": 314
  },
  "users": {
    "total_users": 254,
    "admin_users": 45,
    "suspended_users": 21
  },
  "pulls": {
    "total_pulls": 86,
    "merged_pulls": 60,
    "mergeable_pulls": 21,
    "unmergeable_pulls": 3
  },
  "issues": {
    "total_issues": 179,
    "open_issues": 83,
    "closed_issues": 96
  },
  "milestones": {
    "total_milestones": 7,
    "open_milestones": 6,
    "closed_milestones": 1
  },
  "gists": {
    "total_gists": 178,
    "private_gists": 151,
    "public_gists": 25
  },
  "comments": {
    "total_commit_comments": 6,
    "total_gist_comments": 28,
    "total_issue_comments": 366,
    "total_pull_request_comments": 30
  }
}

Global webhooks

Global webhooks are installed on your enterprise. You can use global webhooks to automatically monitor, respond to, or enforce rules for users, organizations, teams, and repositories on your enterprise. Global webhooks can subscribe to the organization, user, repository, team, member, membership, fork, and ping event types.

This API is only available to authenticated site administrators. Normal users will receive a 404 response if they try to access it. To learn how to configure global webhooks, see About global webhooks.

get /admin/hooks

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

accept string header

This API is under preview and subject to change.

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/hooks', {
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Default response

Status: 200 OK
[
  {
    "type": "Global",
    "id": 1,
    "name": "web",
    "active": true,
    "events": [
      "organization",
      "user"
    ],
    "config": {
      "url": "https://example.com",
      "content_type": "json",
      "insecure_ssl": "0",
      "secret": "********"
    },
    "updated_at": "2017-12-07T00:14:59Z",
    "created_at": "2017-12-07T00:14:59Z",
    "url": "https://api.github.com/admin/hooks/1",
    "ping_url": "https://api.github.com/admin/hooks/1/pings"
  }
]

Preview notice

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️ This header is required.

post /admin/hooks

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

accept string header

This API is under preview and subject to change.

name string body

Required. Must be passed as "web".

config object body

Required. Key/value pairs to provide settings for this webhook.

Properties of the config object

url (string)

Required. The URL to which the payloads will be delivered.

content_type (string)

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secret (string)

If provided, the secret will be used as the key to generate the HMAC hex digest value in the X-Hub-Signature header.

insecure_ssl (string)

Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

events array of strings body

The events that trigger this webhook. A global webhook can be triggered by user and organization events. Default: user and organization.

active boolean body

Determines if notifications are sent when the webhook is triggered. Set to true to send notifications.

Default: true

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks \
  -d '{"name":"name","config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl"}}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/hooks', {
  name: 'name',
  config: {
    url: 'url',
    content_type: 'content_type',
    secret: 'secret',
    insecure_ssl: 'insecure_ssl'
  },
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Default response

Status: 201 Created
{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization",
    "user"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "json",
    "insecure_ssl": "0",
    "secret": "********"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

Preview notice

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️ This header is required.

get /admin/hooks/{hook_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

accept string header

This API is under preview and subject to change.

hook_id integer path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/hooks/{hook_id}', {
  hook_id: 42,
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Default response

Status: 200 OK
{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization",
    "user"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "json",
    "insecure_ssl": "0",
    "secret": "********"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

Preview notice

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️ This header is required.

Update a global webhook

Parameters that are not provided will be overwritten with the default value or removed if no default exists.

patch /admin/hooks/{hook_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

accept string header

This API is under preview and subject to change.

hook_id integer path
config object body

Key/value pairs to provide settings for this webhook.

Properties of the config object

url (string)

Required. The URL to which the payloads will be delivered.

content_type (string)

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secret (string)

If provided, the secret will be used as the key to generate the HMAC hex digest value in the X-Hub-Signature header.

insecure_ssl (string)

Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

events array of strings body

The events that trigger this webhook. A global webhook can be triggered by user and organization events. Default: user and organization.

active boolean body

Determines if notifications are sent when the webhook is triggered. Set to true to send notifications.

Default: true

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks/42 \
  -d '{"config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl"}}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/hooks/{hook_id}', {
  hook_id: 42,
  config: {
    url: 'url',
    content_type: 'content_type',
    secret: 'secret',
    insecure_ssl: 'insecure_ssl'
  },
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Default response

Status: 200 OK
{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "form",
    "insecure_ssl": "0"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

Preview notice

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️ This header is required.

delete /admin/hooks/{hook_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

accept string header

This API is under preview and subject to change.

hook_id integer path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/hooks/{hook_id}', {
  hook_id: 42,
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Response

Status: 204 No Content

Preview notice

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️ This header is required.

Ping a global webhook

This will trigger a ping event to be sent to the webhook.

post /admin/hooks/{hook_id}/pings

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

accept string header

This API is under preview and subject to change.

hook_id integer path

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks/42/pings
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/hooks/{hook_id}/pings', {
  hook_id: 42,
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Response

Status: 204 No Content

Preview notice

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️ This header is required.

LDAP

You can use the LDAP API to update account relationships between a GitHub Enterprise Server user or team and its linked LDAP entry or queue a new synchronization.

With the LDAP mapping endpoints, you're able to update the Distinguished Name (DN) that a user or team maps to. Note that the LDAP endpoints are generally only effective if your GitHub Enterprise Server appliance has LDAP Sync enabled. The Update LDAP mapping for a user endpoint can be used when LDAP is enabled, even if LDAP Sync is disabled.

Update LDAP mapping for a team

Updates the distinguished name (DN) of the LDAP entry to map to a team. LDAP synchronization must be enabled to map LDAP entries to a team. Use the Create a team endpoint to create a team with LDAP mapping.

You can also update the LDAP mapping of a child team.

patch /admin/ldap/teams/{team_id}/mapping

Parameters

Name Type In Description
accept string header

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

team_id integer path
ldap_dn string body

The distinguished name (DN) of the LDAP entry to map to a team.

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/ldap/teams/42/mapping \
  -d '{"ldap_dn":"ldap_dn"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/ldap/teams/{team_id}/mapping', {
  team_id: 42,
  ldap_dn: 'ldap_dn'
})

Default response

Status: 200 OK
{
  "ldap_dn": "cn=Enterprise Ops,ou=teams,dc=github,dc=com",
  "id": 1,
  "node_id": "MDQ6VGVhbTE=",
  "url": "https://api.github.com/teams/1",
  "html_url": "https://github.com/orgs/github/teams/justice-league",
  "name": "Justice League",
  "slug": "justice-league",
  "description": "A great team.",
  "privacy": "closed",
  "permission": "admin",
  "members_url": "https://api.github.com/teams/1/members{/member}",
  "repositories_url": "https://api.github.com/teams/1/repos",
  "parent": null
}

Sync LDAP mapping for a team

Note that this API call does not automatically initiate an LDAP sync. Rather, if a 201 is returned, the sync job is queued successfully, and is performed when the instance is ready.

post /admin/ldap/teams/{team_id}/sync

Parameters

Name Type In Description
accept string header

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

team_id integer path

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/ldap/teams/42/sync
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/ldap/teams/{team_id}/sync', {
  team_id: 42
})

Response

Status: 201 Created
{
  "status": "queued"
}

patch /admin/ldap/users/{username}/mapping

Parameters

Name Type In Description
accept string header

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

username string path
ldap_dn string body

The distinguished name (DN) of the LDAP entry to map to a team.

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/ldap/users/USERNAME/mapping \
  -d '{"ldap_dn":"ldap_dn"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/ldap/users/{username}/mapping', {
  username: 'username',
  ldap_dn: 'ldap_dn'
})

Default response

Status: 200 OK
{
  "ldap_dn": "uid=asdf,ou=users,dc=github,dc=com",
  "login": "octocat",
  "id": 1,
  "node_id": "MDQ6VXNlcjE=",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "gravatar_id": "",
  "url": "https://api.github.com/users/octocat",
  "html_url": "https://github.com/octocat",
  "followers_url": "https://api.github.com/users/octocat/followers",
  "following_url": "https://api.github.com/users/octocat/following{/other_user}",
  "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
  "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
  "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
  "organizations_url": "https://api.github.com/users/octocat/orgs",
  "repos_url": "https://api.github.com/users/octocat/repos",
  "events_url": "https://api.github.com/users/octocat/events{/privacy}",
  "received_events_url": "https://api.github.com/users/octocat/received_events",
  "type": "User",
  "site_admin": false
}

Sync LDAP mapping for a user

Note that this API call does not automatically initiate an LDAP sync. Rather, if a 201 is returned, the sync job is queued successfully, and is performed when the instance is ready.

post /admin/ldap/users/{username}/sync

Parameters

Name Type In Description
accept string header

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

username string path

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/ldap/users/USERNAME/sync
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/ldap/users/{username}/sync', {
  username: 'username'
})

Response

Status: 201 Created
{
  "status": "queued"
}

License

The License API provides information on your Enterprise license. It is only available to authenticated site administrators. Normal users will receive a 404 response if they try to access it.

get /enterprise/settings/license

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/settings/license
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/settings/license')

Default response

Status: 200 OK
{
  "seats": 1400,
  "seats_used": 1316,
  "seats_available": 84,
  "kind": "standard",
  "days_until_expiration": 365,
  "expire_at": "2016/02/06 12:41:52 -0600"
}

Management console

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

You must explicitly set the port number when making API calls to the Management Console. If TLS is enabled on your enterprise, 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 Server 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'

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
get /setup/api/configcheck

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/configcheck
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/configcheck')

Default 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"
    }
  ]
}

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

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/configure
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/configure')

Response

Status: 202 Accepted

Get the maintenance status

Check your installation's maintenance status:

get /setup/api/maintenance

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/maintenance
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/maintenance')

Default 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
    }
  ]
}

Enable or disable maintenance mode

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.

post /setup/api/maintenance

Parameters

Name Type In Description
accept string header

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

maintenance string body

Required. A JSON string with the attributes enabled and when.

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/maintenance \
  -d '{"maintenance":"maintenance"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/maintenance', {
  maintenance: 'maintenance'
})

Default 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
    }
  ]
}

get /setup/api/settings

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/settings')

Default 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",
      "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

For a list of the available settings, see the Get settings endpoint.

put /setup/api/settings

Parameters

Name Type In Description
accept string header

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

settings string body

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

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings \
  -d '{"settings":"settings"}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /setup/api/settings', {
  settings: 'settings'
})

Response

Status: 204 No Content

get /setup/api/settings/authorized-keys

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings/authorized-keys
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/settings/authorized-keys')

Default 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"
  }
]

post /setup/api/settings/authorized-keys

Parameters

Name Type In Description
accept string header

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

authorized_key string body

Required. The path to the public SSH key.

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings/authorized-keys \
  -d '{"authorized_key":"authorized_key"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/settings/authorized-keys', {
  authorized_key: 'authorized_key'
})

Default 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"
  }
]

delete /setup/api/settings/authorized-keys

Parameters

Name Type In Description
accept string header

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

authorized_key string body

Required. The path to the public SSH key.

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings/authorized-keys \
  -d '{"authorized_key":"authorized_key"}'
JavaScript (@octokit/core.js)
await octokit.request('DELETE /setup/api/settings/authorized-keys', {
  authorized_key: 'authorized_key'
})

Default 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"
  }
]

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.

For a list of the available settings, see the Get settings endpoint.

post /setup/api/start

Parameters

Name Type In Description
accept string header

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

license string body

Required. The content of your .ghl license file.

password string body

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 body

An optional JSON string containing the installation settings.

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/start \
  -d '{"license":"license"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/start', {
  license: 'license'
})

Response

Status: 202 Accepted

Upgrade a license

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

post /setup/api/upgrade

Parameters

Name Type In Description
accept string header

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

license string body

The content of your new .ghl license file.

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/upgrade \
  -d '{"license":"license"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/upgrade', {
  license: 'license'
})

Response

Status: 202 Accepted

Organizations

The Organization Administration API allows you to create organizations on your enterprise. It is only available to authenticated site administrators. Normal users will receive a 404 response if they try to access it.

post /admin/organizations

Parameters

Name Type In Description
accept string header

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

login string body

Required. The organization's username.

admin string body

Required. The login of the user who will manage this organization.

profile_name string body

The organization's display name.

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/organizations \
  -d '{"login":"login","admin":"admin"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/organizations', {
  login: 'login',
  admin: 'admin'
})

Default response

Status: 201 Created
{
  "login": "github",
  "id": 1,
  "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
  "url": "https://api.github.com/orgs/github",
  "repos_url": "https://api.github.com/orgs/github/repos",
  "events_url": "https://api.github.com/orgs/github/events",
  "hooks_url": "https://api.github.com/orgs/github/hooks",
  "issues_url": "https://api.github.com/orgs/github/issues",
  "members_url": "https://api.github.com/orgs/github/members{/member}",
  "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "description": "A great organization"
}

patch /admin/organizations/{org}

Parameters

Name Type In Description
accept string header

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

org string path
login string body

Required. The organization's new name.

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/organizations/ORG \
  -d '{"login":"login"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/organizations/{org}', {
  org: 'org',
  login: 'login'
})

Response

Status: 202 Accepted
{
  "message": "Job queued to rename organization. It may take a few minutes to complete.",
  "url": "https://<hostname>/api/v3/organizations/1"
}

Organization pre-receive hooks

The Organization Pre-receive Hooks API allows you to view and modify enforcement of the pre-receive hooks that are available to an organization.

Object attributes

NameTypeDescription
namestringThe name of the hook.
enforcementstringThe state of enforcement for the hook on this repository.
allow_downstream_configurationbooleanWhether repositories can override enforcement.
configuration_urlstringURL for the endpoint where enforcement is set.

Possible values for enforcement are enabled, disabled andtesting. disabled indicates the pre-receive hook will not run. enabled indicates it will run and reject any pushes that result in a non-zero status. testing means the script will run but will not cause any pushes to be rejected.

configuration_url may be a link to this endpoint or this hook's global configuration. Only site admins are able to access the global configuration.

List pre-receive hooks for an organization

List all pre-receive hooks that are enabled or testing for this organization as well as any disabled hooks that can be configured at the organization level. Globally disabled pre-receive hooks that do not allow downstream configuration are not listed.

get /orgs/{org}/pre-receive-hooks

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

org string path
per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

direction string query

One of asc (ascending) or desc (descending).

sort string query

The sort order for the response collection.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/pre-receive-hooks', {
  org: 'org',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
[
  {
    "id": 42,
    "name": "Check Commits",
    "enforcement": "disabled",
    "configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
    "allow_downstream_configuration": true
  }
]

Notes

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

get /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

org string path
pre_receive_hook_id integer path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'org',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
  "allow_downstream_configuration": true
}

Notes

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

Update pre-receive hook enforcement for an organization

For pre-receive hooks which are allowed to be configured at the org level, you can set enforcement and allow_downstream_configuration

patch /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

org string path
pre_receive_hook_id integer path
enforcement string body

The state of enforcement for the hook on this repository.

allow_downstream_configuration boolean body

Whether repositories can override enforcement.

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks/42 \
  -d '{"enforcement":"enforcement"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'org',
  pre_receive_hook_id: 42,
  enforcement: 'enforcement',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "enabled",
  "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42",
  "allow_downstream_configuration": false
}

Notes

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

Remove pre-receive hook enforcement for an organization

Removes any overrides for this hook at the org level for this org.

delete /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

org string path
pre_receive_hook_id integer path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'org',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
  "allow_downstream_configuration": true
}

Notes

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

Pre-receive environments

The Pre-receive Environments API allows you to create, list, update and delete environments for pre-receive hooks. It is only available to authenticated site administrators. Normal users will receive a 404 response if they try to access it.

Object attributes

Pre-receive Environment

NameTypeDescription
namestringThe name of the environment as displayed in the UI.
image_urlstringURL to the tarball that will be downloaded and extracted.
default_environmentbooleanWhether this is the default environment that ships with GitHub Enterprise Server.
downloadobjectThis environment's download status.
hooks_countintegerThe number of pre-receive hooks that use this environment.

Pre-receive Environment Download

NameTypeDescription
statestringThe state of the most recent download.
downloaded_atstringThe time when the most recent download started.
messagestringOn failure, this will have any error messages produced.

Possible values for state are not_started, in_progress, success, failed.

get /admin/pre-receive-environments

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

direction string query

One of asc (ascending) or desc (descending).

sort string query

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-environments', {
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
[
  {
    "id": 1,
    "name": "Default",
    "image_url": "githubenterprise://internal",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1",
    "html_url": "https://github.example.com/admin/pre-receive-environments/1",
    "default_environment": true,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 14,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1/downloads/latest",
      "state": "not_started",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  {
    "id": 2,
    "name": "DevTools Hook Env",
    "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
    "html_url": "https://github.example.com/admin/pre-receive-environments/2",
    "default_environment": false,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  }
]

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

post /admin/pre-receive-environments

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

name string body

Required. The new pre-receive environment's name.

image_url string body

Required. URL from which to download a tarball of this environment.

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments \
  -d '{"name":"name","image_url":"image_url"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/pre-receive-environments', {
  name: 'name',
  image_url: 'image_url',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 201 Created
{
  "id": 2,
  "name": "DevTools Hook Env",
  "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
  "html_url": "https://github.example.com/admin/pre-receive-environments/2",
  "default_environment": false,
  "created_at": "2016-05-20T11:35:45-05:00",
  "hooks_count": 1,
  "download": {
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
    "state": "not_started",
    "downloaded_at": null,
    "message": null
  }
}

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

get /admin/pre-receive-environments/{pre_receive_environment_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

pre_receive_environment_id integer path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
{
  "id": 2,
  "name": "DevTools Hook Env",
  "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
  "html_url": "https://github.example.com/admin/pre-receive-environments/2",
  "default_environment": false,
  "created_at": "2016-05-20T11:35:45-05:00",
  "hooks_count": 1,
  "download": {
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
    "state": "success",
    "downloaded_at": "2016-05-26T07:42:53-05:00",
    "message": null
  }
}

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

Update a pre-receive environment

You cannot modify the default environment. If you attempt to modify the default environment, you will receive a 422 Unprocessable Entity response.

patch /admin/pre-receive-environments/{pre_receive_environment_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

pre_receive_environment_id integer path
name string body

This pre-receive environment's new name.

image_url string body

URL from which to download a tarball of this environment.

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42 \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 42,
  name: 'name',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
{
  "id": 2,
  "name": "DevTools Hook Env",
  "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
  "html_url": "https://github.example.com/admin/pre-receive-environments/2",
  "default_environment": false,
  "created_at": "2016-05-20T11:35:45-05:00",
  "hooks_count": 1,
  "download": {
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
    "state": "success",
    "downloaded_at": "2016-05-26T07:42:53-05:00",
    "message": null
  }
}

Client errors

Status: 422 Unprocessable Entity
{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "PreReceiveEnvironment",
      "code": "custom",
      "message": "Cannot modify or delete the default environment"
    }
  ]
}

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

Delete a pre-receive environment

If you attempt to delete an environment that cannot be deleted, you will receive a 422 Unprocessable Entity response.

The possible error messages are:

  • Cannot modify or delete the default environment
  • Cannot delete environment that has hooks
  • Cannot delete environment when download is in progress
delete /admin/pre-receive-environments/{pre_receive_environment_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

pre_receive_environment_id integer path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 204 No Content

Client errors

Status: 422 Unprocessable Entity
{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "PreReceiveEnvironment",
      "code": "custom",
      "message": "Cannot modify or delete the default environment"
    }
  ]
}

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

Start a pre-receive environment download

Triggers a new download of the environment tarball from the environment's image_url. When the download is finished, the newly downloaded tarball will overwrite the existing environment.

If a download cannot be triggered, you will receive a 422 Unprocessable Entity response.

The possible error messages are:

  • Cannot modify or delete the default environment
  • Can not start a new download when a download is in progress
post /admin/pre-receive-environments/{pre_receive_environment_id}/downloads

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

pre_receive_environment_id integer path

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42/downloads
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/pre-receive-environments/{pre_receive_environment_id}/downloads', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 202 Accepted
{
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/3/downloads/latest",
  "state": "not_started",
  "downloaded_at": null,
  "message": null
}

Client errors

Status: 422 Unprocessable Entity
{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "PreReceiveEnvironment",
      "code": "custom",
      "message": "Can not start a new download when a download is in progress"
    }
  ]
}

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

Get the download status for a pre-receive environment

In addition to seeing the download status at the "Get a pre-receive environment" endpoint, there is also this separate endpoint for just the download status.

get /admin/pre-receive-environments/{pre_receive_environment_id}/downloads/latest

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

pre_receive_environment_id integer path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42/downloads/latest
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-environments/{pre_receive_environment_id}/downloads/latest', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
{
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/3/downloads/latest",
  "state": "success",
  "downloaded_at": "2016-05-26T07:42:53-05:00",
  "message": null
}

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

Pre-receive hooks

The Pre-receive Hooks API allows you to create, list, update and delete pre-receive hooks. It is only available to authenticated site administrators. Normal users will receive a 404 response if they try to access it.

Object attributes

Pre-receive Hook

NameTypeDescription
namestringThe name of the hook.
scriptstringThe script that the hook runs.
script_repositoryobjectThe GitHub repository where the script is kept.
environmentobjectThe pre-receive environment where the script is executed.
enforcementstringThe state of enforcement for this hook.
allow_downstream_configurationbooleanWhether enforcement can be overridden at the org or repo level.

Possible values for enforcement are enabled, disabled andtesting. disabled indicates the pre-receive hook will not run. enabled indicates it will run and reject any pushes that result in a non-zero status. testing means the script will run but will not cause any pushes to be rejected.

get /admin/pre-receive-hooks

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

direction string query

One of asc (ascending) or desc (descending).

sort string query

One of created (when the repository was starred) or updated (when it was last pushed to) or name.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-hooks', {
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
[
  {
    "id": 1,
    "name": "Check Commits",
    "enforcement": "disabled",
    "script": "scripts/commmit_check.sh",
    "script_repository": {
      "id": 595,
      "full_name": "DevIT/hooks",
      "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
      "html_url": "https://github.example.com/DevIT/hooks"
    },
    "environment": {
      "id": 2,
      "name": "DevTools Hook Env",
      "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
      "html_url": "https://github.example.com/admin/pre-receive-environments/2",
      "default_environment": false,
      "created_at": "2016-05-20T11:35:45-05:00",
      "hooks_count": 1,
      "download": {
        "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
        "state": "success",
        "downloaded_at": "2016-05-26T07:42:53-05:00",
        "message": null
      }
    },
    "allow_downstream_configuration": false
  }
]

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

post /admin/pre-receive-hooks

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

name string body

Required. The name of the hook.

script string body

Required. The script that the hook runs.

script_repository object body

Required. The GitHub repository where the script is kept.

environment object body

Required. The pre-receive environment where the script is executed.

enforcement string body

The state of enforcement for this hook. default: disabled

allow_downstream_configuration boolean body

Whether enforcement can be overridden at the org or repo level. default: false

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks \
  -d '{"name":"name","script":"script","script_repository":{},"environment":{}}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/pre-receive-hooks', {
  name: 'name',
  script: 'script',
  script_repository: {},
  environment: {},
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 201 Created
{
  "id": 1,
  "name": "Check Commits",
  "enforcement": "disabled",
  "script": "scripts/commmit_check.sh",
  "script_repository": {
    "id": 595,
    "full_name": "DevIT/hooks",
    "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
    "html_url": "https://github.example.com/DevIT/hooks"
  },
  "environment": {
    "id": 2,
    "name": "DevTools Hook Env",
    "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
    "html_url": "https://github.example.com/admin/pre-receive-environments/2",
    "default_environment": false,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  "allow_downstream_configuration": false
}

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

get /admin/pre-receive-hooks/{pre_receive_hook_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

pre_receive_hook_id integer path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
{
  "id": 1,
  "name": "Check Commits",
  "enforcement": "disabled",
  "script": "scripts/commmit_check.sh",
  "script_repository": {
    "id": 595,
    "full_name": "DevIT/hooks",
    "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
    "html_url": "https://github.example.com/DevIT/hooks"
  },
  "environment": {
    "id": 2,
    "name": "DevTools Hook Env",
    "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
    "html_url": "https://github.example.com/admin/pre-receive-environments/2",
    "default_environment": false,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  "allow_downstream_configuration": false
}

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

patch /admin/pre-receive-hooks/{pre_receive_hook_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

pre_receive_hook_id integer path
name string body

The name of the hook.

script string body

The script that the hook runs.

script_repository object body

The GitHub repository where the script is kept.

environment object body

The pre-receive environment where the script is executed.

enforcement string body

The state of enforcement for this hook.

allow_downstream_configuration boolean body

Whether enforcement can be overridden at the org or repo level.

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks/42 \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 42,
  name: 'name',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
{
  "id": 1,
  "name": "Check Commits",
  "enforcement": "disabled",
  "script": "scripts/commmit_check.sh",
  "script_repository": {
    "id": 595,
    "full_name": "DevIT/hooks",
    "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
    "html_url": "https://github.example.com/DevIT/hooks"
  },
  "environment": {
    "id": 1,
    "name": "Default",
    "image_url": "githubenterprise://internal",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1",
    "html_url": "https://github.example.com/admin/pre-receive-environments/1",
    "default_environment": true,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  "allow_downstream_configuration": true
}

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

delete /admin/pre-receive-hooks/{pre_receive_hook_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

pre_receive_hook_id integer path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 204 No Content

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

Repository pre-receive hooks

The Repository Pre-receive Hooks API allows you to view and modify enforcement of the pre-receive hooks that are available to a repository.

Object attributes

NameTypeDescription
namestringThe name of the hook.
enforcementstringThe state of enforcement for the hook on this repository.
configuration_urlstringURL for the endpoint where enforcement is set.

Possible values for enforcement are enabled, disabled andtesting. disabled indicates the pre-receive hook will not run. enabled indicates it will run and reject any pushes that result in a non-zero status. testing means the script will run but will not cause any pushes to be rejected.

configuration_url may be a link to this repository, it's organization owner or global configuration. Authorization to access the endpoint at configuration_url is determined at the owner or site admin level.

List pre-receive hooks for a repository

List all pre-receive hooks that are enabled or testing for this repository as well as any disabled hooks that are allowed to be enabled at the repository level. Pre-receive hooks that are disabled at a higher level and are not configurable will not be listed.

get /repos/{owner}/{repo}/pre-receive-hooks

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

owner string path
repo string path
per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

direction string query

One of asc (ascending) or desc (descending).

sort string query

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/pre-receive-hooks', {
  owner: 'octocat',
  repo: 'hello-world',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
[
  {
    "id": 42,
    "name": "Check Commits",
    "enforcement": "disabled",
    "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
  }
]

Notes

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

get /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

owner string path
repo string path
pre_receive_hook_id integer path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
}

Notes

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

Update pre-receive hook enforcement for a repository

For pre-receive hooks which are allowed to be configured at the repo level, you can set enforcement

patch /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

owner string path
repo string path
pre_receive_hook_id integer path
enforcement string body

The state of enforcement for the hook on this repository.

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks/42 \
  -d '{"enforcement":"enforcement"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  pre_receive_hook_id: 42,
  enforcement: 'enforcement',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "enabled",
  "configuration_url": "https://github.example.com/api/v3/repos/octocat/hello-world/pre-receive-hooks/42"
}

Notes

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

Remove pre-receive hook enforcement for a repository

Deletes any overridden enforcement on this repository for the specified hook.

Responds with effective values inherited from owner and/or global level.

delete /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

owner string path
repo string path
pre_receive_hook_id integer path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
}

Notes

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️ This header is required.

Users

The User Administration API allows you to suspend, unsuspend, promote, and demote users on your enterprise. It is only available to authenticated site administrators. Normal users will receive a 403 response if they try to access it.

get /admin/keys

Parameters

Name Type In Description
accept string header

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

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

direction string query

One of asc (ascending) or desc (descending).

sort string query
since string query

Only show public keys accessed after the given time.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/keys
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/keys')

Default response

Status: 200 OK
[
  {
    "key_id": "012345678912345678",
    "key": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234",
    "user_id": 232,
    "repository_id": null
  },
  {
    "key_id": "012345678912345678",
    "key": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234",
    "user_id": null,
    "repository_id": 2333,
    "id": "2",
    "url": "https://api.github.com/repos/octocat/Hello-World/keys/2"
  }
]

delete /admin/keys/{key_ids}

Parameters

Name Type In Description
accept string header

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

key_ids string path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/keys/KEY_IDS
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/keys/{key_ids}', {
  key_ids: 'key_ids'
})

Response

Status: 204 No Content

List personal access tokens

Lists personal access tokens for all users, including admin users.

get /admin/tokens

Parameters

Name Type In Description
accept string header

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

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/tokens
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/tokens')

Default response

Status: 200 OK
[
  {
    "id": 2,
    "url": "https://enterprise.octocat.com/api/v3/authorizations/2",
    "app": {
      "name": "My personal access token",
      "url": "https://docs.github.com/enterprise/rest/reference/enterprise-admin#list-personal-access-tokens",
      "client_id": "00000000000000000000"
    },
    "token": "",
    "hashed_token": "23cffb2fab1b0a62747863eba88cb9327e561f2f7a0c8661c0d9b83146cb8d45",
    "token_last_eight": "848f9f8a",
    "note": "My personal access token",
    "note_url": null,
    "created_at": "2019-04-24T21:49:02Z",
    "updated_at": "2019-04-24T21:49:02Z",
    "scopes": [
      "admin:business",
      "admin:gpg_key",
      "admin:org",
      "admin:org_hook",
      "admin:pre_receive_hook",
      "admin:public_key",
      "admin:repo_hook",
      "delete_repo",
      "gist",
      "notifications",
      "repo",
      "user",
      "write:discussion"
    ],
    "fingerprint": null
  }
]

Delete a personal access token

Deletes a personal access token. Returns a 403 - Forbidden status when a personal access token is in use. For example, if you access this endpoint with the same personal access token that you are trying to delete, you will receive this error.

delete /admin/tokens/{token_id}

Parameters

Name Type In Description
accept string header

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

token_id integer path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/tokens/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/tokens/{token_id}', {
  token_id: 42
})

Response

Status: 204 No Content

Create a user

If an external authentication mechanism is used, the login name should match the login name in the external system. If you are using LDAP authentication, you should also update the LDAP mapping for the user.

The login name will be normalized to only contain alphanumeric characters or single hyphens. For example, if you send "octo_cat" as the login, a user named "octo-cat" will be created.

If the login name or email address is already associated with an account, the server will return a 422 response.

post /admin/users

Parameters

Name Type In Description
accept string header

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

login string body

Required. The user's username.

email string body

Required for built-in authentication. The user's email address. This parameter can be omitted when using CAS, LDAP, or SAML. For details on built-in and centrally-managed authentication, see the GitHub authentication guide.

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users \
  -d '{"login":"login"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/users', {
  login: 'login'
})

Default response

Status: 201 Created
{
  "login": "octocat",
  "id": 1,
  "node_id": "MDQ6VXNlcjE=",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "gravatar_id": "",
  "url": "https://api.github.com/users/octocat",
  "html_url": "https://github.com/octocat",
  "followers_url": "https://api.github.com/users/octocat/followers",
  "following_url": "https://api.github.com/users/octocat/following{/other_user}",
  "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
  "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
  "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
  "organizations_url": "https://api.github.com/users/octocat/orgs",
  "repos_url": "https://api.github.com/users/octocat/repos",
  "events_url": "https://api.github.com/users/octocat/events{/privacy}",
  "received_events_url": "https://api.github.com/users/octocat/received_events",
  "type": "User",
  "site_admin": false
}

patch /admin/users/{username}

Parameters

Name Type In Description
accept string header

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

username string path
login string body

Required. The user's new username.

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users/USERNAME \
  -d '{"login":"login"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/users/{username}', {
  username: 'username',
  login: 'login'
})

Response

Status: 202 Accepted
{
  "message": "Job queued to rename user. It may take a few minutes to complete.",
  "url": "https://api.github.com/user/1"
}

Delete a user

Deleting a user will delete all their repositories, gists, applications, and personal settings. Suspending a user is often a better option.

You can delete any user account except your own.

delete /admin/users/{username}

Parameters

Name Type In Description
accept string header

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

username string path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/users/{username}', {
  username: 'username'
})

Response

Status: 204 No Content

post /admin/users/{username}/authorizations

Parameters

Name Type In Description
accept string header

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

username string path
scopes array of strings body

A list of scopes.

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users/USERNAME/authorizations \
  -d '{"scopes":["scopes"]}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/users/{username}/authorizations', {
  username: 'username',
  scopes: [
    'scopes'
  ]
})

Default response

Status: 201 Created
{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abcdefgh12345678",
  "token_last_eight": "12345678",
  "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "fingerprint": "jklmnop12345678"
}

delete /admin/users/{username}/authorizations

Parameters

Name Type In Description
accept string header

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

username string path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users/USERNAME/authorizations
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/users/{username}/authorizations', {
  username: 'username'
})

Response

Status: 204 No Content

Promote a user to be a site administrator

Note that you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP verbs."

put /users/{username}/site_admin

Parameters

Name Type In Description
accept string header

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

username string path

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/users/USERNAME/site_admin
JavaScript (@octokit/core.js)
await octokit.request('PUT /users/{username}/site_admin', {
  username: 'username'
})

Response

Status: 204 No Content

Demote a site administrator

You can demote any user account except your own.

delete /users/{username}/site_admin

Parameters

Name Type In Description
accept string header

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

username string path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/users/USERNAME/site_admin
JavaScript (@octokit/core.js)
await octokit.request('DELETE /users/{username}/site_admin', {
  username: 'username'
})

Response

Status: 204 No Content

Suspend a user

If your GitHub instance uses LDAP Sync with Active Directory LDAP servers, Active Directory LDAP-authenticated users cannot be suspended through this API. If you attempt to suspend an Active Directory LDAP-authenticated user through this API, it will return a 403 response.

You can suspend any user account except your own.

Note that, if you choose not to pass any parameters, you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP verbs."

put /users/{username}/suspended

Parameters

Name Type In Description
accept string header

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

username string path
reason string body

The reason the user is being suspended. This message will be logged in the audit log. If you don't provide a reason, it will default to "Suspended via API by SITE_ADMINISTRATOR", where SITE_ADMINISTRATOR is the person who performed the action.

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/users/USERNAME/suspended \
  -d '{"reason":"reason"}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /users/{username}/suspended', {
  username: 'username',
  reason: 'reason'
})

Response

Status: 204 No Content

Unsuspend a user

If your GitHub instance uses LDAP Sync with Active Directory LDAP servers, this API is disabled and will return a 403 response. Active Directory LDAP-authenticated users cannot be unsuspended using the API.

delete /users/{username}/suspended

Parameters

Name Type In Description
accept string header

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

username string path
reason string body

The reason the user is being unsuspended. This message will be logged in the audit log. If you don't provide a reason, it will default to "Unsuspended via API by SITE_ADMINISTRATOR", where SITE_ADMINISTRATOR is the person who performed the action.

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/users/USERNAME/suspended \
  -d '{"reason":"reason"}'
JavaScript (@octokit/core.js)
await octokit.request('DELETE /users/{username}/suspended', {
  username: 'username',
  reason: 'reason'
})

Response

Status: 204 No Content