{"meta":{"title":"适用于自定义存储库角色的 REST API 终结点","intro":"使用 REST API 与自定义存储库角色交互。","product":"REST API","breadcrumbs":[{"href":"/zh/enterprise-server@3.22/rest","title":"REST API"},{"href":"/zh/enterprise-server@3.22/rest/orgs","title":"组织"},{"href":"/zh/enterprise-server@3.22/rest/orgs/custom-roles","title":"自定义角色"}],"documentType":"article"},"body":"# 适用于自定义存储库角色的 REST API 终结点\n\n使用 REST API 与自定义存储库角色交互。\n\n> [!NOTE]\n> Most endpoints use `Authorization: Bearer <YOUR-TOKEN>` and `Accept: application/vnd.github+json` headers, plus `X-GitHub-Api-Version: 2026-03-10`. Curl examples below omit these standard headers for brevity.\n\n## Closing down - List custom repository roles in an organization\n\n```\nGET /organizations/{organization_id}/custom_roles\n```\n\nWarning\n\nClosing down notice: This operation is closing down and will be removed in the future. Use the \"List custom repository roles\" endpoint instead.\n\nList the custom repository roles available in this organization. For more information on custom repository roles, see \"About custom repository roles.\"\nThe authenticated user must be administrator of the organization or of a repository of the organization to use this endpoint.\nOAuth app tokens and personal access tokens (classic) need the admin:org or repo scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`organization_id`** (string) (required)\n  The unique identifier of the organization.\n\n### HTTP response status codes\n\n- **404** - Resource not found\n\n## List custom repository roles in an organization\n\n```\nGET /orgs/{org}/custom-repository-roles\n```\n\nList the custom repository roles available in this organization. For more information on custom repository roles, see \"About custom repository roles.\"\nThe authenticated user must be an administrator of the organization or of a repository of the organization to use this endpoint.\nOAuth app tokens and personal access tokens (classic) need the admin:org or repo scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`org`** (string) (required)\n  The organization name. The name is not case sensitive.\n\n### HTTP response status codes\n\n- **200** - Response - list of custom role names\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  http(s)://HOSTNAME/api/v3/orgs/ORG/custom-repository-roles\n```\n\n**Response schema (Status: 200):**\n\n* `total_count`: integer\n* `custom_roles`: array of `Organization Custom Repository Role`:\n  * `id`: required, integer\n  * `name`: required, string\n  * `description`: string or null\n  * `base_role`: required, string, enum: `read`, `triage`, `write`, `maintain`\n  * `permissions`: required, array of string\n  * `organization`: required, `Simple User`:\n    * `name`: string or null\n    * `email`: string or null\n    * `login`: required, string\n    * `id`: required, integer, format: int64\n    * `node_id`: required, string\n    * `avatar_url`: required, string, format: uri\n    * `gravatar_id`: required, string or null\n    * `url`: required, string, format: uri\n    * `html_url`: required, string, format: uri\n    * `followers_url`: required, string, format: uri\n    * `following_url`: required, string\n    * `gists_url`: required, string\n    * `starred_url`: required, string\n    * `subscriptions_url`: required, string, format: uri\n    * `organizations_url`: required, string, format: uri\n    * `repos_url`: required, string, format: uri\n    * `events_url`: required, string\n    * `received_events_url`: required, string, format: uri\n    * `type`: required, string\n    * `site_admin`: required, boolean\n    * `starred_at`: string\n    * `user_view_type`: string\n  * `created_at`: required, string, format: date-time\n  * `updated_at`: required, string, format: date-time\n\n## Create a custom repository role\n\n```\nPOST /orgs/{org}/custom-repository-roles\n```\n\nCreates 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.\"\nThe authenticated user must be an administrator for the organization to use this endpoint.\nOAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`org`** (string) (required)\n  The organization name. The name is not case sensitive.\n\n#### Body parameters\n\n- **`name`** (string) (required)\n  The name of the custom role.\n\n- **`description`** (string or null)\n  A short description about who this role is for or what permissions it grants.\n\n- **`base_role`** (string) (required)\n  The system role from which this role inherits permissions.\n  Can be one of: `read`, `triage`, `write`, `maintain`\n\n- **`permissions`** (array of strings) (required)\n  A list of additional permissions included in this role.\n\n### HTTP response status codes\n\n- **201** - Created\n\n- **404** - Resource not found\n\n- **422** - Validation failed, or the endpoint has been spammed.\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X POST \\\n  http(s)://HOSTNAME/api/v3/orgs/ORG/custom-repository-roles \\\n  -d '{\n  \"name\": \"Labeler\",\n  \"description\": \"A role for issue and pull request labelers\",\n  \"base_role\": \"read\",\n  \"permissions\": [\n    \"add_label\"\n  ]\n}'\n```\n\n**Response schema (Status: 201):**\n\n* `id`: required, integer\n* `name`: required, string\n* `description`: string or null\n* `base_role`: required, string, enum: `read`, `triage`, `write`, `maintain`\n* `permissions`: required, array of string\n* `organization`: required, `Simple User`:\n  * `name`: string or null\n  * `email`: string or null\n  * `login`: required, string\n  * `id`: required, integer, format: int64\n  * `node_id`: required, string\n  * `avatar_url`: required, string, format: uri\n  * `gravatar_id`: required, string or null\n  * `url`: required, string, format: uri\n  * `html_url`: required, string, format: uri\n  * `followers_url`: required, string, format: uri\n  * `following_url`: required, string\n  * `gists_url`: required, string\n  * `starred_url`: required, string\n  * `subscriptions_url`: required, string, format: uri\n  * `organizations_url`: required, string, format: uri\n  * `repos_url`: required, string, format: uri\n  * `events_url`: required, string\n  * `received_events_url`: required, string, format: uri\n  * `type`: required, string\n  * `site_admin`: required, boolean\n  * `starred_at`: string\n  * `user_view_type`: string\n* `created_at`: required, string, format: date-time\n* `updated_at`: required, string, format: date-time\n\n## Get a custom repository role\n\n```\nGET /orgs/{org}/custom-repository-roles/{role_id}\n```\n\nGets 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.\"\nThe authenticated user must be an administrator of the organization or of a repository of the organization to use this endpoint.\nOAuth app tokens and personal access tokens (classic) need the admin:org or repo scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`org`** (string) (required)\n  The organization name. The name is not case sensitive.\n\n- **`role_id`** (integer) (required)\n  The unique identifier of the role.\n\n### HTTP response status codes\n\n- **200** - OK\n\n- **404** - Resource not found\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  http(s)://HOSTNAME/api/v3/orgs/ORG/custom-repository-roles/ROLE_ID\n```\n\n**Response schema (Status: 200):**\n\nSame response schema as [Create a custom repository role](#create-a-custom-repository-role).\n\n## Update a custom repository role\n\n```\nPATCH /orgs/{org}/custom-repository-roles/{role_id}\n```\n\nUpdates 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.\"\nThe authenticated user must be an administrator for the organization to use this endpoint.\nOAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`org`** (string) (required)\n  The organization name. The name is not case sensitive.\n\n- **`role_id`** (integer) (required)\n  The unique identifier of the role.\n\n#### Body parameters\n\n- **`name`** (string)\n  The name of the custom role.\n\n- **`description`** (string or null)\n  A short description about who this role is for or what permissions it grants.\n\n- **`base_role`** (string)\n  The system role from which this role inherits permissions.\n  Can be one of: `read`, `triage`, `write`, `maintain`\n\n- **`permissions`** (array of strings)\n  A list of additional permissions included in this role.\n\n### HTTP response status codes\n\n- **200** - OK\n\n- **404** - Resource not found\n\n- **422** - Validation failed, or the endpoint has been spammed.\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X PATCH \\\n  http(s)://HOSTNAME/api/v3/orgs/ORG/custom-repository-roles/ROLE_ID \\\n  -d '{\n  \"name\": \"Labeler\",\n  \"description\": \"A role for issue and PR labelers\",\n  \"base_role\": \"read\",\n  \"permissions\": [\n    \"add_label\",\n    \"remove_label\"\n  ]\n}'\n```\n\n**Response schema (Status: 200):**\n\nSame response schema as [Create a custom repository role](#create-a-custom-repository-role).\n\n## Delete a custom repository role\n\n```\nDELETE /orgs/{org}/custom-repository-roles/{role_id}\n```\n\nDeletes a custom role from an organization. Once the custom role has been deleted, any\nuser, 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.\"\nThe authenticated user must be an administrator for the organization to use this endpoint.\nOAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`org`** (string) (required)\n  The organization name. The name is not case sensitive.\n\n- **`role_id`** (integer) (required)\n  The unique identifier of the role.\n\n### HTTP response status codes\n\n- **204** - No Content\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X DELETE \\\n  http(s)://HOSTNAME/api/v3/orgs/ORG/custom-repository-roles/ROLE_ID\n```\n\n**Response schema (Status: 204):**\n\n## List repository fine-grained permissions for an organization\n\n```\nGET /orgs/{org}/repository-fine-grained-permissions\n```\n\nLists the fine-grained permissions that can be used in custom repository roles for an organization. For more information, see \"About custom repository roles.\"\nThe authenticated user must be an administrator of the organization or of a repository of the organization to use this endpoint.\nOAuth app tokens and personal access tokens (classic) need the admin:org or repo scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`org`** (string) (required)\n  The organization name. The name is not case sensitive.\n\n### HTTP response status codes\n\n- **200** - OK\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  http(s)://HOSTNAME/api/v3/orgs/ORG/repository-fine-grained-permissions\n```\n\n**Response schema (Status: 200):**\n\nArray of `Repository Fine-Grained Permission`:\n  * `name`: required, string\n  * `description`: required, string"}