v56

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

orgs

Create a custom repository role

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