Sign in

v56

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

Update a custom organization role

Updates an existing custom organization role. Permission changes will apply to all assignees. For more information on custom organization roles, see "Managing people's access to your organization with roles."

If the update would add repository permissions, the base_role must also be set to a value besides none, either previously or as part of the update. If the update sets the base_role field to none, you must also remove all of the repository permissions as well, otherwise the update will fail.

To use this endpoint, the authenticated user must be one of:

  • An administrator for the organization.
  • An organization member (or a member of a team) assigned a custom organization role that includes the Manage custom organization roles (write_organization_custom_org_role) permission. For more information, see "Permissions for organization access."

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

patch/orgs/{org}/organization-roles/{role_id}

Path parameters

orgstring required

The organization name. The name is not case sensitive.

role_idinteger required

The unique identifier of the role.

Request body

namestring

The name of the custom role.

descriptionstring

A short description about the intended use of this role or the permissions it grants.

permissionsstring[]

A list of additional permissions included in this role.

base_role'none' | 'read' | 'triage' | 'write' | 'maintain' | 'admin'

The system role from which this role can inherit permissions.

Response

Response

idinteger required

The unique identifier of the role.

namestring required

The name of the role.

descriptionstring nullable

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

base_role'read' | 'triage' | 'write' | 'maintain' | 'admin' nullable

The system role from which this role inherits permissions.

source'Organization' | 'Enterprise' | 'Predefined' nullable

Source answers the question, "where did this role come from?"

permissionsstring[] required

A list of permissions included in this role.

created_atstring date-time required

The date and time the role was created.

updated_atstring date-time required

The date and time the role was last updated.

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