openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Application About Restrictions 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: Restrictions
paths:
/repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps:
post:
summary: GitHub Add App Access Restrictions
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Grants the specified apps push access for this branch. Only GitHub Apps that are installed on the repository and that have been granted write access to the repository contents can be added as authorized actors on a protected branch.'
tags:
- Restrictions
operationId: addAppAccessRestrictions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#add-app-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
requestBody:
required: false
content:
application/json:
schema:
oneOf:
- type: object
properties:
apps:
type: array
description: 'The GitHub Apps that have push access to this branch. Use the slugified version of the app name. **Note**: The list of users, apps, and teams in total is limited to 100 items.'
items:
type: string
required:
- apps
example:
apps:
- my-app
- type: array
items:
type: string
examples:
default:
value:
apps:
- octoapp
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/integration'
examples:
default:
$ref: '#/components/examples/integration-items'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: apps
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Set App Access Restrictions
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Replaces the list of apps that have push access to this branch. This removes all apps that previously had push access and grants push access to the new list of apps. Only GitHub Apps that are installed on the repository and that have been granted write access to the repository contents can be added as authorized actors on a protected branch.'
tags:
- Restrictions
operationId: setAppAccessRestrictions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#set-app-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
requestBody:
required: false
content:
application/json:
schema:
oneOf:
- type: object
properties:
apps:
type: array
description: 'The GitHub Apps that have push access to this branch. Use the slugified version of the app name. **Note**: The list of users, apps, and teams in total is limited to 100 items.'
items:
type: string
required:
- apps
example:
apps:
- my-app
- type: array
items:
type: string
examples:
default:
value:
apps:
- octoapp
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/integration'
examples:
default:
$ref: '#/components/examples/integration-items'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: apps
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Remove App Access Restrictions
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Removes the ability of an app to push to this branch. Only GitHub Apps that are installed on the repository and that have been granted write access to the repository contents can be added as authorized actors on a protected branch.'
tags:
- Restrictions
operationId: removeAppAccessRestrictions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#remove-app-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
properties:
apps:
type: array
description: 'The GitHub Apps that have push access to this branch. Use the slugified version of the app name. **Note**: The list of users, apps, and teams in total is limited to 100 items.'
items:
type: string
required:
- apps
example:
apps:
- my-app
- type: array
items:
type: string
examples:
default:
value:
apps:
- my-app
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/integration'
examples:
default:
$ref: '#/components/examples/integration-items'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: apps
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/branches/{branch}/protection/restrictions:
get:
summary: GitHub Get Access Restrictions
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Lists who has access to this protected branch.
**Note**: Users, apps, and teams `restrictions` are only available for organization-owned repositories.'
tags:
- Restrictions
operationId: getAccessRestrictions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#get-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- 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/branch-restriction-policy'
examples:
default:
$ref: '#/components/examples/branch-restriction-policy'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete Access Restrictions
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Disables the ability to restrict who can push to this branch.'
tags:
- Restrictions
operationId: deleteAccessRestrictions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#delete-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- 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
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams:
post:
summary: GitHub Add Team Access Restrictions
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Grants the specified teams push access for this branch. You can also give push access to child teams.'
tags:
- Restrictions
operationId: addTeamAccessRestrictions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#add-team-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- 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:
oneOf:
- type: object
properties:
teams:
type: array
description: The slug values for teams
items:
type: string
required:
- teams
example:
teams:
- my-team
- type: array
description: The slug values for teams
items:
type: string
examples:
default:
summary: Example adding a team in a branch protection rule
value:
teams:
- justice-league
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/team'
examples:
default:
$ref: '#/components/examples/team-items'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: teams
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Set Team Access Restrictions
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Replaces the list of teams that have push access to this branch. This removes all teams that previously had push access and grants push access to the new list of teams. Team restrictions include child teams.'
tags:
- Restrictions
operationId: setTeamAccessRestrictions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#set-team-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- 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:
oneOf:
- type: object
properties:
teams:
type: array
description: The slug values for teams
items:
type: string
required:
- teams
example:
teams:
- justice-league
- type: array
description: The slug values for teams
items:
type: string
examples:
default:
summary: Example replacing a team in a branch protection rule
value:
teams:
- justice-league
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/team'
examples:
default:
$ref: '#/components/examples/team-items'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: teams
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Remove Team Access Restrictions
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Removes the ability of a team to push to this branch. You can also remove push access for child teams.'
tags:
- Restrictions
operationId: removeTeamAccessRestrictions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#remove-team-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- 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:
content:
application/json:
schema:
oneOf:
- type: object
properties:
teams:
type: array
description: The slug values for teams
items:
type: string
required:
- teams
example:
teams:
- my-team
- type: array
description: The slug values for teams
items:
type: string
examples:
default:
summary: Example removing a team in a branch protection rule
value:
teams:
- octocats
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/team'
examples:
default:
$ref: '#/components/examples/team-items'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: teams
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users:
post:
summary: GitHub Add User Access Restrictions
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Grants the specified people push access for this branch.
| Type | Description |
| - | -- |
| `array` | Usernames for people who can have push access. **Note**: The list of users, apps, and teams in total is limited to 100 items. |'
tags:
- Restrictions
operationId: addUserAccessRestrictions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#add-user-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- 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:
oneOf:
- type: object
properties:
users:
type: array
description: The username for users
items:
type: string
required:
- users
example:
users:
- mona
- type: array
items:
type: string
examples:
default:
summary: Example adding a user in a branch protection rule
value:
users:
- octocat
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/simple-user'
examples:
default:
$ref: '#/components/examples/simple-user-items'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: users
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Set User Access Restrictions
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Replaces the list of people that have push access to this branch. This removes all people that previously had push access and grants push access to the new list of people.
| Type | Description |
| - | -- |
| `array` | Usernames for people who can have push access. **Note**: The list of users, apps, and teams in total is limited to 100 items. |'
tags:
- Restrictions
operationId: setUserAccessRestrictions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#set-user-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- 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:
oneOf:
- type: object
properties:
users:
type: array
description: The username for users
items:
type: string
required:
- users
example:
users:
- mona
- type: array
items:
type: string
examples:
default:
summary: Example replacing a user in a branch protection rule
value:
users:
- octocat
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/simple-user'
examples:
default:
$ref: '#/components/examples/simple-user-items'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: users
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Remove User Access Restrictions
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Removes the ability of a user to push to this branch.
| Type | Description |
| - |
|
| `array` | Usernames of the people who should no longer have push access. **Note**: The list of users, apps, and teams in total is limited to 100 items. |'
tags:
- Restrictions
operationId: removeUserAccessRestrictions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#remove-user-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- 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:
content:
application/json:
schema:
oneOf:
- type: object
properties:
users:
type: array
description: The username for users
items:
type: string
required:
- users
example:
users:
- mona
- type: array
items:
type: string
examples:
default:
summary: Example removing a user in a branch protection rule
value:
users:
- octocat
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/simple-user'
examples:
default:
$ref: '#/components/examples/simple-user-items'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: users
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
nullable-simple-user:
title: Simple User
description: A GitHub user.
type: object
properties:
name:
nullable: true
type: string
example: octocat
email:
nullable: true
type: string
example: octocat@github.com
login:
type: string
example: octocat
id:
type: integ
# --- truncated at 32 KB (662 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-restrictions-api-openapi.yml