openapi: 3.1.0 info: version: 1.1.4 title: github-repos-api description: |- Use the REST API to create, manage and control the workflow of public and private GitHub repositories. license: name: MIT url: https://spdx.org/licenses/MIT termsOfService: https://docs.github.com/articles/github-terms-of-service contact: name: Support url: https://support.github.com/contact servers: - url: '{protocol}://{hostname}' variables: hostname: description: Self-hosted Enterprise Server hostname default: api.github.com protocol: description: Self-hosted Enterprise Server protocol default: https externalDocs: description: GitHub Enterprise Developer Docs url: https://docs.github.com/enterprise-server@3.9/rest/ tags: - name: Add - name: Checks - name: Collaborators - name: Get - name: Lists - name: Permissions - name: Remove - name: Repositories description: Source control repositories. - name: Users paths: /repos/{owner}/{repo}/collaborators: get: summary: GitHub List Repository Collaborators description: |- For organization-owned repositories, the list of collaborators includes outside collaborators, organization members that are direct collaborators, organization members with access through team memberships, organization members with access through default organization permissions, and organization owners. Organization members with write, maintain, or admin privileges on the organization-owned repository can use this endpoint. Team members will include the members of child teams. The authenticated user must have push access to the repository to use this endpoint. OAuth app tokens and personal access tokens (classic) need the `read:org` and `repo` scopes to use this endpoint. tags: - Collaborators - Lists - Repositories operationId: listRepositoryCollaborators externalDocs: description: API method documentation url: |- https://docs.github.com/enterprise-server@3.9/rest/collaborators/collaborators#list-repository-collaborators parameters: - $ref: '#/components/parameters/owner' - $ref: '#/components/parameters/repo' - name: affiliation description: |- Filter collaborators returned by their affiliation. `outside` means all outside collaborators of an organization-owned repository. `direct` means all collaborators with permissions to an organization-owned repository, regardless of organization membership status. `all` means all collaborators the authenticated user can see. in: query required: false schema: type: string enum: - outside - direct - all default: all example: outside - name: permission description: |- Filter collaborators by the permissions they have on the repository. If not specified, all collaborators will be returned. in: query required: false schema: type: string enum: - pull - triage - push - maintain - admin example: pull - $ref: '#/components/parameters/per-page' - $ref: '#/components/parameters/page' - in: header name: Authorization schema: type: string example: example_value - in: header name: X-GitHub-Api-Version schema: type: string default: '2022-11-28' example: example_value - in: header name: Accept schema: type: string default: application/vnd.github+json example: example_value responses: '200': description: Response content: application/json: schema: type: array items: $ref: '#/components/schemas/collaborator' examples: default: $ref: '#/components/examples/collaborator-items' headers: Link: $ref: '#/components/headers/link' '404': $ref: '#/components/responses/not_found' x-github: githubCloudOnly: false enabledForGitHubApps: true category: collaborators subcategory: collaborators x-api-evangelist-certified: '2025-07-16' x-api-naftiko-published: '2025-07-25' security: - bearerHttpAuthentication: [] x-microcks-operation: delay: 0 dispatcher: FALLBACK /repos/{owner}/{repo}/collaborators/{username}: get: summary: GitHub Check if User is Repository Collaborator description: |- For organization-owned repositories, the list of collaborators includes outside collaborators, organization members that are direct collaborators, organization members with access through team memberships, organization members with access through default organization permissions, and organization owners. Team members will include the members of child teams. The authenticated user must have push access to the repository to use this endpoint. OAuth app tokens and personal access tokens (classic) need the `read:org` and `repo` scopes to use this endpoint. tags: - Checks - Collaborators - Repositories - Users operationId: checkIfUserIsRepositoryCollaborator externalDocs: description: API method documentation url: |- https://docs.github.com/enterprise-server@3.9/rest/collaborators/collaborators#check-if-a-user-is-a-repository-collaborator parameters: - $ref: '#/components/parameters/owner' - $ref: '#/components/parameters/repo' - $ref: '#/components/parameters/username' - in: header name: Authorization schema: type: string example: example_value - in: header name: X-GitHub-Api-Version schema: type: string default: '2022-11-28' example: example_value - in: header name: Accept schema: type: string default: application/vnd.github+json example: example_value responses: '204': description: Response if user is a collaborator '404': description: Not Found if user is not a collaborator x-github: githubCloudOnly: false enabledForGitHubApps: true category: collaborators subcategory: collaborators security: - bearerHttpAuthentication: [] x-microcks-operation: delay: 0 dispatcher: FALLBACK put: summary: GitHub Add Repository Collaborator description: |- This endpoint triggers [notifications](https://docs.github.com/enterprise-server@3.9/github/managing-subscriptions-and-notifications-on-github/about-notifications). Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "[Rate limits for the API](https://docs.github.com/enterprise-server@3.9/rest/overview/rate-limits-for-the-rest-api#about-secondary-rate-limits)" and "[Best practices for using the REST API](https://docs.github.com/enterprise-server@3.9/rest/guides/best-practices-for-using-the-rest-api)." Adding an outside collaborator may be restricted by enterprise administrators. For more information, see "[Enforcing repository management policies in your enterprise](https://docs.github.com/enterprise-server@3.9/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-inviting-outside-collaborators-to-repositories)." For more information on permission levels, see "[Repository permission levels for an organization](https://docs.github.com/enterprise-server@3.9/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization#permission-levels-for-repositories-owned-by-an-organization)". There are restrictions on which permissions can be granted to organization members when an organization base role is in place. In this case, the permission being given must be equal to or higher than the org base permission. Otherwise, the request will fail with: ``` Cannot assign {member} permission of {role name} ``` Note that, if you choose not to pass any parameters, you'll need to set `Content-Length` to zero when calling out to this endpoint. For more information, see "[HTTP method](https://docs.github.com/enterprise-server@3.9/rest/guides/getting-started-with-the-rest-api#http-method)." **Updating an existing collaborator's permission level** The endpoint can also be used to change the permissions of an existing collaborator without first removing and re-adding the collaborator. To change the permissions, use the same endpoint and pass a different `permission` parameter. The response will be a `204`, with no other indication that the permission level changed. tags: - Add - Collaborators - Repositories operationId: addRepositoryCollaborator externalDocs: description: API method documentation url: |- https://docs.github.com/enterprise-server@3.9/rest/collaborators/collaborators#add-a-repository-collaborator parameters: - $ref: '#/components/parameters/owner' - $ref: '#/components/parameters/repo' - $ref: '#/components/parameters/username' - in: header name: Authorization schema: type: string example: example_value - in: header name: X-GitHub-Api-Version schema: type: string default: '2022-11-28' example: example_value - in: header name: Accept schema: type: string default: application/vnd.github+json example: example_value requestBody: required: false content: application/json: schema: type: object properties: permission: type: string description: |- The permission to grant the collaborator. **Only valid on organization-owned repositories.** default: push examples: new-invitation-is-created: summary: Add a collaborator with triage permissions value: permission: triage responses: '204': description: |- Response when: - an existing collaborator is added as a collaborator - an organization member is added as an individual collaborator - an existing team member (whose team is also a repository collaborator) is added as an individual collaborator '403': $ref: '#/components/responses/forbidden' '422': $ref: '#/components/responses/validation_failed' x-github: triggersNotification: true githubCloudOnly: false enabledForGitHubApps: true category: collaborators subcategory: collaborators security: - bearerHttpAuthentication: [] x-microcks-operation: delay: 0 dispatcher: FALLBACK delete: summary: GitHub Remove Repository Collaborator description: |- Removes a collaborator from a repository. To use this endpoint, the authenticated user must either be an administrator of the repository or target themselves for removal. This endpoint also: - Cancels any outstanding invitations - Unasigns the user from any issues - Removes access to organization projects if the user is not an organization member and is not a collaborator on any other organization repositories. - Unstars the repository - Updates access permissions to packages Removing a user as a collaborator has the following effects on forks: - If the user had access to a fork through their membership to this repository, the user will also be removed from the fork. - If the user had their own fork of the repository, the fork will be deleted. - If the user still has read access to the repository, open pull requests by this user from a fork will be denied. **Note**: user can still have access to the repository through organization permissions like base repository permissions. Although the API responds immediately, the additional permission updates might take some extra time to complete in the background. For more information on fork permissions, see "[About permissions and visibility of forks](https://docs.github.com/enterprise-server@3.9/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks)". tags: - Collaborators - Remove - Repositories operationId: removeRepositoryCollaborator externalDocs: description: API method documentation url: |- https://docs.github.com/enterprise-server@3.9/rest/collaborators/collaborators#remove-a-repository-collaborator parameters: - $ref: '#/components/parameters/owner' - $ref: '#/components/parameters/repo' - $ref: '#/components/parameters/username' - in: header name: Authorization schema: type: string example: example_value - in: header name: X-GitHub-Api-Version schema: type: string default: '2022-11-28' example: example_value - in: header name: Accept schema: type: string default: application/vnd.github+json example: example_value responses: '204': description: No Content when collaborator was removed from the repository. '403': $ref: '#/components/responses/forbidden' '422': $ref: '#/components/responses/validation_failed' x-github: githubCloudOnly: false enabledForGitHubApps: true category: collaborators subcategory: collaborators security: - bearerHttpAuthentication: [] x-microcks-operation: delay: 0 dispatcher: FALLBACK /repos/{owner}/{repo}/collaborators/{username}/permission: get: summary: GitHub Get Repository Permissions for User description: |- Checks the repository permission of a collaborator. The possible repository permissions are `admin`, `write`, `read`, and `none`. *Note*: The `permission` attribute provides the legacy base roles of `admin`, `write`, `read`, and `none`, where the `maintain` role is mapped to `write` and the `triage` role is mapped to `read`. To determine the role assigned to the collaborator, see the `role_name` attribute, which will provide the full role name, including custom roles. The `permissions` hash can also be used to determine which base level of access the collaborator has to the repository. tags: - Get - Permissions - Repositories - Users operationId: getRepositoryPermissionsForUser externalDocs: description: API method documentation url: |- https://docs.github.com/enterprise-server@3.9/rest/collaborators/collaborators#get-repository-permissions-for-a-user parameters: - $ref: '#/components/parameters/owner' - $ref: '#/components/parameters/repo' - $ref: '#/components/parameters/username' - in: header name: Authorization schema: type: string example: example_value - in: header name: X-GitHub-Api-Version schema: type: string default: '2022-11-28' example: example_value - in: header name: Accept schema: type: string default: application/vnd.github+json example: example_value responses: '200': description: if user has admin permissions content: application/json: schema: $ref: '#/components/schemas/repository-collaborator-permission' examples: response-if-user-has-admin-permissions: $ref: |- #/components/examples/repository-collaborator-permission-response-if-user-has-admin-permissions '404': $ref: '#/components/responses/not_found' x-github: githubCloudOnly: false enabledForGitHubApps: true category: collaborators subcategory: collaborators security: - bearerHttpAuthentication: [] x-microcks-operation: delay: 0 dispatcher: FALLBACK components: schemas: basic-error: title: Basic Error description: Basic Error type: object properties: message: type: string example: Example body text documentation_url: type: string example: https://api.github.com/repos/octocat/Hello-World url: type: string example: https://api.github.com/repos/octocat/Hello-World status: type: string example: open validation-error: title: Validation Error description: Validation Error type: object required: - message - documentation_url properties: message: type: string example: Example body text documentation_url: type: string example: https://api.github.com/repos/octocat/Hello-World errors: type: array items: type: object required: - code properties: resource: type: string field: type: string message: type: string code: type: string index: type: integer value: oneOf: - type: string - type: integer - type: array items: type: string collaborator: title: Collaborator description: Collaborator type: object properties: login: type: string example: octocat id: type: integer format: int64 example: 1 email: type: string example: octocat@github.com name: type: string example: octocat node_id: type: string example: MDQ6VXNlcjE= avatar_url: type: string format: uri example: https://github.com/images/error/octocat_happy.gif gravatar_id: type: string example: 41d064eb2195891e12d0413f63227ea7 url: type: string format: uri example: https://api.github.com/users/octocat html_url: type: string format: uri example: https://github.com/octocat followers_url: type: string format: uri example: https://api.github.com/users/octocat/followers following_url: type: string example: https://api.github.com/users/octocat/following{/other_user} gists_url: type: string example: https://api.github.com/users/octocat/gists{/gist_id} starred_url: type: string example: https://api.github.com/users/octocat/starred{/owner}{/repo} subscriptions_url: type: string format: uri example: https://api.github.com/users/octocat/subscriptions organizations_url: type: string format: uri example: https://api.github.com/users/octocat/orgs repos_url: type: string format: uri example: https://api.github.com/users/octocat/repos events_url: type: string example: https://api.github.com/users/octocat/events{/privacy} received_events_url: type: string format: uri example: https://api.github.com/users/octocat/received_events type: type: string example: User site_admin: type: boolean example: true permissions: type: object properties: pull: type: boolean triage: type: boolean push: type: boolean maintain: type: boolean admin: type: boolean required: - pull - push - admin role_name: type: string example: admin required: - avatar_url - events_url - followers_url - following_url - gists_url - gravatar_id - html_url - id - node_id - login - organizations_url - received_events_url - repos_url - site_admin - starred_url - subscriptions_url - type - url nullable-collaborator: title: Collaborator description: Collaborator type: object properties: login: type: string example: octocat id: type: integer format: int64 example: 1 email: type: string example: octocat@github.com name: type: string example: octocat node_id: type: string example: MDQ6VXNlcjE= avatar_url: type: string format: uri example: https://github.com/images/error/octocat_happy.gif gravatar_id: type: string example: 41d064eb2195891e12d0413f63227ea7 url: type: string format: uri example: https://api.github.com/users/octocat html_url: type: string format: uri example: https://github.com/octocat followers_url: type: string format: uri example: https://api.github.com/users/octocat/followers following_url: type: string example: https://api.github.com/users/octocat/following{/other_user} gists_url: type: string example: https://api.github.com/users/octocat/gists{/gist_id} starred_url: type: string example: https://api.github.com/users/octocat/starred{/owner}{/repo} subscriptions_url: type: string format: uri example: https://api.github.com/users/octocat/subscriptions organizations_url: type: string format: uri example: https://api.github.com/users/octocat/orgs repos_url: type: string format: uri example: https://api.github.com/users/octocat/repos events_url: type: string example: https://api.github.com/users/octocat/events{/privacy} received_events_url: type: string format: uri example: https://api.github.com/users/octocat/received_events type: type: string example: User site_admin: type: boolean example: true permissions: type: object properties: pull: type: boolean triage: type: boolean push: type: boolean maintain: type: boolean admin: type: boolean required: - pull - push - admin role_name: type: string example: admin required: - avatar_url - events_url - followers_url - following_url - gists_url - gravatar_id - html_url - id - node_id - login - organizations_url - received_events_url - repos_url - site_admin - starred_url - subscriptions_url - type - url repository-collaborator-permission: title: Repository Collaborator Permission description: Repository Collaborator Permission type: object properties: permission: type: string example: example_value role_name: type: string example: admin user: $ref: '#/components/schemas/nullable-collaborator' required: - permission - role_name - user examples: collaborator-items: value: - login: octocat id: 1 node_id: MDQ6VXNlcjE= avatar_url: https://github.com/images/error/octocat_happy.gif gravatar_id: '' 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 site_admin: false permissions: pull: true triage: true push: true maintain: false admin: false role_name: write repository-collaborator-permission-response-if-user-has-admin-permissions: value: permission: admin role_name: admin user: login: octocat id: 1 node_id: MDQ6VXNlcjE= avatar_url: https://github.com/images/error/octocat_happy.gif gravatar_id: '' 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 site_admin: false parameters: per-page: name: per_page description: |- The number of results per page (max 100). For more information, see "[Using pagination in the REST API](https://docs.github.com/enterprise-server@3.9/rest/using-the-rest-api/using-pagination-in-the-rest-api)." in: query schema: type: integer default: 30 page: name: page description: |- The page number of the results to fetch. For more information, see "[Using pagination in the REST API](https://docs.github.com/enterprise-server@3.9/rest/using-the-rest-api/using-pagination-in-the-rest-api)." in: query schema: type: integer default: 1 username: name: username description: The handle for the GitHub user account. in: path required: true schema: type: string owner: name: owner description: The account owner of the repository. The name is not case sensitive. in: path required: true schema: type: string repo: name: repo description: |- The name of the repository without the `.git` extension. The name is not case sensitive. in: path required: true schema: type: string headers: link: example: |- ; rel="next", ; rel="last" schema: type: string responses: not_found: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/basic-error' validation_failed: description: Validation failed, or the endpoint has been spammed. content: application/json: schema: $ref: '#/components/schemas/validation-error' forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/basic-error' securitySchemes: bearerHttpAuthentication: description: Bearer Token type: http scheme: Bearer