Enterprise Administration

Download Spec

Enterprise Administration

List global webhooks
get /admin/hooks

per_page

int

The number of results per page (max 100).

Default
30

page

int

Page number of the results to fetch.

Default
1

Response

ExamplesSchema

Response

[
  {
    "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"
  }
]

Create a global webhook
post /admin/hooks

name

string

required

Must be passed as "web".

config

object (config)

required

Key/value pairs to provide settings for this webhook.

events

array[string]

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

active

boolean

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

Default
true

Request

{
  "name": "web",
  "events": [
    "organization",
    "user"
  ],
  "config": {
    "url": "https://example.com/webhook",
    "content_type": "json",
    "secret": "secret"
  }
}

Response

ExamplesSchema

Response

{
  "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"
}

Get a global webhook
get /admin/hooks/{hook_id}

hook_id

int

required

The unique identifier of the hook.

Response

ExamplesSchema

Response

{
  "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"
}

Delete a global webhook
delete /admin/hooks/{hook_id}

hook_id

int

required

The unique identifier of the hook.

Response

ExamplesSchema

Response

Empty response

Update a global webhook
patch /admin/hooks/{hook_id}

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

config

object (config)

Key/value pairs to provide settings for this webhook.

events

array[string]

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

active

boolean

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

Default
true

Request

{
  "events": [
    "organization"
  ],
  "config": {
    "url": "https://example.com/webhook"
  }
}

Response

ExamplesSchema

Response

{
  "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"
}

Ping a global webhook
post /admin/hooks/{hook_id}/pings

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

hook_id

int

required

The unique identifier of the hook.

Response

ExamplesSchema

Response

Empty response

List public keys
get /admin/keys

per_page

int

The number of results per page (max 100).

Default
30

page

int

Page number of the results to fetch.

Default
1

direction

string

The direction to sort the results by.

Default
"desc"
Enum
  • asc
  • desc

sort

string

Default
"created"
Enum
  • created
  • updated
  • accessed

since

string

Only show public keys accessed after the given time.

Response

ExamplesSchema

Response

[
  {
    "key": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234",
    "id": 2,
    "url": "https://api.github.com/user/keys/2",
    "title": "ssh-rsa AAAAB3NzaC1yc2EAAA",
    "created_at": "2020-06-11T21:31:57Z",
    "verified": false,
    "read_only": false,
    "last_used": "2020-06-11T22:31:57Z",
    "user_id": 1,
    "repository_id": 2
  },
  {
    "key": "9Og8iYjAyymI9LvABpJerYrMxURPc8r+dB7TJyvv1234",
    "id": 3,
    "url": "https://api.github.com/user/keys/2",
    "title": "ssh-rsa AAAAB3NzaC1yc2EAAA",
    "created_at": "2020-06-11T21:31:57Z",
    "verified": false,
    "read_only": false,
    "last_used": "2020-06-11T22:31:57Z",
    "user_id": 1,
    "repository_id": 2
  }
]

Delete a public key
delete /admin/keys/{key_ids}

key_ids

string

required

The unique identifier of the key.

Response

ExamplesSchema

Response

Empty response

Update LDAP mapping for a team
patch /admin/ldap/teams/{team_id}/mapping

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.

ldap_dn

string

required

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

Request

{
  "ldap_dn": "cn=Enterprise Ops,ou=teams,dc=github,dc=com"
}

Response

ExamplesSchema

Response

{
  "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",
  "notification_setting": "notifications_enabled",
  "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
post /admin/ldap/teams/{team_id}/sync

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.

team_id

int

required

The unique identifier of the team.

Response

ExamplesSchema

Response

{
  "status": "queued"
}

Update LDAP mapping for a user
patch /admin/ldap/users/{username}/mapping

ldap_dn

string

required

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

Request

{
  "ldap_dn": "uid=asdf,ou=users,dc=github,dc=com"
}

Response

ExamplesSchema

Response

{
  "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,
  "name": "monalisa octocat",
  "company": "GitHub",
  "blog": "https://github.com/blog",
  "location": "San Francisco",
  "email": "octocat@github.com",
  "hireable": false,
  "bio": "There once was...",
  "twitter_username": "monatheoctocat",
  "public_repos": 2,
  "public_gists": 1,
  "followers": 20,
  "following": 0,
  "created_at": "2008-01-14T04:33:35Z",
  "updated_at": "2008-01-14T04:33:35Z",
  "private_gists": 81,
  "total_private_repos": 100,
  "owned_private_repos": 100,
  "disk_usage": 10000,
  "collaborators": 8,
  "two_factor_authentication": true,
  "plan": {
    "name": "Medium",
    "space": 400,
    "private_repos": 20,
    "collaborators": 0
  }
}

Sync LDAP mapping for a user
post /admin/ldap/users/{username}/sync

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.

username

string

required

The handle for the GitHub user account.

Response

ExamplesSchema

Response

{
  "status": "queued"
}

Create an organization
post /admin/organizations

login

string

required

The organization's username.

admin

string

required

The login of the user who will manage this organization.

profile_name

string

The organization's display name.

Request

{
  "login": "github",
  "profile_name": "GitHub, Inc.",
  "admin": "monalisaoctocat"
}

Response

ExamplesSchema

Response

{
  "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"
}

Update an organization name
patch /admin/organizations/{org}

login

string

required

The organization's new name.

Request

{
  "login": "the-new-octocats"
}

Response

ExamplesSchema

Response

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

List pre-receive environments
get /admin/pre-receive-environments

per_page

int

The number of results per page (max 100).

Default
30

page

int

Page number of the results to fetch.

Default
1

direction

string

The direction to sort the results by.

Default
"desc"
Enum
  • asc
  • desc

sort

string

Default
"created"
Enum
  • created
  • updated
  • name

Response

ExamplesSchema

Response

[
  {
    "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
    }
  }
]

Create a pre-receive environment
post /admin/pre-receive-environments

name

string

required

The new pre-receive environment's name.

image_url

string

required

URL from which to download a tarball of this environment.

Request

{
  "name": "DevTools Hook Env",
  "image_url": "https://my_file_server/path/to/devtools_env.tar.gz"
}

Response

ExamplesSchema

Response

{
  "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
  }
}

Get a pre-receive environment
get /admin/pre-receive-environments/{pre_receive_environment_id}

pre_receive_environment_id

int

required

The unique identifier of the pre-receive environment.

Response

ExamplesSchema

Response

{
  "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
  }
}

Delete a pre-receive environment
delete /admin/pre-receive-environments/{pre_receive_environment_id}

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

pre_receive_environment_id

int

required

The unique identifier of the pre-receive environment.

Response

ExamplesSchema

Response

Empty response

Update a pre-receive environment
patch /admin/pre-receive-environments/{pre_receive_environment_id}

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

name

string

This pre-receive environment's new name.

image_url

string

URL from which to download a tarball of this environment.

Request

{
  "name": "DevTools Hook Env",
  "image_url": "https://my_file_server/path/to/devtools_env.tar.gz"
}

Response

ExamplesSchema

Response

{
  "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
  }
}

Start a pre-receive environment download
post /admin/pre-receive-environments/{pre_receive_environment_id}/downloads

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

pre_receive_environment_id

int

required

The unique identifier of the pre-receive environment.

Response

ExamplesSchema

Response

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

Get the download status for a pre-receive environment
get /admin/pre-receive-environments/{pre_receive_environment_id}/downloads/latest

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.

pre_receive_environment_id

int

required

The unique identifier of the pre-receive environment.