openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Application About Status 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: Status
paths:
/manage/v1/replication/status:
get:
summary: GitHub Get the Status of Services Running on All Replica Nodes
description: 'Gets the status of all services running on each replica node.
This endpoint may take several seconds to reply.'
operationId: getTheStatusOfServicesRunningOnAllReplicaNodes
tags:
- Status
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/manage-ghes#get-the-status-of-services-running-on-all-replica-nodes
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
default: HOSTNAME
description: Self-hosted Enterprise Server hostname
protocol:
default: http
description: Self-hosted Enterprise Server protocol
parameters:
- $ref: '#/components/parameters/uuid'
- $ref: '#/components/parameters/cluster-roles'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/ghes-replication-status'
examples:
default:
$ref: '#/components/examples/ghes-replication-status'
'401':
description: Unauthorized
'500':
description: Internal error
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: manage-ghes
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/migrations/{migration_id}:
get:
summary: GitHub Get an Organization Migration Status
description: 'Fetches the status of a migration.
The `state` of a migration can be one of the following values:
* `pending`, which means the migration hasn''t started yet.
* `exporting`, which means the migration is in progress.
* `exported`, which means the migration finished successfully.
* `failed`, which means the migration failed.'
tags:
- Status
operationId: getAnOrganizationMigrationStatus
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/migrations/orgs#get-an-organization-migration-status
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/migration-id'
- name: exclude
description: Exclude attributes from the API response to improve performance
in: query
schema:
type: array
items:
description: Allowed values that can be passed to the exclude param.
enum:
- repositories
example: repositories
type: string
responses:
'200':
description: '* `pending`, which means the migration hasn''t started yet.
* `exporting`, which means the migration is in progress.
* `exported`, which means the migration finished successfully.
* `failed`, which means the migration failed.'
content:
application/json:
schema:
$ref: '#/components/schemas/migration'
examples:
default:
$ref: '#/components/examples/migration-with-short-org'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: migrations
subcategory: orgs
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks:
get:
summary: GitHub Get Status Checks Protection
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.
tags:
- Status
operationId: getStatusChecksProtection
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#get-status-checks-protection
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/status-check-policy'
examples:
default:
$ref: '#/components/examples/status-check-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
patch:
summary: GitHub Update Status Check Protection
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.
Updating required status checks requires admin or owner permissions to the repository and branch protection to be enabled.'
tags:
- Status
operationId: updateStatusCheckProtection
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#update-status-check-protection
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:
type: object
properties:
strict:
type: boolean
description: Require branches to be up to date before merging.
contexts:
type: array
deprecated: true
description: '**Deprecated**: The list of status checks to require in order to merge into this branch. If any of these checks have recently been set by a particular GitHub App, they will be required to come from that app in future for the branch to merge. Use `checks` instead of `contexts` for more fine-grained control.
'
items:
type: string
checks:
type: array
description: The list of status checks to require in order to merge into this branch.
items:
type: object
required:
- context
properties:
context:
type: string
description: The name of the required check
app_id:
type: integer
description: The ID of the GitHub App that must provide this check. Omit this field to automatically select the GitHub App that has recently provided this check, or any app if it was not set by a GitHub App. Pass -1 to explicitly allow any app to set the status.
examples:
default:
value:
strict: true
contexts:
- continuous-integration/travis-ci
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/status-check-policy'
examples:
default:
$ref: '#/components/examples/status-check-policy'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Remove Status Check Protection
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.
tags:
- Status
operationId: removeStatusCheckProtection
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#remove-status-check-protection
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/required_status_checks/contexts:
get:
summary: GitHub Get All Status Check Contexts
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.
tags:
- Status
operationId: getAllStatusCheckContexts
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#get-all-status-check-contexts
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:
type: array
items:
type: string
examples:
default:
value:
- continuous-integration/travis-ci
'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
post:
summary: GitHub Add Status Check Contexts
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.
tags:
- Status
operationId: addStatusCheckContexts
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#add-status-check-contexts
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:
contexts:
type: array
description: The name of the status checks
items:
type: string
required:
- contexts
example:
contexts:
- contexts
- type: array
description: The name of the status checks
items:
type: string
examples:
default:
summary: Example adding status checks to a branch protection rule
value:
contexts:
- continuous-integration/travis-ci
- continuous-integration/jenkins
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
type: string
examples:
default:
value:
- continuous-integration/travis-ci
- continuous-integration/jenkins
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: contexts
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Set Status Check Contexts
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.
tags:
- Status
operationId: setStatusCheckContexts
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#set-status-check-contexts
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:
contexts:
type: array
description: The name of the status checks
items:
type: string
required:
- contexts
example:
contexts:
- contexts
- type: array
description: The name of the status checks
items:
type: string
examples:
default:
summary: Example updating status checks for a branch protection rule
value:
contexts:
- continuous-integration/travis-ci
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
type: string
examples:
default:
value:
- continuous-integration/travis-ci
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: contexts
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Remove Status Check Contexts
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.
tags:
- Status
operationId: removeStatusCheckContexts
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#remove-status-check-contexts
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:
contexts:
type: array
description: The name of the status checks
items:
type: string
required:
- contexts
example:
contexts:
- contexts
- type: array
description: The name of the status checks
items:
type: string
examples:
default:
summary: Example removing status checks from a branch protection rule
value:
contexts:
- continuous-integration/jenkins
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
type: string
examples:
default:
value:
- continuous-integration/travis-ci
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: contexts
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/commits/{ref}/status:
get:
summary: GitHub Get the Combined Status for Specific Reference
description: 'Users with pull access in a repository can access a combined view of commit statuses for a given ref. The ref can be a SHA, a branch name, or a tag name.
Additionally, a combined `state` is returned. The `state` is one of:
* **failure** if any of the contexts report as `error` or `failure`
* **pending** if there are no statuses or a context is `pending`
* **success** if the latest status for all contexts is `success`'
tags:
- Status
operationId: getTheCombinedStatusForSpecificReference
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/commits/statuses#get-the-combined-status-for-a-specific-reference
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/commit-ref'
- $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:
$ref: '#/components/schemas/combined-commit-status'
examples:
default:
$ref: '#/components/examples/combined-commit-status'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: commits
subcategory: statuses
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/deployments/{deployment_id}/statuses:
post:
summary: GitHub Create Deployment Status
description: 'Users with `push` access can create deployment statuses for a given deployment.
OAuth app tokens and personal access tokens (classic) need the `repo_deployment` scope to use this endpoint.'
tags:
- Status
operationId: createDeploymentStatus
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/deployments/statuses#create-a-deployment-status
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/deployment-id'
- 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: true
content:
application/json:
schema:
type: object
properties:
state:
type: string
description: The state of the status. When you set a transient deployment to `inactive`, the deployment will be shown as `destroyed` in GitHub.
enum:
- error
- failure
- inactive
- in_progress
- queued
- pending
- success
target_url:
type: string
description: The target URL to associate with this status. This URL should contain output to keep the user updated while the task is running or serve as historical information for what happened in the deployment. **Note:** It's recommended to use the `log_url` parameter, which replaces `target_url`.
default: ''
log_url:
type: string
description: 'The full URL of the deployment''s output. This parameter replaces `target_url`. We will continue to accept `target_url` to support legacy uses, but we recommend replacing `target_url` with `log_url`. Setting `log_url` will automatically set `target_url` to the same value. Default: `""`'
default: ''
description:
type: string
description: short description of the status. The maximum description length is 140 characters.
default: ''
environment:
type: string
description: Name for the target deployment environment, which can be changed when setting a deploy status. For example, `production`, `staging`, or `qa`. If not defined, the environment of the previous status on the deployment will be used, if it exists. Otherwise, the environment of the deployment will be used.
environment_url:
type: string
description: 'Sets the URL for accessing your environment. Default: `""`'
default: ''
auto_inactive:
type: boolean
description: 'Adds a new `inactive` status to all prior non-transient, non-production environment deployments with the same repository and `environment` name as the created status''s deployment. An `inactive` status is only added to deployments that had a `success` state. Default: `true`'
required:
- state
examples:
default:
value:
environment: production
state: success
log_url: https://example.com/deployment/42/output
description: Deployment finished successfully.
responses:
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/deployment-status'
examples:
default:
$ref: '#/components/examples/deployment-status'
headers:
Location:
example: https://api.github.com/repos/octocat/example/deployments/42/statuses/1
schema:
type: string
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: deployments
subcategory: statuses
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/deployments/{deployment_id}/statuses/{status_id}:
get:
summary: GitHub Get Deployment Status
description: 'Users with pull access can view a deployment status for a deployment:'
tags:
- Status
operationId: getDeploymentStatus
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/deployments/statuses#get-a-deployment-status
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/deployment-id'
- name: status_id
in: path
required: true
schema:
type: integer
example: 42
- 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/deployment-status'
examples:
default:
$ref: '#/components/examples/deployment-status'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: deployments
subcategory: statuses
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/replicas/caches:
get:
summary: GitHub List Repository Cache Replication Status
description: Lists the status of each repository
# --- truncated at 32 KB (723 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-status-api-openapi.yml