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.

Response

ExamplesSchema

Response

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

List pre-receive hooks

get /admin/pre-receive-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

direction

string

The direction to sort the results by.

Default: "desc"
Enum: asc
desc

sort

string

The property to sort the results by.

Default: "created"
Enum: created
updated
name

Response

ExamplesSchema

Response

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

Create a pre-receive hook

post /admin/pre-receive-hooks

name

string

required

The name of the hook.

script

string

required

The script that the hook runs.

script_repository

object (script_repository)

required

The GitHub repository where the script is kept.

environment

object (environment)

required

The pre-receive environment where the script is executed.

enforcement

string

The state of enforcement for this hook. default: disabled

allow_downstream_configuration

boolean

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

Request

{
  "name": "Check Commits",
  "script": "scripts/commit_check.sh",
  "enforcement": "disabled",
  "allow_downstream_configuration": false,
  "script_repository": {
    "full_name": "DevIT/hooks"
  },
  "environment": {
    "id": 2
  }
}

Response

ExamplesSchema

Response

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

Get a pre-receive hook

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

pre_receive_hook_id

int

required

The unique identifier of the pre-receive hook.

Response

ExamplesSchema

Response

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

Delete a pre-receive hook

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

pre_receive_hook_id

int

required

The unique identifier of the pre-receive hook.

Response

ExamplesSchema

Response

Empty response

Update a pre-receive hook

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

name

string

The name of the hook.

script

string

The script that the hook runs.

script_repository

object (script_repository)

The GitHub repository where the script is kept.

environment

object (environment)

The pre-receive environment where the script is executed.

enforcement

string

The state of enforcement for this hook.

allow_downstream_configuration

boolean

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

Request

{
  "name": "Check Commits",
  "environment": {
    "id": 1
  },
  "allow_downstream_configuration": true
}

Response

ExamplesSchema

Response

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

List personal access tokens

get /admin/tokens

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

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

[
  {
    "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": "ghp_16C7e42F292c6912E7710c838347Ae178B4a",
    "hashed_token": "23cffb2fab1b0a62747863eba88cb9327e561f2f7a0c8661c0d9b83146cb8d45",
    "token_last_eight": "Ae178B4a",
    "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

delete /admin/tokens/{token_id}

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.

token_id

int

required

The unique identifier of the token.

Response

ExamplesSchema

Response

Empty response

Create a user

post /admin/users

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.

login

string

required

The user's username.

email

string

Required for built-in authentication. The user's email address. This parameter can be omitted when using CAS, LDAP, or SAML. For more information, see "About authentication for your enterprise."

suspended

boolean

Whether to set the user as suspended when the user is created.

Default: false

Request

{
  "login": "monalisa",
  "email": "octocat@github.com"
}

Response

ExamplesSchema

Response

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

Delete a user

delete /admin/users/{username}

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.

username

string

required

The handle for the GitHub user account.

Response

ExamplesSchema

Response

Empty response

Update the username for a user

patch /admin/users/{username}

login

string

required

The user's new username.

Request

{
  "login": "thenewmonalisa"
}

Response

ExamplesSchema

Response

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

Create an impersonation OAuth token

post /admin/users/{username}/authorizations

scopes

array[string]

required

A list of scopes.

Request

{
  "scopes": [
    "public_repo"
  ]
}

Response

ExamplesSchema

Response when creating a new impersonation OAuth token

{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "token_last_eight": "Ae178B4a",
  "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",
  "expires_at": "2011-10-06T17:26:27Z",
  "fingerprint": "jklmnop12345678"
}

Delete an impersonation OAuth token

delete /admin/users/{username}/authorizations

username

string

required

The handle for the GitHub user account.

Response

ExamplesSchema

Response

Empty response

get /enterprise/announcement

Gets the current message and expiration date of the global announcement banner in your enterprise.

Response

ExamplesSchema

Response

{
  "announcement": "Very **important** announcement about _something_.",
  "expires_at": "2021-01-01T00:00:00.000+00:00",
  "user_dismissible": false
}

delete /enterprise/announcement

Removes the global announcement banner in your enterprise.

Response

ExamplesSchema

Response

Empty response

patch /enterprise/announcement

Sets the message and expiration time for the global announcement banner in your enterprise.

announcement

string or null

required

The announcement text in GitHub Flavored Markdown. For more information about GitHub Flavored Markdown, see "Basic writing and formatting syntax."

Example: "Very **important** announcement about _something_."

expires_at

string or null

date-time

The time at which the announcement expires. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. To set an announcement that never expires, omit this parameter, set it to null, or set it to an empty string.

Example: "\"2021-01-01T00:00:00.000-07:00\""

Request

{
  "announcement": "Very **important** announcement about _something_.",
  "expires_at": "2021-01-01T00:00:00.000+00:00"
}

Response

ExamplesSchema

Response

{
  "announcement": "Very **important** announcement about _something_.",
  "expires_at": "2021-01-01T00:00:00.000+00:00",
  "user_dismissible": false
}

Get license information

get /enterprise/settings/license

Response

ExamplesSchema

Response

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

Get all statistics

get /enterprise/stats/all

Response

ExamplesSchema

Response

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

Get comment statistics

get /enterprise/stats/comments

Response

ExamplesSchema

Response

{
  "total_commit_comments": 5000,
  "total_gist_comments": 400,
  "total_issue_comments": 10900,
  "total_pull_request_comments": 9900
}

Get gist statistics

get /enterprise/stats/gists

Response

ExamplesSchema

Response

{
  "total_gists": 500,
  "private_gists": 30,
  "public_gists": 470
}

Get hooks statistics

get /enterprise/stats/hooks

Response

ExamplesSchema

Response

{
  "total_hooks": 50,
  "active_hooks": 47,
  "inactive_hooks": 3
}

Get issue statistics

get /enterprise/stats/issues

Response

ExamplesSchema

Response

{
  "total_issues": 5000,
  "open_issues": 300,
  "closed_issues": 4700
}

Get milestone statistics

get /enterprise/stats/milestones

Response

ExamplesSchema

Response

{
  "total_milestones": 90,
  "open_milestones": 10,
  "closed_milestones": 80
}

Get organization statistics

get /enterprise/stats/orgs

Response

ExamplesSchema

Response

{
  "total_orgs": 50,
  "disabled_orgs": 1,
  "total_teams": 70,
  "total_team_members": 700
}

Get pages statistics

get /enterprise/stats/pages

Response

ExamplesSchema

Response

{
  "total_pages": 20
}

Get pull request statistics

get /enterprise/stats/pulls

Response

ExamplesSchema

Response

{
  "total_pulls": 1200,
  "merged_pulls": 1100,
  "mergeable_pulls": 90,
  "unmergeable_pulls": 10
}

Get repository statistics

get /enterprise/stats/repos

Response

ExamplesSchema

Response

{
  "total_repos": 200,
  "root_repos": 1,
  "fork_repos": 10,
  "org_repos": 150,
  "total_pushes": 39000,
  "total_wikis": 5
}

Get users statistics

get /enterprise/stats/users

Response

ExamplesSchema

Response

{
  "total_users": 100,
  "admin_users": 3,
  "suspended_users": 1
}

Get GitHub Actions permissions for an enterprise

get /enterprises/{enterprise}/actions/permissions

Gets the GitHub Actions permissions policy for organizations and allowed actions in an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Response

ExamplesSchema

Response

{
  "enabled_organizations": "all",
  "allowed_actions": "selected",
  "selected_actions_url": "https://api.github.com/enterprises/2/actions/permissions/selected-actions"
}

Set GitHub Actions permissions for an enterprise

put /enterprises/{enterprise}/actions/permissions

Sets the GitHub Actions permissions policy for organizations and allowed actions in an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

enabled_organizations

string

required

The policy that controls the organizations in the enterprise that are allowed to run GitHub Actions.

Enum: all
none
selected

allowed_actions

string

The permissions policy that controls the actions that are allowed to run.

Enum: all
local_only
selected

Request

{
  "enabled_organizations": "all",
  "allowed_actions": "selected"
}

Response

ExamplesSchema

Response

Empty response

List selected organizations enabled for GitHub Actions in an enterprise

get /enterprises/{enterprise}/actions/permissions/organizations

Lists the organizations that are selected to have GitHub Actions enabled in an enterprise. To use this endpoint, the enterprise permission policy for enabled_organizations must be configured to selected. For more information, see "Set GitHub Actions permissions for an enterprise."

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

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

{
  "total_count": 1,
  "organizations": [
    {
      "login": "octocat",
      "id": 161335,
      "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
      "url": "https://api.github.com/orgs/octo-org",
      "repos_url": "https://api.github.com/orgs/octo-org/repos",
      "events_url": "https://api.github.com/orgs/octo-org/events",
      "hooks_url": "https://api.github.com/orgs/octo-org/hooks",
      "issues_url": "https://api.github.com/orgs/octo-org/issues",
      "members_url": "https://api.github.com/orgs/octo-org/members{/member}",
      "public_members_url": "https://api.github.com/orgs/octo-org/public_members{/member}",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "description": "A great organization"
    }
  ]
}

Set selected organizations enabled for GitHub Actions in an enterprise

put /enterprises/{enterprise}/actions/permissions/organizations

Replaces the list of selected organizations that are enabled for GitHub Actions in an enterprise. To use this endpoint, the enterprise permission policy for enabled_organizations must be configured to selected. For more information, see "Set GitHub Actions permissions for an enterprise."

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

selected_organization_ids

array[int]

required

List of organization IDs to enable for GitHub Actions.

Request

{
  "selected_organization_ids": [
    32,
    91
  ]
}

Response

ExamplesSchema

Response

Empty response

Enable a selected organization for GitHub Actions in an enterprise

put /enterprises/{enterprise}/actions/permissions/organizations/{org_id}

Adds an organization to the list of selected organizations that are enabled for GitHub Actions in an enterprise. To use this endpoint, the enterprise permission policy for enabled_organizations must be configured to selected. For more information, see "Set GitHub Actions permissions for an enterprise."

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

org_id

int

required

The unique identifier of the organization.

Response

ExamplesSchema

Response

Empty response

Disable a selected organization for GitHub Actions in an enterprise

delete /enterprises/{enterprise}/actions/permissions/organizations/{org_id}

Removes an organization from the list of selected organizations that are enabled for GitHub Actions in an enterprise. To use this endpoint, the enterprise permission policy for enabled_organizations must be configured to selected. For more information, see "Set GitHub Actions permissions for an enterprise."

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

org_id

int

required

The unique identifier of the organization.

Response

ExamplesSchema

Response

Empty response

Get allowed actions for an enterprise

get /enterprises/{enterprise}/actions/permissions/selected-actions

Gets the selected actions that are allowed in an enterprise. To use this endpoint, the enterprise permission policy for allowed_actions must be configured to selected. For more information, see "Set GitHub Actions permissions for an enterprise."

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Response

ExamplesSchema

Response

{
  "github_owned_allowed": true,
  "verified_allowed": false,
  "patterns_allowed": [
    "monalisa/octocat@*",
    "docker/*"
  ]
}

Set allowed actions for an enterprise

put /enterprises/{enterprise}/actions/permissions/selected-actions

Sets the actions that are allowed in an enterprise. To use this endpoint, the enterprise permission policy for allowed_actions must be configured to selected. For more information, see "Set GitHub Actions permissions for an enterprise."

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

github_owned_allowed

boolean

required

Whether GitHub-owned actions are allowed. For example, this includes the actions in the actions organization.

patterns_allowed

array[string]

required

Specifies a list of string-matching patterns to allow specific action(s). Wildcards, tags, and SHAs are allowed. For example, monalisa/octocat@*, monalisa/octocat@v2, monalisa/*.

Request

{
  "github_owned_allowed": true,
  "verified_allowed": false,
  "patterns_allowed": [
    "monalisa/octocat@*",
    "docker/*"
  ]
}

Response

ExamplesSchema

Response

Empty response

List self-hosted runner groups for an enterprise

get /enterprises/{enterprise}/actions/runner-groups

Lists all self-hosted runner groups for an enterprise.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

per_page

int

The number of results per page (max 100).

Default: 30

page

int

Page number of the results to fetch.

Default: 1

visible_to_organization

string

Only return runner groups that are allowed to be used by this organization.

Response

ExamplesSchema

Response

{
  "total_count": 3,
  "runner_groups": [
    {
      "id": 1,
      "name": "Default",
      "visibility": "all",
      "default": true,
      "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/1/runners",
      "allows_public_repositories": false,
      "restricted_to_workflows": false,
      "selected_workflows": [],
      "workflow_restrictions_read_only": false
    },
    {
      "id": 2,
      "name": "octo-runner-group",
      "visibility": "selected",
      "default": false,
      "selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/2/organizations",
      "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/2/runners",
      "allows_public_repositories": true,
      "restricted_to_workflows": true,
      "selected_workflows": [
        "octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
      ],
      "workflow_restrictions_read_only": false
    },
    {
      "id": 3,
      "name": "expensive-hardware",
      "visibility": "private",
      "default": false,
      "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/3/runners",
      "allows_public_repositories": true,
      "restricted_to_workflows": false,
      "selected_workflows": [
        "octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
      ],
      "workflow_restrictions_read_only": false
    }
  ]
}

Create a self-hosted runner group for an enterprise

post /enterprises/{enterprise}/actions/runner-groups

Creates a new self-hosted runner group for an enterprise.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

name

string

required

Name of the runner group.

visibility

string

Visibility of a runner group. You can select all organizations or select individual organization.

Enum: selected
all

selected_organization_ids

array[int]

List of organization IDs that can access the runner group.

runners

array[int]

List of runner IDs to add to the runner group.

allows_public_repositories

boolean

Whether the runner group can be used by public repositories.

Default: false

restricted_to_workflows

boolean

If true, the runner group will be restricted to running only the workflows specified in the selected_workflows array.

Default: false

selected_workflows

array[string]

List of workflows the runner group should be allowed to run. This setting will be ignored unless restricted_to_workflows is set to true.

Request

{
  "name": "Expensive hardware runners",
  "visibility": "selected",
  "selected_organization_ids": [
    32,
    91
  ],
  "runners": [
    9,
    2
  ]
}

Response

ExamplesSchema

Response

{
  "id": 2,
  "name": "octo-runner-group",
  "visibility": "selected",
  "default": false,
  "selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
  "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners",
  "allows_public_repositories": false,
  "restricted_to_workflows": true,
  "selected_workflows": [
    "octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
  ],
  "workflow_restrictions_read_only": false
}

Get a self-hosted runner group for an enterprise

get /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}

Gets a specific self-hosted runner group for an enterprise.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id

int

required

Unique identifier of the self-hosted runner group.

Response

ExamplesSchema

Response

{
  "id": 2,
  "name": "octo-runner-group",
  "visibility": "selected",
  "default": false,
  "selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
  "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners",
  "allows_public_repositories": false,
  "restricted_to_workflows": true,
  "selected_workflows": [
    "octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
  ],
  "workflow_restrictions_read_only": false
}

Delete a self-hosted runner group from an enterprise

delete /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}

Deletes a self-hosted runner group for an enterprise.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id

int

required

Unique identifier of the self-hosted runner group.

Response

ExamplesSchema

Response

Empty response

Update a self-hosted runner group for an enterprise

patch /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}

Updates the name and visibility of a self-hosted runner group in an enterprise.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

name

string

Name of the runner group.

visibility

string

Visibility of a runner group. You can select all organizations or select individual organizations.

Default: "all"
Enum: selected
all

allows_public_repositories

boolean

Whether the runner group can be used by public repositories.

Default: false

restricted_to_workflows

boolean

If true, the runner group will be restricted to running only the workflows specified in the selected_workflows array.

Default: false

selected_workflows

array[string]

List of workflows the runner group should be allowed to run. This setting will be ignored unless restricted_to_workflows is set to true.

Request

{
  "name": "Expensive hardware runners",
  "visibility": "selected"
}

Response

ExamplesSchema

Response

{
  "id": 2,
  "name": "Expensive hardware runners",
  "visibility": "selected",
  "default": false,
  "selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
  "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners",
  "allows_public_repositories": true,
  "restricted_to_workflows": false,
  "selected_workflows": [
    "octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
  ],
  "workflow_restrictions_read_only": false
}

List organization access to a self-hosted runner group in an enterprise

get /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations

Lists the organizations with access to a self-hosted runner group.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

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

{
  "total_count": 1,
  "organizations": [
    {
      "login": "octocat",
      "id": 161335,
      "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
      "url": "https://api.github.com/orgs/octo-org",
      "repos_url": "https://api.github.com/orgs/octo-org/repos",
      "events_url": "https://api.github.com/orgs/octo-org/events",
      "hooks_url": "https://api.github.com/orgs/octo-org/hooks",
      "issues_url": "https://api.github.com/orgs/octo-org/issues",
      "members_url": "https://api.github.com/orgs/octo-org/members{/member}",
      "public_members_url": "https://api.github.com/orgs/octo-org/public_members{/member}",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "description": "A great organization"
    }
  ]
}

Set organization access for a self-hosted runner group in an enterprise

put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations

Replaces the list of organizations that have access to a self-hosted runner configured in an enterprise.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

selected_organization_ids

array[int]

required

List of organization IDs that can access the runner group.

Request

{
  "selected_organization_ids": [
    32,
    91
  ]
}

Response

ExamplesSchema

Response

Empty response

Add organization access to a self-hosted runner group in an enterprise

put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations/{org_id}

Adds an organization to the list of selected organizations that can access a self-hosted runner group. The runner group must have visibility set to selected. For more information, see "Create a self-hosted runner group for an enterprise."

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id

int

required

Unique identifier of the self-hosted runner group.

org_id

int

required

The unique identifier of the organization.

Response

ExamplesSchema

Response

Empty response

Remove organization access to a self-hosted runner group in an enterprise

delete /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations/{org_id}

Removes an organization from the list of selected organizations that can access a self-hosted runner group. The runner group must have visibility set to selected. For more information, see "Create a self-hosted runner group for an enterprise."

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id

int

required

Unique identifier of the self-hosted runner group.

org_id

int

required

The unique identifier of the organization.

Response

ExamplesSchema

Response

Empty response

List self-hosted runners in a group for an enterprise

get /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners

Lists the self-hosted runners that are in a specific enterprise group.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

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

{
  "total_count": 2,
  "runners": [
    {
      "id": 23,
      "name": "linux_runner",
      "os": "linux",
      "status": "online",
      "busy": true,
      "labels": [
        {
          "id": 5,
          "name": "self-hosted",
          "type": "read-only"
        },
        {
          "id": 7,
          "name": "X64",
          "type": "read-only"
        },
        {
          "id": 11,
          "name": "Linux",
          "type": "read-only"
        }
      ]
    },
    {
      "id": 24,
      "name": "mac_runner",
      "os": "macos",
      "status": "offline",
      "busy": false,
      "labels": [
        {
          "id": 5,
          "name": "self-hosted",
          "type": "read-only"
        },
        {
          "id": 7,
          "name": "X64",
          "type": "read-only"
        },
        {
          "id": 20,
          "name": "macOS",
          "type": "read-only"
        },
        {
          "id": 21,
          "name": "no-gpu",
          "type": "custom"
        }
      ]
    }
  ]
}

Set self-hosted runners in a group for an enterprise

put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners

Replaces the list of self-hosted runners that are part of an enterprise runner group.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

runners

array[int]

required

List of runner IDs to add to the runner group.

Request

{
  "runners": [
    9,
    2
  ]
}

Response

ExamplesSchema

Response

Empty response

Add a self-hosted runner to a group for an enterprise

put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}

Adds a self-hosted runner to a runner group configured in an enterprise.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id

int

required

Unique identifier of the self-hosted runner group.

runner_id

int

required

Unique identifier of the self-hosted runner.

Response

ExamplesSchema

Response

Empty response

Remove a self-hosted runner from a group for an enterprise

delete /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}

Removes a self-hosted runner from a group configured in an enterprise. The runner is then returned to the default group.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id

int

required

Unique identifier of the self-hosted runner group.

runner_id

int

required

Unique identifier of the self-hosted runner.

Response

ExamplesSchema

Response

Empty response

List self-hosted runners for an enterprise

get /enterprises/{enterprise}/actions/runners

Lists all self-hosted runners configured for an enterprise.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

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

{
  "total_count": 2,
  "runners": [
    {
      "id": 23,
      "name": "linux_runner",
      "os": "linux",
      "status": "online",
      "busy": true,
      "labels": [
        {
          "id": 5,
          "name": "self-hosted",
          "type": "read-only"
        },
        {
          "id": 7,
          "name": "X64",
          "type": "read-only"
        },
        {
          "id": 11,
          "name": "Linux",
          "type": "read-only"
        }
      ]
    },
    {
      "id": 24,
      "name": "mac_runner",
      "os": "macos",
      "status": "offline",
      "busy": false,
      "labels": [
        {
          "id": 5,
          "name": "self-hosted",
          "type": "read-only"
        },
        {
          "id": 7,
          "name": "X64",
          "type": "read-only"
        },
        {
          "id": 20,
          "name": "macOS",
          "type": "read-only"
        },
        {
          "id": 21,
          "name": "no-gpu",
          "type": "custom"
        }
      ]
    }
  ]
}

List runner applications for an enterprise

get /enterprises/{enterprise}/actions/runners/downloads

Lists binaries for the runner application that you can download and run.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Response

ExamplesSchema

Response

[
  {
    "os": "osx",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.277.1/actions-runner-osx-x64-2.277.1.tar.gz",
    "filename": "actions-runner-osx-x64-2.277.1.tar.gz",
    "temp_download_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkJmSjdCUXpLdXhjWDc4WnJ5NUxnUW53ZFRrMCJ9.eyJuYW1laWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJzY3AiOiJBY3Rpb25zUnVudGltZS5QYWNrYWdlRG93bmxvYWQiLCJJZGVudGl0eVR5cGVDbGFpbSI6IlN5c3RlbTpTZXJ2aWNlSWRlbnRpdHkiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9zaWQiOiJERERERERERC1ERERELUREREQtRERERC1EREREREREREREREQiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3ByaW1hcnlzaWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJhdWkiOiIwZTZkODAxYi02NzVlLTQ1YzAtOWM4NC1jYTkzNjdlZjc1NjciLCJzaWQiOiI4ZTE5MDliZC1kYzU1LTQ2MWYtOTk2Mi1hZTI0OTEzNzU4OWIiLCJpc3MiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJhdWQiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJuYmYiOjE2MTc5MDQxNzUsImV4cCI6MTYxNzkwODM3NX0.YNsRXL9pBuIfLVndnyVQOpru77Br8hgYIX7LPsOaMfKk4K88YG89a2VIXUWPyHRiOaC-4J0lIPei8ujezEtnMfNZCwHdWq0Niiy-2-ywcfGPmcz-RHz_ZglkPFbzKaiZWJcFKCGHCP0Ta3kdXumJQqiVJEIyppxIY-caR_Wsw2L4BZHOefJq-odsJ0guPgm9fVuU9FxVRkucho1UH_bzt0tAMl1gEWOLBLZ88U9LKCzHWaxheFeBV4DTt1lAcSm213gKP1eMbgAGn5heWhR4RMRBzZc2HO3Lf1syu4E8fW8a-esRAxEYPfqPHwN9LNj2jaU3D3nPwa8lHQLLtA1PNA",
    "sha256_checksum": "f1fa173889dc9036cd529417e652e1729e5a3f4d35ec0151806d7480fda6b89b"
  },
  {
    "os": "linux",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.277.1/actions-runner-linux-x64-2.277.1.tar.gz",
    "filename": "actions-runner-linux-x64-2.277.1.tar.gz",
    "temp_download_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkJmSjdCUXpLdXhjWDc4WnJ5NUxnUW53ZFRrMCJ9.eyJuYW1laWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJzY3AiOiJBY3Rpb25zUnVudGltZS5QYWNrYWdlRG93bmxvYWQiLCJJZGVudGl0eVR5cGVDbGFpbSI6IlN5c3RlbTpTZXJ2aWNlSWRlbnRpdHkiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9zaWQiOiJERERERERERC1ERERELUREREQtRERERC1EREREREREREREREQiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3ByaW1hcnlzaWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJhdWkiOiIwZTZkODAxYi02NzVlLTQ1YzAtOWM4NC1jYTkzNjdlZjc1NjciLCJzaWQiOiI4ZTE5MDliZC1kYzU1LTQ2MWYtOTk2Mi1hZTI0OTEzNzU4OWIiLCJpc3MiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJhdWQiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJuYmYiOjE2MTc5MDQxNzUsImV4cCI6MTYxNzkwODM3NX0.YNsRXL9pBuIfLVndnyVQOpru77Br8hgYIX7LPsOaMfKk4K88YG89a2VIXUWPyHRiOaC-4J0lIPei8ujezEtnMfNZCwHdWq0Niiy-2-ywcfGPmcz-RHz_ZglkPFbzKaiZWJcFKCGHCP0Ta3kdXumJQqiVJEIyppxIY-caR_Wsw2L4BZHOefJq-odsJ0guPgm9fVuU9FxVRkucho1UH_bzt0tAMl1gEWOLBLZ88U9LKCzHWaxheFeBV4DTt1lAcSm213gKP1eMbgAGn5heWhR4RMRBzZc2HO3Lf1syu4E8fW8a-esRAxEYPfqPHwN9LNj2jaU3D3nPwa8lHQLLtA1PNA",
    "sha256_checksum": "02d710fc9e0008e641274bb7da7fde61f7c9aa1cbb541a2990d3450cc88f4e98"
  },
  {
    "os": "linux",
    "architecture": "arm",
    "download_url": "https://github.com/actions/runner/releases/download/v2.277.1/actions-runner-linux-arm-2.277.1.tar.gz",
    "filename": "actions-runner-linux-arm-2.277.1.tar.gz",
    "temp_download_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkJmSjdCUXpLdXhjWDc4WnJ5NUxnUW53ZFRrMCJ9.eyJuYW1laWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJzY3AiOiJBY3Rpb25zUnVudGltZS5QYWNrYWdlRG93bmxvYWQiLCJJZGVudGl0eVR5cGVDbGFpbSI6IlN5c3RlbTpTZXJ2aWNlSWRlbnRpdHkiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9zaWQiOiJERERERERERC1ERERELUREREQtRERERC1EREREREREREREREQiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3ByaW1hcnlzaWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJhdWkiOiIyYTEzZDRmZC01ZDhkLTRjNzgtYjg2MS0zYTMxZGQ3MmYzNjQiLCJzaWQiOiI0MzZiNTg3YS04ODMyLTRiMTMtOWM2Ny05OWRkMjA2ZTQzNmMiLCJpc3MiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJhdWQiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJuYmYiOjE2MTc5MzE1NzEsImV4cCI6MTYxNzkzNTc3MX0.PMhU7-MOnZRDj5k5a4ieeFlQCmKPl2pQvpVRhGZq-9ByKF5s9G0rsnGBxDcolTYlbvEAmSSkeAEwF486F7P0kMVEb-GI14WbErqqMSyaPL81c3W7UHxMJLaSBnDs9ftHMv_IkJmRzaROS8q1ObzUW-ErlltxCdj2zF_5ruK9G2RR566AOAtiA3AHV6k7-FCY5--sDYJN_YXPgpwI0fPN1TM92fdPm93hJnoXuCJNpBYp1vl5W4gwGtU_Pa07ESdqqFN1YJJHUloedNhiIOczGfGVSapRc8vyGm9P_VCM_yKD8JI-MkOXl8JI5fCfhmjmKsw-vSAh9NW67RGvmehmpw",
    "sha256_checksum": "2f2bda21e2fd8fed6938b33182a293f6b1f74e4c5d09acd6d9a0fe3f979f5c85"
  },
  {
    "os": "win",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.277.1/actions-runner-win-x64-2.277.1.zip",
    "filename": "actions-runner-win-x64-2.277.1.zip",
    "temp_download_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkJmSjdCUXpLdXhjWDc4WnJ5NUxnUW53ZFRrMCJ9.eyJuYW1laWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJzY3AiOiJBY3Rpb25zUnVudGltZS5QYWNrYWdlRG93bmxvYWQiLCJJZGVudGl0eVR5cGVDbGFpbSI6IlN5c3RlbTpTZXJ2aWNlSWRlbnRpdHkiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9zaWQiOiJERERERERERC1ERERELUREREQtRERERC1EREREREREREREREQiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3ByaW1hcnlzaWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJhdWkiOiIwZTZkODAxYi02NzVlLTQ1YzAtOWM4NC1jYTkzNjdlZjc1NjciLCJzaWQiOiI4ZTE5MDliZC1kYzU1LTQ2MWYtOTk2Mi1hZTI0OTEzNzU4OWIiLCJpc3MiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJhdWQiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJuYmYiOjE2MTc5MDQxNzUsImV4cCI6MTYxNzkwODM3NX0.YNsRXL9pBuIfLVndnyVQOpru77Br8hgYIX7LPsOaMfKk4K88YG89a2VIXUWPyHRiOaC-4J0lIPei8ujezEtnMfNZCwHdWq0Niiy-2-ywcfGPmcz-RHz_ZglkPFbzKaiZWJcFKCGHCP0Ta3kdXumJQqiVJEIyppxIY-caR_Wsw2L4BZHOefJq-odsJ0guPgm9fVuU9FxVRkucho1UH_bzt0tAMl1gEWOLBLZ88U9LKCzHWaxheFeBV4DTt1lAcSm213gKP1eMbgAGn5heWhR4RMRBzZc2HO3Lf1syu4E8fW8a-esRAxEYPfqPHwN9LNj2jaU3D3nPwa8lHQLLtA1PNA",
    "sha256_checksum": "7215c75a462eeb6a839fa8ed298d79f620617d44d47d37c583114fc3f3b27b30"
  },
  {
    "os": "linux",
    "architecture": "arm64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.277.1/actions-runner-linux-arm64-2.277.1.tar.gz",
    "filename": "actions-runner-linux-arm64-2.277.1.tar.gz",
    "temp_download_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkJmSjdCUXpLdXhjWDc4WnJ5NUxnUW53ZFRrMCJ9.eyJuYW1laWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJzY3AiOiJBY3Rpb25zUnVudGltZS5QYWNrYWdlRG93bmxvYWQiLCJJZGVudGl0eVR5cGVDbGFpbSI6IlN5c3RlbTpTZXJ2aWNlSWRlbnRpdHkiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9zaWQiOiJERERERERERC1ERERELUREREQtRERERC1EREREREREREREREQiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3ByaW1hcnlzaWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJhdWkiOiIwZTZkODAxYi02NzVlLTQ1YzAtOWM4NC1jYTkzNjdlZjc1NjciLCJzaWQiOiI4ZTE5MDliZC1kYzU1LTQ2MWYtOTk2Mi1hZTI0OTEzNzU4OWIiLCJpc3MiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJhdWQiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJuYmYiOjE2MTc5MDQxNzUsImV4cCI6MTYxNzkwODM3NX0.YNsRXL9pBuIfLVndnyVQOpru77Br8hgYIX7LPsOaMfKk4K88YG89a2VIXUWPyHRiOaC-4J0lIPei8ujezEtnMfNZCwHdWq0Niiy-2-ywcfGPmcz-RHz_ZglkPFbzKaiZWJcFKCGHCP0Ta3kdXumJQqiVJEIyppxIY-caR_Wsw2L4BZHOefJq-odsJ0guPgm9fVuU9FxVRkucho1UH_bzt0tAMl1gEWOLBLZ88U9LKCzHWaxheFeBV4DTt1lAcSm213gKP1eMbgAGn5heWhR4RMRBzZc2HO3Lf1syu4E8fW8a-esRAxEYPfqPHwN9LNj2jaU3D3nPwa8lHQLLtA1PNA",
    "sha256_checksum": "a6aa6dd0ba217118ef2b4ea24e9e0a85b02b13c38052a5de0776d6ced3a79c64"
  }
]

Create a registration token for an enterprise

post /enterprises/{enterprise}/actions/runners/registration-token

Returns a token that you can pass to the config script. The token expires after one hour.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

Example using registration token

Configure your self-hosted runner, replacing TOKEN with the registration token provided by this endpoint.

./config.sh --url https://github.com/enterprises/octo-enterprise --token TOKEN

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Response

ExamplesSchema

Response

{
  "token": "LLBF3JGZDX3P5PMEXLND6TS6FCWO6",
  "expires_at": "2020-01-22T12:13:35.123-08:00"
}

Create a remove token for an enterprise

post /enterprises/{enterprise}/actions/runners/remove-token

Returns a token that you can pass to the config script to remove a self-hosted runner from an enterprise. The token expires after one hour.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

Example using remove token

To remove your self-hosted runner from an enterprise, replace TOKEN with the remove token provided by this endpoint.

./config.sh remove --token TOKEN

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Response

ExamplesSchema

Response

{
  "token": "AABF3JGZDX3P5PMEXLND6TS6FCWO6",
  "expires_at": "2020-01-29T12:13:35.123-08:00"
}

Get a self-hosted runner for an enterprise

get /enterprises/{enterprise}/actions/runners/{runner_id}

Gets a specific self-hosted runner configured in an enterprise.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_id

int

required

Unique identifier of the self-hosted runner.

Response

ExamplesSchema

Response

{
  "id": 23,
  "name": "MBP",
  "os": "macos",
  "status": "online",
  "busy": true,
  "labels": [
    {
      "id": 5,
      "name": "self-hosted",
      "type": "read-only"
    },
    {
      "id": 7,
      "name": "X64",
      "type": "read-only"
    },
    {
      "id": 20,
      "name": "macOS",
      "type": "read-only"
    },
    {
      "id": 21,
      "name": "no-gpu",
      "type": "custom"
    }
  ]
}

Delete a self-hosted runner from an enterprise

delete /enterprises/{enterprise}/actions/runners/{runner_id}

Forces the removal of a self-hosted runner from an enterprise. You can use this endpoint to completely remove the runner when the machine you were using no longer exists.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_id

int

required

Unique identifier of the self-hosted runner.

Response

ExamplesSchema

Response

Empty response

List labels for a self-hosted runner for an enterprise

get /enterprises/{enterprise}/actions/runners/{runner_id}/labels

Lists all labels for a self-hosted runner configured in an enterprise.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_id

int

required

Unique identifier of the self-hosted runner.

Response

ExamplesSchema

Response

{
  "total_count": 4,
  "labels": [
    {
      "id": 5,
      "name": "self-hosted",
      "type": "read-only"
    },
    {
      "id": 7,
      "name": "X64",
      "type": "read-only"
    },
    {
      "id": 20,
      "name": "macOS",
      "type": "read-only"
    },
    {
      "id": 21,
      "name": "no-gpu",
      "type": "custom"
    }
  ]
}

Add custom labels to a self-hosted runner for an enterprise

post /enterprises/{enterprise}/actions/runners/{runner_id}/labels

Add custom labels to a self-hosted runner configured in an enterprise.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

labels

array[string]

required

The names of the custom labels to add to the runner.

Request

{
  "labels": [
    "gpu",
    "accelerated"
  ]
}

Response

ExamplesSchema

Response

{
  "total_count": 4,
  "labels": [
    {
      "id": 5,
      "name": "self-hosted",
      "type": "read-only"
    },
    {
      "id": 7,
      "name": "X64",
      "type": "read-only"
    },
    {
      "id": 20,
      "name": "macOS",
      "type": "read-only"
    },
    {
      "id": 21,
      "name": "no-gpu",
      "type": "custom"
    }
  ]
}

Set custom labels for a self-hosted runner for an enterprise

put /enterprises/{enterprise}/actions/runners/{runner_id}/labels

Remove all previous custom labels and set the new custom labels for a specific self-hosted runner configured in an enterprise.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

labels

array[string]

required

The names of the custom labels to set for the runner. You can pass an empty array to remove all custom labels.

Request

{
  "labels": [
    "gpu",
    "accelerated"
  ]
}

Response

ExamplesSchema

Response

{
  "total_count": 4,
  "labels": [
    {
      "id": 5,
      "name": "self-hosted",
      "type": "read-only"
    },
    {
      "id": 7,
      "name": "X64",
      "type": "read-only"
    },
    {
      "id": 20,
      "name": "macOS",
      "type": "read-only"
    },
    {
      "id": 21,
      "name": "no-gpu",
      "type": "custom"
    }
  ]
}

Remove all custom labels from a self-hosted runner for an enterprise

delete /enterprises/{enterprise}/actions/runners/{runner_id}/labels

Remove all custom labels from a self-hosted runner configured in an enterprise. Returns the remaining read-only labels from the runner.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_id

int

required

Unique identifier of the self-hosted runner.

Response

ExamplesSchema

Response

{
  "total_count": 3,
  "labels": [
    {
      "id": 5,
      "name": "self-hosted",
      "type": "read-only"
    },
    {
      "id": 7,
      "name": "X64",
      "type": "read-only"
    },
    {
      "id": 20,
      "name": "macOS",
      "type": "read-only"
    }
  ]
}

Remove a custom label from a self-hosted runner for an enterprise

delete /enterprises/{enterprise}/actions/runners/{runner_id}/labels/{name}

Remove a custom label from a self-hosted runner configured in an enterprise. Returns the remaining labels from the runner.

This endpoint returns a 404 Not Found status if the custom label is not present on the runner.

You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_id

int

required

Unique identifier of the self-hosted runner.

name

string

required

The name of a self-hosted runner's custom label.

Response

ExamplesSchema

Response

{
  "total_count": 4,
  "labels": [
    {
      "id": 5,
      "name": "self-hosted",
      "type": "read-only"
    },
    {
      "id": 7,
      "name": "X64",
      "type": "read-only"
    },
    {
      "id": 20,
      "name": "macOS",
      "type": "read-only"
    },
    {
      "id": 21,
      "name": "no-gpu",
      "type": "custom"
    }
  ]
}

Get the audit log for an enterprise

get /enterprises/{enterprise}/audit-log

Gets the audit log for an enterprise. To use this endpoint, you must be an enterprise admin, and you must use an access token with the read:audit_log scope.

phrase

string

A search phrase. For more information, see Searching the audit log.

include

string

The event types to include:

web - returns web (non-Git) events.
git - returns Git events.
all - returns both web and Git events.

The default is web.

Enum: web
git
all

after

string

A cursor, as given in the Link header. If specified, the query only searches for events after this cursor.

before

string

A cursor, as given in the Link header. If specified, the query only searches for events before this cursor.

order

string

The order of audit log events. To list newest events first, specify desc. To list oldest events first, specify asc.

The default is desc.

Enum: desc
asc

page

int

Page number of the results to fetch.

Default: 1

per_page

int

The number of results per page (max 100).

Default: 30

Response

ExamplesSchema

Response

[
  {
    "actor_ip": "88.123.45.123",
    "from": "pull_requests#merge",
    "device_cookie": null,
    "actor": "mona-admin",
    "actor_id": 7,
    "repo": "octo-org/octo-repo",
    "repo_id": 17,
    "business": "github",
    "business_id": 1,
    "org": "octo-org",
    "org_id": 8,
    "action": "pull_request.merge",
    "@timestamp": 1635940599755,
    "created_at": 1635940599755,
    "operation_type": "modify",
    "actor_location": {
      "country_code": "GB",
      "country_name": "United Kingdom",
      "region": "ENG",
      "region_name": "England",
      "city": "Louth",
      "postal_code": "LN11",
      "location": {
        "lat": 53.4457,
        "lon": 0.141
      }
    },
    "data": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
      "method": "POST",
      "request_id": "e4dabc4d-ba16-4bca-1234-649be7ae1188",
      "server_id": "5d17aab5-fd9f-abcd-a820-16bed246441b",
      "request_category": "other",
      "controller_action": "merge",
      "url": "https://example.com/octo-org/octo-repo/pull/1/merge",
      "client_id": 322299977.1635936,
      "referrer": "https://example.com/octo-org/octo-repo/pull/1",
      "actor_session": 1,
      "pull_request_id": 1,
      "category_type": "Resource Management"
    }
  },
  {
    "actor_ip": "88.123.45.123",
    "from": "pull_request_review_events#create",
    "device_cookie": null,
    "actor": "mona-admin",
    "actor_id": 7,
    "business_id": 1,
    "org_id": 8,
    "action": "pull_request_review.submit",
    "@timestamp": 1635940593079,
    "created_at": 1635940593079,
    "operation_type": "modify",
    "actor_location": {
      "country_code": "GB",
      "country_name": "United Kingdom",
      "region": "ENG",
      "region_name": "England",
      "city": "Louth",
      "postal_code": "LN11",
      "location": {
        "lat": 53.4457,
        "lon": 0.141
      }
    },
    "data": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
      "method": "PUT",
      "request_id": "c0f63bb7-17b6-4796-940c-12345c5a581b",
      "server_id": "2abc1234-f651-43e3-9696-e942ad5f8c89",
      "request_category": "other",
      "controller_action": "create",
      "url": "https://example.com/octo-org/octo-repo/pull/1/reviews",
      "client_id": 322299977.1635936,
      "referrer": "https://example.com/octo-org/octo-repo/pull/1/files",
      "actor_session": 1,
      "spammy": false,
      "pull_request_id": 1,
      "body": null,
      "allowed": true,
      "id": 1,
      "state": 40,
      "issue_id": 1,
      "review_id": 1,
      "category_type": "Resource Management"
    }
  },
  {
    "actor_ip": "88.123.45.123",
    "from": "pull_requests#create",
    "device_cookie": null,
    "actor": "mona",
    "actor_id": 9,
    "user_id": 9,
    "repo": "octo-org/octo-repo",
    "repo_id": 17,
    "business": "github",
    "business_id": 1,
    "org": "octo-org",
    "org_id": 8,
    "action": "pull_request.create",
    "@timestamp": 1635940554161,
    "created_at": 1635940554161,
    "operation_type": "create",
    "actor_location": {
      "country_code": "GB",
      "country_name": "United Kingdom",
      "region": "ENG",
      "region_name": "England",
      "city": "Louth",
      "postal_code": "LN11",
      "location": {
        "lat": 53.4457,
        "lon": 0.141
      }
    },
    "data": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
      "method": "POST",
      "request_id": "2773abeb-477f-4ebf-a017-f8e8a206c305",
      "server_id": "796e3115-4ce8-4606-8fd0-99ea57a2e12b",
      "request_category": "other",
      "controller_action": "create",
      "url": "https://example.com/octo-org/octo-repo/pull/create?base=octo-org%3Amain&head=mona%3Apatch-1",
      "client_id": 386351111.163594,
      "referrer": "https://example.com/octo-org/octo-repo/compare/main...mona:patch-1",
      "actor_session": 2,
      "pull_request_id": 1,
      "category_type": "Resource Management"
    }
  }
]

Get code security and analysis features for an enterprise

get /enterprises/{enterprise}/code_security_and_analysis

Gets code security and analysis settings for the specified enterprise. To use this endpoint, you must be an administrator of the enterprise, and you must use an access token with the admin:enterprise scope.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Response

ExamplesSchema

Response

{
  "advanced_security_enabled_for_new_repositories": true,
  "dependabot_alerts_enabled_for_new_repositories": true,
  "secret_scanning_enabled_for_new_repositories": true,
  "secret_scanning_push_protection_enabled_for_new_repositories": true,
  "secret_scanning_push_protection_custom_link": "https://github.com/test-org/test-repo/blob/main/README.md"
}

Update code security and analysis features for an enterprise

patch /enterprises/{enterprise}/code_security_and_analysis

Updates the settings for advanced security, Dependabot alerts, secret scanning, and push protection for new repositories in an enterprise. To use this endpoint, you must be an administrator of the enterprise, and you must use an access token with the admin:enterprise scope.

advanced_security_enabled_for_new_repositories

boolean

Whether GitHub Advanced Security is automatically enabled for new repositories. For more information, see "About GitHub Advanced Security."

dependabot_alerts_enabled_for_new_repositories

boolean

Whether Dependabot alerts are automatically enabled for new repositories. For more information, see "About Dependabot alerts."

secret_scanning_enabled_for_new_repositories

boolean

Whether secret scanning is automatically enabled for new repositories. For more information, see "About secret scanning."

secret_scanning_push_protection_enabled_for_new_repositories

boolean

Whether secret scanning push protection is automatically enabled for new repositories. For more information, see "Protecting pushes with secret scanning."

secret_scanning_push_protection_custom_link

string or null

The URL that will be displayed to contributors who are blocked from pushing a secret. For more information, see "Protecting pushes with secret scanning." To disable this functionality, set this field to null.

Request

{
  "advanced_security_enabled_for_new_repositories": true,
  "dependabot_alerts_enabled_for_new_repositories": true,
  "secret_scanning_enabled_for_new_repositories": true,
  "secret_scanning_push_protection_enabled_for_new_repositories": true,
  "secret_scanning_push_protection_custom_link": "https://github.com/test-org/test-repo/blob/main/README.md"
}

Response

ExamplesSchema

Action started

Empty response

Enable or disable a security feature

post /enterprises/{enterprise}/{security_product}/{enablement}

Enables or disables the specified security feature for all repositories in an enterprise.

To use this endpoint, you must be an administrator of the enterprise, and you must use an access token with the admin:enterprise scope.

enterprise

string

required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

security_product

string

required

The security feature to enable or disable.

Enum: advanced_security
dependabot_alerts
secret_scanning
secret_scanning_push_protection

enablement

string

required

The action to take.

enable_all means to enable the specified security feature for all repositories in the enterprise. disable_all means to disable the specified security feature for all repositories in the enterprise.

Enum: enable_all
disable_all

Response

ExamplesSchema

Action started

Empty response

Get the status of services running on all replica nodes

get /manage/v1/replication/status

Gets the status of all services running on each replica node. This endpoint may take several seconds to reply.

Response

ExamplesSchema

Response

{
  "status": "OK",
  "nodes": [
    {
      "hostname": "ghe-local-primary",
      "status": "OK",
      "services": []
    },
    {
      "hostname": "ghe-local-replica",
      "status": "OK",
      "services": [
        {
          "status": "OK",
          "name": "redis",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "elasticsearch",
          "details": "cluster is in sync (0 shards initializing, 0 shards unassigned)"
        },
        {
          "status": "OK",
          "name": "git",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "pages",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "alambic",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "git-hooks",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "consul",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "mysql",
          "details": "replication is in sync"
        }
      ]
    }
  ]
}

Get all GHES release version for all nodes

get /manage/v1/version

Gets all of the currently installed GitHub Enterprise Server release version on all available nodes. For more information, see "GitHub Enterprise Server releases."

Response

ExamplesSchema

Response

[
  {
    "hostname": "ghe-local-primary",
    "version": {
      "version": "3.9.0",
      "platform": "azure",
      "build_id": "fc542058b5",
      "build_date": "2023-05-02"
    }
  }
]

List pre-receive hooks for an organization

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

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.

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

The sort order for the response collection.

Default: "created"
Enum: created
updated
name

Response

ExamplesSchema

Response

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

Get a pre-receive hook for an organization

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

org

string

required

The organization name. The name is not case sensitive.

pre_receive_hook_id

int

required

The unique identifier of the pre-receive hook.

Response

ExamplesSchema

Response

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

Remove pre-receive hook enforcement for an organization

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

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

org

string

required

The organization name. The name is not case sensitive.

pre_receive_hook_id

int

required

The unique identifier of the pre-receive hook.

Response

ExamplesSchema

Response

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

Update pre-receive hook enforcement for an organization

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

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

enforcement

string

The state of enforcement for the hook on this repository.

allow_downstream_configuration

boolean

Whether repositories can override enforcement.

Request

{
  "enforcement": "enabled",
  "allow_downstream_configuration": false
}

Response

ExamplesSchema

Response

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

List pre-receive hooks for a repository

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

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.

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": 42,
    "name": "Check Commits",
    "enforcement": "disabled",
    "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
  }
]

Get a pre-receive hook for a repository

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

owner

string

required

The account owner of the repository. The name is not case sensitive.

repo

string

required

The name of the repository. The name is not case sensitive.

pre_receive_hook_id

int

required

The unique identifier of the pre-receive hook.

Response

ExamplesSchema

Response

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

Remove pre-receive hook enforcement for a repository

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

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

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

owner

string

required

The account owner of the repository. The name is not case sensitive.

repo

string

required

The name of the repository. The name is not case sensitive.

pre_receive_hook_id

int

required

The unique identifier of the pre-receive hook.

Response

ExamplesSchema

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

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

Update pre-receive hook enforcement for a repository

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

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

enforcement

string

The state of enforcement for the hook on this repository.

Enum: enabled
disabled
testing

Request

{
  "enforcement": "enabled"
}

Response

ExamplesSchema

Response

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

List provisioned SCIM groups for an enterprise

get /scim/v2/Groups

Note: The SCIM API endpoints for enterprise accounts are currently in private beta and are subject to change.

Lists provisioned SCIM groups in an enterprise.

You can improve query search time by using the excludedAttributes query parameter with a value of members to exclude members from the response.

filter

string

If specified, only results that match the specified filter will be returned. Multiple filters are not supported. Possible filters are externalId, id, and displayName. For example, ?filter="externalId eq '9138790-10932-109120392-12321'".

excludedAttributes

string

Excludes the specified attribute from being returned in the results. Using this parameter can speed up response time.

Example: "members"

startIndex

int

int32

Used for pagination: the starting index of the first result to return when paginating through values.

Default: 1
Example: 1

count

int

int32

Used for pagination: the number of results to return per page.

Default: 30
Example: 1

Response

ExamplesSchema

Success, either groups were found or not found

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
      "id": "927fa2c08dcb4a7fae9e",
      "displayName": "Engineering",
      "members": [
        {
          "value": "879db59-3bdf-4490-ad68-ab880a2694745",
          "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745",
          "displayName": "User 1"
        },
        {
          "value": "0db508eb-91e2-46e4-809c-30dcbda0c685",
          "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685",
          "displayName": "User 2"
        }
      ],
      "meta": {
        "resourceType": "Group",
        "created": "2012-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z",
        "location": "https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e"
      }
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 20
}

Provision a SCIM enterprise group

post /scim/v2/Groups

Note: The SCIM API endpoints for enterprise accounts are currently in private beta and are subject to change.

Creates a SCIM group for an enterprise.

If members are included as part of the group provisioning payload, they will be created as external group members. It is up to a provider to store a mapping between the externalId and id of each user.

schemas

array[string]

required

The URIs that are used to indicate the namespaces of the SCIM schemas.

Example: [ "urn:ietf:params:scim:schemas:core:2.0:Group" ]

externalId

string

required

A unique identifier for the resource as defined by the provisioning client.

Example: "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159"

displayName

string

required

A human-readable name for a security group.

Example: "Engineering"

members

array[object]

required

The group members.

Request

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
  "displayName": "Engineering"
}

Response

ExamplesSchema

Group has been created

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc",
  "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
  "displayName": "Engineering",
  "members": [
    {
      "value": "879db59-3bdf-4490-ad68-ab880a2694745",
      "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745",
      "displayName": "User 1"
    },
    {
      "value": "0db508eb-91e2-46e4-809c-30dcbda0c685",
      "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685",
      "displayName": "User 2"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "created": "2012-03-27T19:59:26.000Z",
    "lastModified": "2018-03-27T19:59:26.000Z",
    "location": "https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e"
  }
}

Get SCIM provisioning information for an enterprise group

get /scim/v2/Groups/{scim_group_id}

Note: The SCIM API endpoints for enterprise accounts are currently in private beta and are subject to change.

Gets information about a SCIM group.

excludedAttributes

string

Excludes the specified attribute from being returned in the results. Using this parameter can speed up response time.

Example: "members"

Response

ExamplesSchema

Success, a group was found

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc",
  "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
  "displayName": "Engineering",
  "members": [
    {
      "value": "879db59-3bdf-4490-ad68-ab880a2694745",
      "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745",
      "displayName": "User 1"
    },
    {
      "value": "0db508eb-91e2-46e4-809c-30dcbda0c685",
      "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685",
      "displayName": "User 2"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "created": "2012-03-27T19:59:26.000Z",
    "lastModified": "2018-03-27T19:59:26.000Z",
    "location": "https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e"
  }
}

Set SCIM information for a provisioned enterprise group

put /scim/v2/Groups/{scim_group_id}

Note: The SCIM API endpoints for enterprise accounts are currently in private beta and are subject to change.

Replaces an existing provisioned group’s information.

You must provide all the information required for the group as if you were provisioning it for the first time. Any existing group information that you don't provide will be removed, including group membership. If you want to only update a specific attribute, use the Update an attribute for a SCIM enterprise group endpoint instead.

schemas

array[string]

required

The URIs that are used to indicate the namespaces of the SCIM schemas.

Example: [ "urn:ietf:params:scim:schemas:core:2.0:Group" ]

externalId

string

required

A unique identifier for the resource as defined by the provisioning client.

Example: "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159"

displayName

string

required

A human-readable name for a security group.

Example: "Engineering"

members

array[object]

required

The group members.

Request

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
  "displayName": "Engineering"
}

Response

ExamplesSchema

Group was updated

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc",
  "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
  "displayName": "Engineering",
  "members": [
    {
      "value": "879db59-3bdf-4490-ad68-ab880a2694745",
      "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745",
      "displayName": "User 1"
    },
    {
      "value": "0db508eb-91e2-46e4-809c-30dcbda0c685",
      "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685",
      "displayName": "User 2"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "created": "2012-03-27T19:59:26.000Z",
    "lastModified": "2018-03-27T19:59:26.000Z",
    "location": "https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e"
  }
}

Delete a SCIM group from an enterprise

delete /scim/v2/Groups/{scim_group_id}

Note: The SCIM API endpoints for enterprise accounts are currently in private beta and are subject to change.

Deletes a SCIM group from an enterprise.

scim_group_id

string

required

A unique identifier of the SCIM group.

Example: "7fce0092-d52e-4f76-b727-3955bd72c939"

Response

ExamplesSchema

Group was deleted, no content

Empty response

Update an attribute for a SCIM enterprise group

patch /scim/v2/Groups/{scim_group_id}

Note: The SCIM API endpoints for enterprise accounts are currently in private beta and are subject to change.

Update a provisioned group’s individual attributes.

To change a group’s values, you must provide a specific Operations JSON format that contains at least one of the add, remove, or replace operations. For examples and more information on the SCIM operations format, see the SCIM specification. Update can also be used to add group memberships.

Group memberships can be sent one at a time or in batches for faster performance. Note: The memberships are referenced through a local user id, and the user will need to be created before they are referenced here.

Operations

array[object]

required

patch operations list

schemas

array[string]

required

Request

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "Employees"
    }
  ]
}

Response

ExamplesSchema

Response

Empty response

List SCIM provisioned identities for an enterprise

get /scim/v2/Users

Note: The SCIM API endpoints for enterprise accounts are currently in private beta and are subject to change.

Lists provisioned SCIM enterprise members.

When a user with a SCIM-provisioned external identity is removed from an enterprise through a patch with active flag set to false, the account's metadata is preserved to allow the user to re-join the enterprise in the future. However, the user's account will be suspended and the user will not be able to sign-in. In order to permanently suspend the users account with no ability to re-join the enterprise in the future, use the delete request. Users that were not permanently deleted will be visible in the returned results.

You can improve query search time by using the excludedAttributes query parameter with a value of groups to exclude groups from the response.

filter

string

If specified, only results that match the specified filter will be returned. Multiple filters are not supported. Possible filters are userName, externalId, id, and displayName. For example, ?filter="externalId eq '9138790-10932-109120392-12321'".

excludedAttributes

string

Excludes the specified attribute from being returned in the results. Using this parameter can speed up response time.

Example: "members"

startIndex

int

int32

Used for pagination: the starting index of the first result to return when paginating through values.

Default: 1
Example: 1

count

int

int32

Used for pagination: the number of results to return per page.

Default: 30
Example: 1

Response

ExamplesSchema

Success, either users were found or not found

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "externalId": "E012345",
      "id": "7fce0092-d52e-4f76-b727-3955bd72c939",
      "active": true,
      "userName": "E012345",
      "name": {
        "formatted": "Ms. Mona Lisa Octocat",
        "familyName": "Octocat",
        "givenName": "Mona",
        "middleName": "Lisa"
      },
      "displayName": "Mona Lisa",
      "emails": [
        {
          "value": "mlisa@example.com",
          "type": "work",
          "primary": true
        }
      ],
      "roles": [
        {
          "value": "User",
          "primary": false
        }
      ]
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 20
}

Provision a SCIM enterprise user

post /scim/v2/Users

Note: The SCIM API endpoints for enterprise accounts are currently in private beta and are subject to change.

Creates an external identity for a new SCIM enterprise user.

SCIM does not authenticate users, it only provisions them. The authentication of users is done by SAML. However, when SCIM is enabled, all users need to be provisioned through SCIM before a user can sign in through SAML. The matching of a user to a SCIM provisioned user is done when the SAML assertion is consumed. The user will be matched on SAML response NameID to SCIM userName.

When converting existing enterprise to use SCIM, the user handle (userName) from the SCIM payload will be used to match the provisioned user to an already existing user in the enterprise. Since the new identity record is created for newly provisioned users the matching for those records is done using a user's handle. Currently the matching will be performed to all of the users no matter if they were SAML JIT provisioned or created as local users.

schemas

array[string]

required

The URIs that are used to indicate the namespaces of the SCIM schemas.

Example: [ "urn:ietf:params:scim:schemas:core:2.0:User" ]

externalId

string

required

A unique identifier for the resource as defined by the provisioning client.

Example: "E012345"

active

boolean

required

Whether the user active in the IdP.

Example: true

userName

string

required

The username for the user.

Example: "E012345"

name

object (name)

displayName

string

required

A human-readable name for the user.

Example: "Mona Lisa"

emails

array[object]

required

The emails for the user.

roles

array[object]

The roles assigned to the user.

Request

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "externalId": "E012345",
  "active": true,
  "userName": "E012345",
  "name": {
    "formatted": "Ms. Mona Lisa Octocat",
    "familyName": "Octocat",
    "givenName": "Mona",
    "middleName": "Lisa"
  },
  "displayName": "Mona Lisa",
  "emails": [
    {
      "value": "mlisa@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "roles": [
    {
      "value": "User",
      "primary": false
    }
  ]
}

Response

ExamplesSchema

User has been created

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "7fce0092-d52e-4f76-b727-3955bd72c939",
  "externalId": "E012345",
  "active": true,
  "userName": "E012345",
  "name": {
    "formatted": "Ms. Mona Lisa Octocat",
    "familyName": "Octocat",
    "givenName": "Mona",
    "middleName": "Lisa"
  },
  "displayName": "Mona Lisa",
  "emails": [
    {
      "value": "mlisa@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "roles": [
    {
      "value": "User",
      "primary": false
    }
  ],
  "meta": {
    "resourceType": "User",
    "created": "2012-03-27T19:59:26.000Z",
    "lastModified": "2018-03-27T19:59:26.000Z",
    "location": "https://api.github.localhost/scim/v2/Users/7fce0092-d52e-4f76-b727-3955bd72c939"
  }
}

Get SCIM provisioning information for an enterprise user

get /scim/v2/Users/{scim_user_id}

Note: The SCIM API endpoints for enterprise accounts are currently in private beta and are subject to change.

Gets information about a SCIM user.

scim_user_id

string

required

The unique identifier of the SCIM user.

Response

ExamplesSchema

Success, a user was found

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "7fce0092-d52e-4f76-b727-3955bd72c939",
  "externalId": "E012345",
  "active": true,
  "userName": "E012345",
  "name": {
    "formatted": "Ms. Mona Lisa Octocat",
    "familyName": "Octocat",
    "givenName": "Mona",
    "middleName": "Lisa"
  },
  "displayName": "Mona Lisa",
  "emails": [
    {
      "value": "mlisa@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "roles": [
    {
      "value": "User",
      "primary": false
    }
  ],
  "meta": {
    "resourceType": "User",
    "created": "2012-03-27T19:59:26.000Z",
    "lastModified": "2018-03-27T19:59:26.000Z",
    "location": "https://api.github.localhost/scim/v2/Users/7fce0092-d52e-4f76-b727-3955bd72c939"
  }
}

Set SCIM information for a provisioned enterprise user

put /scim/v2/Users/{scim_user_id}

Note: The SCIM API endpoints for enterprise accounts are currently in private beta and are subject to change.

Replaces an existing provisioned user's information.

You must provide all the information required for the user as if you were provisioning them for the first time. Any existing user information that you don't provide will be removed. If you want to only update a specific attribute, use the Update an attribute for a SCIM user endpoint instead.

Warning: Setting active: false will suspend a user and obfuscate the user handle and user email. Since the implementation is a generic SCIM implementation and does not differentiate yet between different IdP providers, for Okta, the user GDPR data will not be purged and the credentials will not be removed.

schemas

array[string]

required

The URIs that are used to indicate the namespaces of the SCIM schemas.

Example: [ "urn:ietf:params:scim:schemas:core:2.0:User" ]

externalId

string

required

A unique identifier for the resource as defined by the provisioning client.

Example: "E012345"

active

boolean

required

Whether the user active in the IdP.

Example: true

userName

string

required

The username for the user.

Example: "E012345"

name

object (name)

displayName

string

required

A human-readable name for the user.

Example: "Mona Lisa"

emails

array[object]

required

The emails for the user.

roles

array[object]

The roles assigned to the user.

Request

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "externalId": "E012345",
  "active": true,
  "userName": "E012345",
  "name": {
    "formatted": "Ms. Mona Lisa Octocat",
    "familyName": "Octocat",
    "givenName": "Mona",
    "middleName": "Lisa"
  },
  "displayName": "Mona Lisa",
  "emails": [
    {
      "value": "mlisa@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "roles": [
    {
      "value": "User",
      "primary": false
    }
  ]
}

Response

ExamplesSchema

User was updated

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "7fce0092-d52e-4f76-b727-3955bd72c939",
  "externalId": "E012345",
  "active": true,
  "userName": "E012345",
  "name": {
    "formatted": "Ms. Mona Lisa Octocat",
    "familyName": "Octocat",
    "givenName": "Mona",
    "middleName": "Lisa"
  },
  "displayName": "Mona Lisa",
  "emails": [
    {
      "value": "mlisa@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "roles": [
    {
      "value": "User",
      "primary": false
    }
  ],
  "meta": {
    "resourceType": "User",
    "created": "2012-03-27T19:59:26.000Z",
    "lastModified": "2018-03-27T19:59:26.000Z",
    "location": "https://api.github.localhost/scim/v2/Users/7fce0092-d52e-4f76-b727-3955bd72c939"
  }
}

Delete a SCIM user from an enterprise

delete /scim/v2/Users/{scim_user_id}

Note: The SCIM API endpoints for enterprise accounts are currently in private beta and are subject to change.

Permanently suspends a SCIM user from an enterprise, removes all data for the user, obfuscates the login, email, and display name of the user, removes all external-identity SCIM attributes, and deletes the emails, avatar, PATs, SSH keys, OAuth authorizations credentials, GPG keys, and SAML mappings for the user. You will not be able to undo this action.

scim_user_id

string

required

The unique identifier of the SCIM user.

Response

ExamplesSchema

User was deleted, no content

Empty response

Update an attribute for a SCIM enterprise user

patch /scim/v2/Users/{scim_user_id}

Note: The SCIM API endpoints for enterprise accounts are currently in private beta and are subject to change.

Update a provisioned user's individual attributes.

To change a user's values, you must provide a specific Operations JSON format that contains at least one of the add, remove, or replace operations. For examples and more information on the SCIM operations format, see the SCIM specification.

Note: Complicated SCIM path selectors that include filters are not supported. For example, a path selector defined as "path": "emails[type eq \"work\"]" will not work.

Warning: Setting active: false will suspend a user and obfuscate the user handle and user email. Since the implementation is a generic SCIM implementation and does not differentiate yet between different IdP providers, for Okta, the user GDPR data will not be purged and the credentials will not be removed.

{
  "Operations":[{
    "op":"replace",
    "value":{
      "active":false
    }
  }]
}

Operations

array[object]

required

patch operations list

schemas

array[string]

required

Request

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "emails[type eq 'work'].value",
      "value": "updatedEmail@microsoft.com"
    },
    {
      "op": "replace",
      "path": "name.familyName",
      "value": "updatedFamilyName"
    }
  ]
}

Response

ExamplesSchema

Success, user was updated

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "7fce0092-d52e-4f76-b727-3955bd72c939",
  "externalId": "E012345",
  "active": true,
  "userName": "E012345",
  "name": {
    "formatted": "Ms. Mona Lisa Octocat",
    "familyName": "Octocat",
    "givenName": "Mona",
    "middleName": "Lisa"
  },
  "displayName": "Mona Lisa",
  "emails": [
    {
      "value": "mlisa@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "roles": [
    {
      "value": "User",
      "primary": false
    }
  ],
  "meta": {
    "resourceType": "User",
    "created": "2012-03-27T19:59:26.000Z",
    "lastModified": "2018-03-27T19:59:26.000Z",
    "location": "https://api.github.localhost/scim/v2/Users/7fce0092-d52e-4f76-b727-3955bd72c939"
  }
}

Get the configuration status

get /setup/api/configcheck

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

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

The different statuses are:

Status	Description
`PENDING`	The job has not started yet
`CONFIGURING`	The job is running
`DONE`	The job has finished correctly
`FAILED`	The job has finished unexpectedly

Response

ExamplesSchema

Response

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

post /setup/api/configure

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

Response

ExamplesSchema

Response

Empty response

Get the maintenance status

get /setup/api/maintenance

Check your installation's maintenance status:

Response

ExamplesSchema

Response

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

Enable or disable maintenance mode

post /setup/api/maintenance

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

maintenance

string

required

A JSON string with the attributes enabled and when.

The possible values for enabled are true and false. When it's false, the attribute when is ignored and the maintenance mode is turned off. when defines the time period when the maintenance was enabled.

The possible values for when are now or any date parseable by mojombo/chronic.

Request

{
  "maintenance": "{\"enabled\":true, \"when\":\"now\"}"
}

Response

ExamplesSchema

Response

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

Get settings

get /setup/api/settings

Gets the settings for your instance. To change settings, see the Set settings endpoint.

Note: You cannot retrieve the management console password with the Enterprise administration API.

Response

ExamplesSchema

Response

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

put /setup/api/settings

Applies settings on your instance. For a list of the available settings, see the Get settings endpoint.

Notes:

The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.
You cannot set the management console password with the Enterprise administration API. Use the ghe-set-password utility to change the management console password. For more information, see "Command-line utilities."

settings

string

required

A JSON string with the new settings. Note that you only need to pass the specific settings you want to modify. For a list of the available settings, see the Get settings endpoint.

Request

{
  "settings": "{ \"enterprise\": { \"public_pages\": true }}"
}

Response

ExamplesSchema

Response

Empty response

Get all authorized SSH keys

get /setup/api/settings/authorized-keys

Response

ExamplesSchema

Response

[
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  }
]

Add an authorized SSH key

post /setup/api/settings/authorized-keys

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

authorized_key

string

required

The public SSH key.

Request

{
  "authorized_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCssTL/Vtu/ODLTj0VtZoRAbvf7uiv5997GyDq0MoAZUjb5jmA5wYe2/wF6sFuhiZTnZoF1ZtCHunPp0hM/GHrn6VySBhNncx14YO8FPt1CIhEeRMSEjUK9cY3xAbS365oXY8vnUHJsS9+1tr/2bx/+4NJfcUt/Ezf1OR/0LStQXw=="
}

Response

ExamplesSchema

Response

[
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  }
]

Remove an authorized SSH key

delete /setup/api/settings/authorized-keys

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

authorized_key

string

required

The public SSH key.

Request

{
  "authorized_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCssTL/Vtu/ODLTj0VtZoRAbvf7uiv5997GyDq0MoAZUjb5jmA5wYe2/wF6sFuhiZTnZoF1ZtCHunPp0hM/GHrn6VySBhNncx14YO8FPt1CIhEeRMSEjUK9cY3xAbS365oXY8vnUHJsS9+1tr/2bx/+4NJfcUt/Ezf1OR/0LStQXw=="
}

Response

ExamplesSchema

Response

[
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  }
]

Create a GitHub license

post /setup/api/start

When you boot a GitHub instance for the first time, you can use the following endpoint to upload a license.

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

When using this endpoint, your GitHub instance must have a password set. This can be accomplished two ways:

If you're working directly with the API before accessing the web interface, you must pass in the password parameter to set your password.
If you set up your instance via the web interface before accessing the API, your calls to this endpoint do not need the password parameter.

Note: The request body for this operation must be submitted as multipart/form-data data. You can can reference the license file by prefixing the filename with the @ symbol using curl. For more information, see the curl documentation.

license

string

required

The content of your .ghl license file.

password

string

You must provide a password only if you are uploading your license for the first time. If you previously set a password through the web interface, you don't need this parameter.

settings

string

An optional JSON string containing the installation settings. For a list of the available settings, see the Get settings endpoint.

Request

{
  "license": "@enterprise.ghl",
  "password": "secret"
}

Response

ExamplesSchema

Response

Empty response

Upgrade a license

post /setup/api/upgrade

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

Note: The request body for this operation must be submitted as multipart/form-data data. You can can reference the license file by prefixing the filename with the @ symbol using curl. For more information, see the curl documentation.

license

string

The content of your new .ghl license file.

Request

{
  "license": "@enterprise.ghl"
}

Response

ExamplesSchema

Response

Empty response

Promote a user to be a site administrator

put /users/{username}/site_admin

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

username

string

required

The handle for the GitHub user account.

Response

ExamplesSchema

Response

Empty response

Demote a site administrator

delete /users/{username}/site_admin

You can demote any user account except your own.

username

string

required

The handle for the GitHub user account.

Response

ExamplesSchema

Response

Empty response

Suspend a user

put /users/{username}/suspended

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

reason

string

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.

Request

{
  "reason": "Suspended during leave of absence."
}

Response

ExamplesSchema

Response

Empty response

Unsuspend a user

delete /users/{username}/suspended

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.

reason

string

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.

Request

{
  "reason": "Unsuspended after leave of absence."
}

Response

ExamplesSchema

Response

Empty response