カスタムリポジトリロール

この REST API を使って、カスタムリポジトリロールを操作します。

List custom repository roles in an organization

List the custom repository roles available in this organization. In order to see custom repository roles in an organization, the authenticated user must be an organization owner.

To use this endpoint the authenticated user must be an administrator for the organization or of an repository of the organization and must use an access token with admin:org repo scope. GitHub Apps must have the organization_custom_roles:read organization permission to use this endpoint.

For more information on custom repository roles, see "About custom repository roles."

パラメーター

ヘッダー
名前, Type, 説明
`accept`string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`organization_id`string必須 The unique identifier of the organization.

HTTP 応答状態コード

状態コード	説明
`200`	Response - list of custom role names

コードサンプル

get/organizations/{organization_id}/custom_roles

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/organizations/ORGANIZATION_ID/custom_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://api.github.com/users/github",
        "html_url": "https://github.com/github",
        "followers_url": "https://api.github.com/users/github/followers",
        "following_url": "https://api.github.com/users/github/following{/other_user}",
        "gists_url": "https://api.github.com/users/github/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/github/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/github/subscriptions",
        "organizations_url": "https://api.github.com/users/github/orgs",
        "repos_url": "https://api.github.com/users/github/repos",
        "events_url": "https://api.github.com/users/github/events{/privacy}",
        "received_events_url": "https://api.github.com/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://api.github.com/users/github",
        "html_url": "https://github.com/github",
        "followers_url": "https://api.github.com/users/github/followers",
        "following_url": "https://api.github.com/users/github/following{/other_user}",
        "gists_url": "https://api.github.com/users/github/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/github/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/github/subscriptions",
        "organizations_url": "https://api.github.com/users/github/orgs",
        "repos_url": "https://api.github.com/users/github/repos",
        "events_url": "https://api.github.com/users/github/events{/privacy}",
        "received_events_url": "https://api.github.com/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 role

に対応 GitHub Apps

Note: This operation is in beta and is subject to change.

Creates a custom repository role that can be used by all repositories owned by the organization.

To use this endpoint the authenticated user must be an administrator for the organization and must use an access token with admin:org scope. GitHub Apps must have the organization_custom_roles:write organization permission to use this endpoint.

For more information on custom repository roles, see "About custom repository roles."

パラメーター

ヘッダー
名前, Type, 説明
`accept`string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`org`string必須 The organization name. The name is not case sensitive.
本文のパラメーター
名前, Type, 説明
`name`string必須 The name of the custom role.
`description`string A short description about the intended usage of this role or what permissions it grants.
`base_role`string必須 The system role from which this role inherits permissions. 次のいずれかにできます: `read`, `triage`, `write`, `maintain`
`permissions`array of strings必須 A list of additional permissions included in this role.

HTTP 応答状態コード

状態コード	説明
`201`	Created
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

コードサンプル

post/orgs/{org}/custom_roles

curl \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/custom_roles \
  -d '{"name":"Labeler","description":"A role for issue and PR labelers","base_role":"read","permissions":["add_label"]}'

Response

Status: 201

{
  "id": 8030,
  "name": "Labeler",
  "description": "A role for issue and PR labelers",
  "base_role": "read",
  "permissions": [
    "add_label"
  ],
  "organization": {
    "login": "github",
    "id": 9919,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjk5MTk=",
    "avatar_url": "https://avatars.githubusercontent.com/u/9919?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/github",
    "html_url": "https://github.com/github",
    "followers_url": "https://api.github.com/users/github/followers",
    "following_url": "https://api.github.com/users/github/following{/other_user}",
    "gists_url": "https://api.github.com/users/github/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/github/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/github/subscriptions",
    "organizations_url": "https://api.github.com/users/github/orgs",
    "repos_url": "https://api.github.com/users/github/repos",
    "events_url": "https://api.github.com/users/github/events{/privacy}",
    "received_events_url": "https://api.github.com/users/github/received_events",
    "type": "Organization",
    "site_admin": false
  },
  "created_at": "2022-07-04T22:19:11Z",
  "updated_at": "2022-07-04T22:19:11Z"
}

Get a custom role

に対応 GitHub Apps

Note: This operation is in beta and is subject to change.

Gets a custom repository role that is available to all repositories owned by the organization.

To use this operation, the authenticated user must be an administrator for the organization and must use an access token with admin:org scope. GitHub Apps must have the organization_custom_roles:write organization permission to use this endpoint.

For more information on custom repository roles, see "About custom repository roles."

パラメーター

ヘッダー
名前, Type, 説明
`accept`string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`org`string必須 The organization name. The name is not case sensitive.
`role_id`integer必須 The unique identifier of the role.

HTTP 応答状態コード

状態コード	説明
`200`	OK
`404`	Resource not found

コードサンプル

get/orgs/{org}/custom_roles/{role_id}

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/custom_roles/ROLE_ID

Response

Status: 200

{
  "id": 8030,
  "name": "Labeler",
  "description": "A role for who can label issues and PRs",
  "base_role": "read",
  "permissions": [
    "add_label"
  ],
  "organization": {
    "login": "github",
    "id": 9919,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjk5MTk=",
    "avatar_url": "https://avatars.githubusercontent.com/u/9919?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/github",
    "html_url": "https://github.com/github",
    "followers_url": "https://api.github.com/users/github/followers",
    "following_url": "https://api.github.com/users/github/following{/other_user}",
    "gists_url": "https://api.github.com/users/github/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/github/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/github/subscriptions",
    "organizations_url": "https://api.github.com/users/github/orgs",
    "repos_url": "https://api.github.com/users/github/repos",
    "events_url": "https://api.github.com/users/github/events{/privacy}",
    "received_events_url": "https://api.github.com/users/github/received_events",
    "type": "Organization",
    "site_admin": false
  },
  "created_at": "2022-07-04T22:19:11Z",
  "updated_at": "2022-07-04T22:19:11Z"
}

Update a custom role

に対応 GitHub Apps

Note: This operation is in beta and subject to change.

Updates a custom repository role that can be used by all repositories owned by the organization.

To use this endpoint the authenticated user must be an administrator for the organization and must use an access token with admin:org scope. GitHub Apps must have the organization_custom_roles:write organization permission to use this endpoint.

For more information about custom repository roles, see "About custom repository roles."

パラメーター

ヘッダー
名前, Type, 説明
`accept`string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`org`string必須 The organization name. The name is not case sensitive.
`role_id`integer必須 The unique identifier of the role.
本文のパラメーター
名前, Type, 説明
`name`string The name of the custom role.
`description`string 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. 次のいずれかにできます: `read`, `triage`, `write`, `maintain`
`permissions`array of strings A list of additional permissions included in this role. If specified, these permissions will replace any currently set on the role.

HTTP 応答状態コード

状態コード	説明
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

コードサンプル

patch/orgs/{org}/custom_roles/{role_id}

curl \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/custom_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": "Labeler",
  "description": "A role for issue and PR labelers",
  "base_role": "read",
  "permissions": [
    "add_label",
    "remove_label"
  ],
  "organization": {
    "login": "github",
    "id": 9919,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjk5MTk=",
    "avatar_url": "https://avatars.githubusercontent.com/u/9919?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/github",
    "html_url": "https://github.com/github",
    "followers_url": "https://api.github.com/users/github/followers",
    "following_url": "https://api.github.com/users/github/following{/other_user}",
    "gists_url": "https://api.github.com/users/github/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/github/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/github/subscriptions",
    "organizations_url": "https://api.github.com/users/github/orgs",
    "repos_url": "https://api.github.com/users/github/repos",
    "events_url": "https://api.github.com/users/github/events{/privacy}",
    "received_events_url": "https://api.github.com/users/github/received_events",
    "type": "Organization",
    "site_admin": false
  },
  "created_at": "2022-07-04T22:19:11Z",
  "updated_at": "2022-07-04T22:19:11Z"
}

Delete a custom role

に対応 GitHub Apps

Note: This operation is in beta and is subject to change.

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.

To use this endpoint the authenticated user must be an administrator for the organization and must use an access token with admin:org scope. GitHub Apps must have the organization_custom_roles:write organization permission to use this endpoint.

For more information about custom repository roles, see "About custom repository roles."

パラメーター

ヘッダー
名前, Type, 説明
`accept`string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`org`string必須 The organization name. The name is not case sensitive.
`role_id`integer必須 The unique identifier of the role.

HTTP 応答状態コード

状態コード	説明
`204`	No Content

コードサンプル

delete/orgs/{org}/custom_roles/{role_id}

curl \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/custom_roles/ROLE_ID

Response

Status: 204

List repository fine-grained permissions for an organization

に対応 GitHub Apps

Note: This operation is in beta and subject to change.

Lists the fine-grained permissions that can be used in custom repository roles for an organization. For more information, see "About custom repository roles."

To use this endpoint the authenticated user must be an administrator for the organization or of an repository of the organization and must use an access token with admin:org repo scope. GitHub Apps must have the organization_custom_roles:read organization permission to use this endpoint.

パラメーター

ヘッダー
名前, Type, 説明
`accept`string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`org`string必須 The organization name. The name is not case sensitive.

HTTP 応答状態コード

状態コード	説明
`200`	OK

コードサンプル

get/orgs/{org}/fine_grained_permissions

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/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"
  }
]

カスタム リポジトリ ロール

List custom repository roles in an organization

Response - list of custom role names

Create a custom role

Response

Get a custom role

Response

Update a custom role

Response

Delete a custom role

Response

List repository fine-grained permissions for an organization

Response

カスタムリポジトリロール