v56

latestOpenAPI 3.0.3MITraw.githubusercontent.com2026-08-011,4581,08113.3 MB

orgs

Closing down - Create a custom role

[!WARNING] Closing down notice: This operation is closing down and will be removed after September 6, 2023. Use the "Create a custom repository role" endpoint instead.

Creates a custom repository role that can be used by all repositories owned by the organization. For more information on custom repository roles, see "About custom repository roles."

The authenticated user must be an administrator for the organization to use this endpoint.

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

post/orgs/{org}/custom_roles

Path parameters

orgstring required

The organization name. The name is not case sensitive.

Request body

namestring required

The name of the custom role.

descriptionstring nullable

A short description about who this role is for or what permissions it grants.

base_role'read' | 'triage' | 'write' | 'maintain' required

The system role from which this role inherits permissions.

permissionsstring[] required

A list of additional permissions included in this role.

Response

Response

idinteger required

The unique identifier of the custom role.

namestring required

The name of the custom role.

descriptionstring nullable

A short description about who this role is for or what permissions it grants.

base_role'read' | 'triage' | 'write' | 'maintain' required

The system role from which this role inherits permissions.

permissionsstring[] required

A list of additional permissions included in this role.

created_atstring date-time required

updated_atstring date-time required

Example response

{
  "organization": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "41d064eb2195891e12d0413f63227ea7",
    "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",
    "starred_at": "\"2020-07-09T00:17:55Z\"",
    "user_view_type": "public"
  }
}