openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Application About Permissions API
description: 'Use the REST API to retrieve information about GitHub Apps and GitHub App
installations.'
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?tags=dotcom-rest-api
x-github-plan: ghes
x-github-release: 3.9
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
tags:
- name: Permissions
paths:
/orgs/{org}/actions/permissions:
get:
summary: GitHub Get Github Actions Permissions for an Organization
description: 'Gets the GitHub Actions permissions policy for repositories and allowed actions in an organization.
You must authenticate using an access token with the `admin:org` scope to use this endpoint. GitHub Apps must have the `administration` organization permission to use this API.'
operationId: getGithubActionsPermissionsForAnOrganization
tags:
- Permissions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/actions/permissions#get-github-actions-permissions-for-an-organization
parameters:
- $ref: '#/components/parameters/org'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/actions-organization-permissions'
examples:
default:
$ref: '#/components/examples/actions-organization-permissions'
x-github:
enabledForGitHubApps: true
githubCloudOnly: false
category: actions
subcategory: permissions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Set Github Actions Permissions for an Organization
description: 'Sets the GitHub Actions permissions policy for repositories and allowed actions in an organization.
If the organization belongs to an enterprise that has set restrictive permissions at the enterprise level, such as `allowed_actions` to `selected` actions, then you cannot override them for the organization.
OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.'
operationId: setGithubActionsPermissionsForAnOrganization
tags:
- Permissions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/actions/permissions#set-github-actions-permissions-for-an-organization
parameters:
- $ref: '#/components/parameters/org'
responses:
'204':
description: Response
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
enabled_repositories:
$ref: '#/components/schemas/enabled-repositories'
allowed_actions:
$ref: '#/components/schemas/allowed-actions'
required:
- enabled_repositories
examples:
default:
value:
enabled_repositories: all
allowed_actions: selected
x-github:
enabledForGitHubApps: true
githubCloudOnly: false
category: actions
subcategory: permissions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/actions/permissions/workflow:
get:
summary: GitHub Get Default Workflow Permissions for an Organization
description: 'Gets the default workflow permissions granted to the `GITHUB_TOKEN` when running workflows in an organization,
as well as whether GitHub Actions can submit approving pull request reviews. For more information, see
"[Setting the permissions of the GITHUB_TOKEN for your organization](https://docs.github.com/enterprise-server@3.9/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#setting-the-permissions-of-the-github_token-for-your-organization)."
OAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.'
tags:
- Permissions
operationId: getDefaultWorkflowPermissionsForAnOrganization
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/actions/permissions#get-default-workflow-permissions-for-an-organization
parameters:
- $ref: '#/components/parameters/org'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/actions-get-default-workflow-permissions'
examples:
default:
$ref: '#/components/examples/actions-default-workflow-permissions'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: actions
subcategory: permissions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Set Default Workflow Permissions for an Organization
description: 'Sets the default workflow permissions granted to the `GITHUB_TOKEN` when running workflows in an organization, and sets if GitHub Actions
can submit approving pull request reviews. For more information, see
"[Setting the permissions of the GITHUB_TOKEN for your organization](https://docs.github.com/enterprise-server@3.9/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#setting-the-permissions-of-the-github_token-for-your-organization)."
OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.'
tags:
- Permissions
operationId: setDefaultWorkflowPermissionsForAnOrganization
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/actions/permissions#set-default-workflow-permissions-for-an-organization
parameters:
- $ref: '#/components/parameters/org'
responses:
'204':
description: Success response
'409':
description: Conflict response when changing a setting is prevented by the owning enterprise
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/actions-set-default-workflow-permissions'
examples:
default:
$ref: '#/components/examples/actions-default-workflow-permissions'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: actions
subcategory: permissions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/repository-fine-grained-permissions:
get:
summary: GitHub List Repository Fine-grained Permissions for an Organization
description: 'Lists the fine-grained permissions that can be used in custom repository roles for an organization. For more information, see "[About custom repository roles](https://docs.github.com/enterprise-server@3.9/organizations/managing-peoples-access-to-your-organization-with-roles/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.'
tags:
- Permissions
operationId: listRepositoryFinegrainedPermissionsForAnOrganization
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/custom-roles#list-repository-fine-grained-permissions-for-an-organization
parameters:
- $ref: '#/components/parameters/org'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/repository-fine-grained-permission'
examples:
default:
$ref: '#/components/examples/repository-fine-grained-permission-example'
x-github:
githubCloudOnly: true
enabledForGitHubApps: true
category: orgs
subcategory: custom-roles
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/teams/{team_slug}/projects/{project_id}:
get:
summary: GitHub Check Team Permissions for Project
description: 'Checks whether a team has `read`, `write`, or `admin` permissions for an organization project. The response includes projects inherited from a parent team.
**Note:** You can also specify a team by `org_id` and `team_id` using the route `GET /organizations/{org_id}/team/{team_id}/projects/{project_id}`.'
tags:
- Permissions
operationId: checkTeamPermissionsForProject
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/teams/teams#check-team-permissions-for-a-project
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/team-slug'
- $ref: '#/components/parameters/project-id'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/team-project'
examples:
default:
$ref: '#/components/examples/team-project'
'404':
description: Not Found if project is not managed by this team
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: teams
subcategory: teams
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Add or Update Team Project Permissions
description: 'Adds an organization project to a team. To add a project to a team or update the team''s permission on a project, the authenticated user must have `admin` permissions for the project. The project and team must be part of the same organization.
**Note:** You can also specify a team by `org_id` and `team_id` using the route `PUT /organizations/{org_id}/team/{team_id}/projects/{project_id}`.'
tags:
- Permissions
operationId: addOrUpdateTeamProjectPermissions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/teams/teams#add-or-update-team-project-permissions
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/team-slug'
- $ref: '#/components/parameters/project-id'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
permission:
type: string
description: 'The permission to grant to the team for this project. Default: the team''s `permission` attribute will be used to determine what permission to grant the team on this project. Note that, if you choose not to pass any parameters, you''ll need to set `Content-Length` to zero when calling 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)."'
enum:
- read
- write
- admin
nullable: true
examples:
default:
summary: Updates the permissions for the team to write for the project
value:
permission: write
responses:
'204':
description: Response
'403':
description: Forbidden if the project is not owned by the organization
content:
application/json:
schema:
type: object
properties:
message:
type: string
documentation_url:
type: string
examples:
response-if-the-project-is-not-owned-by-the-organization:
value:
message: Must have admin rights to Repository.
documentation_url: https://docs.github.com/enterprise-server@3.9/rest/teams/teams#add-or-update-team-project-permissions
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: teams
subcategory: teams
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}:
get:
summary: GitHub Check Team Permissions for Repository
description: 'Checks whether a team has `admin`, `push`, `maintain`, `triage`, or `pull` permission for a repository. Repositories inherited through a parent team will also be checked.
You can also get information about the specified repository, including what permissions the team grants on it, by passing the following custom [media type](https://docs.github.com/enterprise-server@3.9/rest/overview/media-types/) via the `application/vnd.github.v3.repository+json` accept header.
If a team doesn''t have permission for the repository, you will receive a `404 Not Found` response status.
If the repository is private, you must have at least `read` permission for that repository, and your token must have the `repo` or `admin:org` scope. Otherwise, you will receive a `404 Not Found` response status.
**Note:** You can also specify a team by `org_id` and `team_id` using the route `GET /organizations/{org_id}/team/{team_id}/repos/{owner}/{repo}`.'
tags:
- Permissions
operationId: checkTeamPermissionsForRepository
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/teams/teams#check-team-permissions-for-a-repository
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/team-slug'
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
responses:
'200':
description: Alternative response with repository permissions
content:
application/json:
schema:
$ref: '#/components/schemas/team-repository'
examples:
alternative-response-with-repository-permissions:
$ref: '#/components/examples/team-repository-alternative-response-with-repository-permissions'
'204':
description: Response if team has permission for the repository. This is the response when the repository media type hasn't been provded in the Accept header.
'404':
description: Not Found if team does not have permission for the repository
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: teams
subcategory: teams
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Add or Update Team Repository Permissions
description: 'To add a repository to a team or update the team''s permission on a repository, the authenticated user must have admin access to the repository, and must be able to see the team. The repository must be owned by the organization, or a direct fork of a repository owned by the organization. You will get a `422 Unprocessable Entity` status if you attempt to add a repository to a team that is not owned by the organization. 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)."
**Note:** You can also specify a team by `org_id` and `team_id` using the route `PUT /organizations/{org_id}/team/{team_id}/repos/{owner}/{repo}`.
For more information about the 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)".'
tags:
- Permissions
operationId: addOrUpdateTeamRepositoryPermissions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/teams/teams#add-or-update-team-repository-permissions
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/team-slug'
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
permission:
type: string
description: 'The permission to grant the team on this repository. We accept the following permissions to be set: `pull`, `triage`, `push`, `maintain`, `admin` and you can also specify a custom repository role name, if the owning organization has defined any. If no permission is specified, the team''s `permission` attribute will be used to determine what permission to grant the team on this repository.'
default: push
examples:
default:
summary: Adding a team to an organization repository with the write role
value:
permission: push
responses:
'204':
description: Response
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: teams
subcategory: teams
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/teams/{team_id}/projects/{project_id}:
get:
summary: GitHub Check Team Permissions for Project (legacy)
description: '**Deprecation Notice:** This endpoint route is deprecated and will be removed from the Teams API. We recommend migrating your existing code to use the new [Check team permissions for a project](https://docs.github.com/enterprise-server@3.9/rest/teams/teams#check-team-permissions-for-a-project) endpoint.
Checks whether a team has `read`, `write`, or `admin` permissions for an organization project. The response includes projects inherited from a parent team.'
tags:
- Permissions
operationId: checkTeamPermissionsForProjectLegacy
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/teams/teams#check-team-permissions-for-a-project-legacy
parameters:
- $ref: '#/components/parameters/team-id'
- $ref: '#/components/parameters/project-id'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/team-project'
examples:
default:
$ref: '#/components/examples/team-project'
'404':
description: Not Found if project is not managed by this team
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
removalDate: '2021-02-01'
deprecationDate: '2020-01-21'
category: teams
subcategory: teams
deprecated: true
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Add or Update Team Project Permissions (legacy)
description: '**Deprecation Notice:** This endpoint route is deprecated and will be removed from the Teams API. We recommend migrating your existing code to use the new [Add or update team project permissions](https://docs.github.com/enterprise-server@3.9/rest/teams/teams#add-or-update-team-project-permissions) endpoint.
Adds an organization project to a team. To add a project to a team or update the team''s permission on a project, the authenticated user must have `admin` permissions for the project. The project and team must be part of the same organization.'
tags:
- Permissions
operationId: addOrUpdateTeamProjectPermissionsLegacy
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/teams/teams#add-or-update-team-project-permissions-legacy
parameters:
- $ref: '#/components/parameters/team-id'
- $ref: '#/components/parameters/project-id'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
permission:
type: string
description: 'The permission to grant to the team for this project. Default: the team''s `permission` attribute will be used to determine what permission to grant the team on this project. Note that, if you choose not to pass any parameters, you''ll need to set `Content-Length` to zero when calling 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)."'
enum:
- read
- write
- admin
examples:
default:
summary: Example of setting permission to read
value:
permission: read
responses:
'204':
description: Response
'403':
description: Forbidden if the project is not owned by the organization
content:
application/json:
schema:
type: object
properties:
message:
type: string
documentation_url:
type: string
examples:
response-if-the-project-is-not-owned-by-the-organization:
value:
message: Must have admin rights to Repository.
documentation_url: https://docs.github.com/enterprise-server@3.9/rest/teams/teams#add-or-update-team-project-permissions
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
removalDate: '2021-02-01'
deprecationDate: '2020-01-21'
category: teams
subcategory: teams
deprecated: true
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/actions/permissions:
get:
summary: GitHub Get Github Actions Permissions for Repository
description: 'Gets the GitHub Actions permissions policy for a repository, including whether GitHub Actions is enabled and the actions allowed to run in the repository.
You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `administration` repository permission to use this API.'
operationId: getGithubActionsPermissionsForRepository
tags:
- Permissions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/actions/permissions#get-github-actions-permissions-for-a-repository
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- 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:
$ref: '#/components/schemas/actions-repository-permissions'
examples:
default:
$ref: '#/components/examples/actions-repository-permissions'
x-github:
enabledForGitHubApps: true
githubCloudOnly: false
category: actions
subcategory: permissions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Set Github Actions Permissions for Repository
description: 'Sets the GitHub Actions permissions policy for enabling GitHub Actions and allowed actions in the repository.
If the repository belongs to an organization or enterprise that has set restrictive permissions at the organization or enterprise levels, such as `allowed_actions` to `selected` actions, then you cannot override them for the repository.
OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
operationId: setGithubActionsPermissionsForRepository
tags:
- Permissions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/actions/permissions#set-github-actions-permissions-for-a-repository
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- 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
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
enabled:
$ref: '#/components/schemas/actions-enabled'
allowed_actions:
$ref: '#/components/schemas/allowed-actions'
required:
- enabled
examples:
default:
value:
enabled: true
allowed_actions: selected
x-github:
enabledForGitHubApps: true
githubCloudOnly: false
category: actions
subcategory: permissions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/actions/permissions/workflow:
get:
summary: GitHub Get Default Workflow Permissions for Repository
description: 'Gets the default workflow permissions granted to the `GITHUB_TOKEN` when running workflows in a repository,
as well as if GitHub Actions can submit approving pull request reviews.
For more information, see "[Setting the permissions of the GITHUB_TOKEN for your repository](https://docs.github.com/enterprise-server@3.9/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#setting-the-permissions-of-the-github_token-for-your-repository)."
OAuth tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
tags:
- Permissions
operationId: getDefaultWorkflowPermissionsForRepository
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/actions/permissions#get-default-workflow-permissions-for-a-repository
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- 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:
$ref: '#/components/schemas/actions-get-default-workflow-permissions'
examples:
default:
$ref: '#/components/examples/actions-default-workflow-permissions'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: actions
subcategory: permissions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Set Default Workflow Permissions for Repository
description: 'Sets the default workflow permissions granted to the `GITHUB_TOKEN` when running workflows in a repository, and sets if GitHub Actions
can submit approving pull request reviews.
For more information, see "[Setting the permissions of the GITHUB_TOKEN for your repository](https://docs.github.com/enterprise-server@3.9/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#setting-the-permissions-of-the-github_token-for-your-repository)."
OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
tags:
- Permissions
operationId: setDefaultWorkflowPermissionsForRepository
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/actions/permissions#set-default-workflow-permissions-for-a-repository
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- 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: Success response
'409':
description: Conflict response when changing a setting is prevented by the owning organization or enterprise
requestBody:
required: true
content:
application/json:
schema:
$ref:
# --- truncated at 32 KB (688 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-permissions-api-openapi.yml