REST API endpoints for custom repository roles
Use the REST API to interact with custom repository roles.
Closing down - List custom repository roles in an organization
Warning
Closing down notice: This operation is closing down and will be removed in the future. Use the "List custom repository roles" endpoint instead.
List the custom repository roles available in this organization. For more information on custom repository roles, see "About custom repository roles."
The authenticated user must be administrator of the organization or of a repository of the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
or repo
scope to use this endpoint.
Fine-grained access tokens for "Closing down - List custom repository roles in an organization"
This endpoint works with the following fine-grained token types:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have at least one of the following permission sets:
- "Custom repository roles" organization permissions (read)
- "Administration" organization permissions (read)
Parameters for "Closing down - List custom repository roles in an organization"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
organization_id string RequiredThe unique identifier of the organization. |
HTTP response status codes for "Closing down - List custom repository roles in an organization"
Status code | Description |
---|---|
200 | Response - list of custom role names |
Code samples for "Closing down - List custom repository roles in an organization"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/organizations/ORGANIZATION_ID/custom_roles
Response - list of custom role names
Status: 200
{
"id": 8030,
"name": "Security Engineer",
"description": "Able to contribute code and maintain the security pipeline",
"base_role": "maintain",
"permissions": [
"delete_alerts_code_scanning"
],
"organization": {
"login": "github",
"id": 1,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
"url": "https://HOSTNAME/orgs/github",
"repos_url": "https://HOSTNAME/orgs/github/repos",
"events_url": "https://HOSTNAME/orgs/github/events",
"hooks_url": "https://HOSTNAME/orgs/github/hooks",
"issues_url": "https://HOSTNAME/orgs/github/issues",
"members_url": "https://HOSTNAME/orgs/github/members{/member}",
"public_members_url": "https://HOSTNAME/orgs/github/public_members{/member}",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"description": "A great organization"
},
"created_at": "2022-07-04T22:19:11Z",
"updated_at": "2022-07-04T22:20:11Z"
}
List custom repository roles in an organization
List the custom repository roles available in this organization. For more information on custom repository roles, see "About custom repository roles."
The authenticated user must be an administrator of the organization or of a repository of the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
or repo
scope to use this endpoint.
Fine-grained access tokens for "List custom repository roles in an organization"
This endpoint works with the following fine-grained token types:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have at least one of the following permission sets:
- "Custom repository roles" organization permissions (read)
- "Administration" organization permissions (read)
Parameters for "List custom repository roles in an organization"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
HTTP response status codes for "List custom repository roles in an organization"
Status code | Description |
---|---|
200 | Response - list of custom role names |
Code samples for "List custom repository roles in an organization"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/orgs/ORG/custom-repository-roles
Response - list of custom role names
Status: 200
{
"total_count": 2,
"custom_roles": [
{
"id": 8030,
"name": "Security Engineer",
"description": "Able to contribute code and maintain the security pipeline",
"base_role": "maintain",
"permissions": [
"delete_alerts_code_scanning"
],
"organization": {
"login": "github",
"id": 9919,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjk5MTk=",
"avatar_url": "https://avatars.githubusercontent.com/u/9919?v=4",
"gravatar_id": "",
"url": "https://HOSTNAME/users/github",
"html_url": "https://github.com/github",
"followers_url": "https://HOSTNAME/users/github/followers",
"following_url": "https://HOSTNAME/users/github/following{/other_user}",
"gists_url": "https://HOSTNAME/users/github/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/github/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/github/subscriptions",
"organizations_url": "https://HOSTNAME/users/github/orgs",
"repos_url": "https://HOSTNAME/users/github/repos",
"events_url": "https://HOSTNAME/users/github/events{/privacy}",
"received_events_url": "https://HOSTNAME/users/github/received_events",
"type": "Organization",
"site_admin": false
},
"created_at": "2022-07-04T22:19:11Z",
"updated_at": "2022-07-04T22:20:11Z"
},
{
"id": 8031,
"name": "Community manager",
"description": "Able to handle all the community interactions without being able to contribute code",
"base_role": "read",
"permissions": [
"mark_as_duplicate",
"manage_settings_pages",
"manage_settings_wiki",
"set_social_preview",
"edit_repo_metadata",
"toggle_discussion_comment_minimize"
],
"organization": {
"login": "github",
"id": 9919,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjk5MTk=",
"avatar_url": "https://avatars.githubusercontent.com/u/9919?v=4",
"gravatar_id": "",
"url": "https://HOSTNAME/users/github",
"html_url": "https://github.com/github",
"followers_url": "https://HOSTNAME/users/github/followers",
"following_url": "https://HOSTNAME/users/github/following{/other_user}",
"gists_url": "https://HOSTNAME/users/github/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/github/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/github/subscriptions",
"organizations_url": "https://HOSTNAME/users/github/orgs",
"repos_url": "https://HOSTNAME/users/github/repos",
"events_url": "https://HOSTNAME/users/github/events{/privacy}",
"received_events_url": "https://HOSTNAME/users/github/received_events",
"type": "Organization",
"site_admin": false
},
"created_at": "2022-07-05T12:01:11Z",
"updated_at": "2022-07-05T12:20:11Z"
}
]
}
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.
Fine-grained access tokens for "Create a custom repository role"
This endpoint works with the following fine-grained token types:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Custom repository roles" organization permissions (write)
Parameters for "Create a custom repository role"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
Name, Type, Description |
---|
name string RequiredThe name of the custom role. |
description string or null A short description about who this role is for or what permissions it grants. |
base_role string RequiredThe system role from which this role inherits permissions. Can be one of: |
permissions array of strings RequiredA list of additional permissions included in this role. |
HTTP response status codes for "Create a custom repository role"
Status code | Description |
---|---|
201 | Created |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Create a custom repository role"
Request example
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/orgs/ORG/custom-repository-roles \
-d '{"name":"Labeler","description":"A role for issue and pull request labelers","base_role":"read","permissions":["add_label"]}'
Response
Status: 201
{
"id": 8030,
"name": "Security Engineer",
"description": "Able to contribute code and maintain the security pipeline",
"base_role": "maintain",
"permissions": [
"delete_alerts_code_scanning"
],
"organization": {
"login": "github",
"id": 1,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
"url": "https://HOSTNAME/orgs/github",
"repos_url": "https://HOSTNAME/orgs/github/repos",
"events_url": "https://HOSTNAME/orgs/github/events",
"hooks_url": "https://HOSTNAME/orgs/github/hooks",
"issues_url": "https://HOSTNAME/orgs/github/issues",
"members_url": "https://HOSTNAME/orgs/github/members{/member}",
"public_members_url": "https://HOSTNAME/orgs/github/public_members{/member}",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"description": "A great organization"
},
"created_at": "2022-07-04T22:19:11Z",
"updated_at": "2022-07-04T22:20:11Z"
}
Get a custom repository role
Gets a custom repository role that is available to 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 of the organization or of a repository of the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
or repo
scope to use this endpoint.
Fine-grained access tokens for "Get a custom repository role"
This endpoint works with the following fine-grained token types:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have at least one of the following permission sets:
- "Custom repository roles" organization permissions (read)
- "Administration" organization permissions (read)
Parameters for "Get a custom repository role"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
role_id integer RequiredThe unique identifier of the role. |
HTTP response status codes for "Get a custom repository role"
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
Code samples for "Get a custom repository role"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/orgs/ORG/custom-repository-roles/ROLE_ID
Response
Status: 200
{
"id": 8030,
"name": "Security Engineer",
"description": "Able to contribute code and maintain the security pipeline",
"base_role": "maintain",
"permissions": [
"delete_alerts_code_scanning"
],
"organization": {
"login": "github",
"id": 1,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
"url": "https://HOSTNAME/orgs/github",
"repos_url": "https://HOSTNAME/orgs/github/repos",
"events_url": "https://HOSTNAME/orgs/github/events",
"hooks_url": "https://HOSTNAME/orgs/github/hooks",
"issues_url": "https://HOSTNAME/orgs/github/issues",
"members_url": "https://HOSTNAME/orgs/github/members{/member}",
"public_members_url": "https://HOSTNAME/orgs/github/public_members{/member}",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"description": "A great organization"
},
"created_at": "2022-07-04T22:19:11Z",
"updated_at": "2022-07-04T22:20:11Z"
}
Update a custom repository role
Updates a custom repository role that can be used by all repositories owned by the organization. For more information about 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.
Fine-grained access tokens for "Update a custom repository role"
This endpoint works with the following fine-grained token types:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Custom repository roles" organization permissions (write)
Parameters for "Update a custom repository role"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
role_id integer RequiredThe unique identifier of the role. |
Name, Type, Description |
---|
name string The name of the custom role. |
description string or null A short description about who this role is for or what permissions it grants. |
base_role string The system role from which this role inherits permissions. Can be one of: |
permissions array of strings A list of additional permissions included in this role. |
HTTP response status codes for "Update a custom repository role"
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Update a custom repository role"
Request example
curl -L \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/orgs/ORG/custom-repository-roles/ROLE_ID \
-d '{"name":"Labeler","description":"A role for issue and PR labelers","base_role":"read","permissions":["add_label","remove_label"]}'
Response
Status: 200
{
"id": 8030,
"name": "Security Engineer",
"description": "Able to contribute code and maintain the security pipeline",
"base_role": "maintain",
"permissions": [
"delete_alerts_code_scanning"
],
"organization": {
"login": "github",
"id": 1,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
"url": "https://HOSTNAME/orgs/github",
"repos_url": "https://HOSTNAME/orgs/github/repos",
"events_url": "https://HOSTNAME/orgs/github/events",
"hooks_url": "https://HOSTNAME/orgs/github/hooks",
"issues_url": "https://HOSTNAME/orgs/github/issues",
"members_url": "https://HOSTNAME/orgs/github/members{/member}",
"public_members_url": "https://HOSTNAME/orgs/github/public_members{/member}",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"description": "A great organization"
},
"created_at": "2022-07-04T22:19:11Z",
"updated_at": "2022-07-04T22:20:11Z"
}
Delete a custom repository role
Deletes a custom role from an organization. Once the custom role has been deleted, any user, team, or invitation with the deleted custom role will be reassigned the inherited role. For more information about 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.
Fine-grained access tokens for "Delete a custom repository role"
This endpoint works with the following fine-grained token types:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Custom repository roles" organization permissions (write)
Parameters for "Delete a custom repository role"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
role_id integer RequiredThe unique identifier of the role. |
HTTP response status codes for "Delete a custom repository role"
Status code | Description |
---|---|
204 | No Content |
Code samples for "Delete a custom repository role"
Request example
curl -L \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/orgs/ORG/custom-repository-roles/ROLE_ID
Response
Status: 204
List repository fine-grained permissions for an organization
Lists the fine-grained permissions that can be used in custom repository roles for an organization. For more information, see "About custom repository roles."
The authenticated user must be an administrator of the organization or of a repository of the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
or repo
scope to use this endpoint.
Fine-grained access tokens for "List repository fine-grained permissions for an organization"
This endpoint works with the following fine-grained token types:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have at least one of the following permission sets:
- "Custom repository roles" organization permissions (read)
- "Administration" organization permissions (read)
Parameters for "List repository fine-grained permissions for an organization"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
HTTP response status codes for "List repository fine-grained permissions for an organization"
Status code | Description |
---|---|
200 | OK |
Code samples for "List repository fine-grained permissions for an organization"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/orgs/ORG/repository-fine-grained-permissions
Response
Status: 200
[
{
"name": "add_assignee",
"description": "Assign or remove a user"
},
{
"name": "remove_assignee",
"description": "Remove an assigned user"
},
{
"name": "add_label",
"description": "Add or remove a label"
}
]