openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Application About Deployments 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: Deployments
paths:
/repos/{owner}/{repo}/actions/runs/{run_id}/pending_deployments:
get:
summary: GitHub Get Pending Deployments for Workflow Run
description: 'Get all deployment environments for a workflow run that are waiting for protection rules to pass.
Anyone with read access to the repository can use this endpoint.
If the repository is private, OAuth tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
tags:
- Deployments
operationId: getPendingDeploymentsForWorkflowRun
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/actions/workflow-runs#get-pending-deployments-for-a-workflow-run
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/run-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
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/pending-deployment'
examples:
default:
$ref: '#/components/examples/pending-deployment-items'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: actions
subcategory: workflow-runs
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Review Pending Deployments for Workflow Run
description: 'Approve or reject pending deployments that are waiting on approval by a required reviewer.
Required reviewers with read access to the repository contents and deployments can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
tags:
- Deployments
operationId: reviewPendingDeploymentsForWorkflowRun
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/actions/workflow-runs#review-pending-deployments-for-a-workflow-run
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/run-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:
environment_ids:
type: array
description: The list of environment ids to approve or reject
example:
- 161171787
- 161171795
items:
type: integer
example: 161171787
state:
type: string
description: Whether to approve or reject deployment to the specified environments.
enum:
- approved
- rejected
example: approved
comment:
type: string
description: comment to accompany the deployment review
example: Ship it!
required:
- environment_ids
- state
- comment
examples:
default:
value:
environment_ids:
- 161171787
state: approved
comment: Ship it!
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/deployment'
examples:
default:
$ref: '#/components/examples/deployment-items'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: actions
subcategory: workflow-runs
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/deployments:
get:
summary: GitHub List Deployments
description: 'Simple filtering of deployments is available via query parameters:'
tags:
- Deployments
operationId: listDeployments
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/deployments/deployments#list-deployments
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- name: sha
description: The SHA recorded at creation time.
in: query
required: false
schema:
type: string
default: none
example: abc123def456789012345678901234567890
- name: ref
description: The name of the ref. This can be a branch, tag, or SHA.
in: query
required: false
schema:
type: string
default: none
example: main
- name: task
description: The name of the task for the deployment (e.g., `deploy` or `deploy:migrations`).
in: query
required: false
schema:
type: string
default: none
example: example_value
- name: environment
description: The name of the environment that was deployed to (e.g., `staging` or `production`).
in: query
required: false
schema:
type: string
default: none
example: example_value
- $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/deployment'
examples:
default:
$ref: '#/components/examples/deployment-items'
headers:
Link:
$ref: '#/components/headers/link'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: deployments
subcategory: deployments
x-api-evangelist-certified: '2025-07-16'
x-api-naftiko-published: '2025-07-25'
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Create Deployment
description: 'Deployments offer a few configurable parameters with certain defaults.
The `ref` parameter can be any named branch, tag, or SHA. At GitHub Enterprise Server we often deploy branches and verify them
before we merge a pull request.
The `environment` parameter allows deployments to be issued to different runtime environments. Teams often have
multiple environments for verifying their applications, such as `production`, `staging`, and `qa`. This parameter
makes it easier to track which environments have requested deployments. The default environment is `production`.
The `auto_merge` parameter is used to ensure that the requested ref is not behind the repository''s default branch. If
the ref _is_ behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds,
the API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will
return a failure response.
By default, [commit statuses](https://docs.github.com/enterprise-server@3.9/rest/commits/statuses) for every submitted context must be in a `success`
state. The `required_contexts` parameter allows you to specify a subset of contexts that must be `success`, or to
specify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do
not require any contexts or create any commit statuses, the deployment will always succeed.
The `payload` parameter is available for any extra information that a deployment system might need. It is a JSON text
field that will be passed on when a deployment event is dispatched.
The `task` parameter is used by the deployment system to allow different execution paths. In the web world this might
be `deploy:migrations` to run schema changes on the system. In the compiled world this could be a flag to compile an
application with debugging enabled.
Merged branch response:
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating
a deployment. This auto-merge happens when:
* Auto-merge option is enabled in the repository
* Topic branch does not include the latest changes on the base branch, which is `master` in the response example
* There are no merge conflicts
If there are no new commits in the base branch, a new request to create a deployment should give a successful
response.
Merge conflict response:
This error happens when the `auto_merge` option is enabled and when the default branch (in this case `master`), can''t
be merged into the branch that''s being deployed (in this case `topic-branch`), due to merge conflicts.
Failed commit status checks:
This error happens when the `required_contexts` parameter indicates that one or more contexts need to have a `success`
status for the commit to be deployed, but one or more of the required contexts do not have a state of `success`.
OAuth app tokens and personal access tokens (classic) need the `repo` or `repo_deployment` scope to use this endpoint.'
tags:
- Deployments
operationId: createDeployment
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/deployments/deployments#create-a-deployment
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
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ref:
type: string
description: The ref to deploy. This can be a branch, tag, or SHA.
task:
type: string
description: Specifies a task to execute (e.g., `deploy` or `deploy:migrations`).
default: deploy
auto_merge:
type: boolean
description: Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
default: true
required_contexts:
type: array
description: The [status](https://docs.github.com/enterprise-server@3.9/rest/commits/statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
items:
type: string
payload:
oneOf:
- type: object
additionalProperties: true
- type: string
description: JSON payload with extra information about the deployment.
default: ''
environment:
type: string
description: Name for the target deployment environment (e.g., `production`, `staging`, `qa`).
default: production
description:
type: string
description: Short description of the deployment.
default: ''
transient_environment:
type: boolean
description: 'Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: `false`'
default: false
production_environment:
type: boolean
description: 'Specifies if the given environment is one that end-users directly interact with. Default: `true` when `environment` is `production` and `false` otherwise.'
required:
- ref
examples:
simple-example:
summary: Simple example
value:
ref: topic-branch
payload: '{ "deploy": "migrate" }'
description: Deploy request from hubot
advanced-example:
summary: Advanced example
value:
ref: topic-branch
auto_merge: false
payload: '{ "deploy": "migrate" }'
description: Deploy request from hubot
required_contexts:
- ci/janky
- security/brakeman
responses:
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/deployment'
examples:
simple-example:
$ref: '#/components/examples/deployment-simple-example'
'202':
description: Merged branch response
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
merged-branch-response:
value:
message: Auto-merged master into topic-branch on deployment.
'409':
description: Conflict when there is a merge conflict or the commit's status checks failed
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: deployments
subcategory: deployments
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/deployments/{deployment_id}:
get:
summary: GitHub Get Deployment
description: This API operation retrieves detailed information about a specific deployment in a GitHub repository. By providing the repository owner, repository name, and deployment ID in the endpoint path, users can fetch comprehensive metadata about a particular deployment including its state, environment, description, creator information, and associated references. This is useful for tracking deployment history, monitoring deployment status, and integrating deployment information into CI/CD pipelines or custom dashboards. The operation requires appropriate authentication and returns a deployment object containing all relevant details about the requested deployment.
tags:
- Deployments
operationId: getDeployment
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/deployments/deployments#get-a-deployment
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
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/deployment'
examples:
default:
$ref: '#/components/examples/deployment'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: deployments
subcategory: deployments
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete Deployment
description: 'If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment.
To set a deployment as inactive, you must:
* Create a new deployment that is active so that the system has a record of the current state, then delete the previously active deployment.
* Mark the active deployment as inactive by adding any non-successful deployment status.
For more information, see "[Create a deployment](https://docs.github.com/enterprise-server@3.9/rest/deployments/deployments/#create-a-deployment)" and "[Create a deployment status](https://docs.github.com/enterprise-server@3.9/rest/deployments/statuses#create-a-deployment-status)."
OAuth app tokens and personal access tokens (classic) need the `repo` or `repo_deployment` scope to use this endpoint.'
tags:
- Deployments
operationId: deleteDeployment
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/deployments/deployments#delete-a-deployment
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
responses:
'204':
description: Response
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed_simple'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: deployments
subcategory: deployments
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/deployments/{deployment_id}/statuses:
get:
summary: GitHub List Deployment Statuses
description: 'Users with pull access can view deployment statuses for a deployment:'
tags:
- Deployments
operationId: listDeploymentStatuses
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/deployments/statuses#list-deployment-statuses
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/deployment-id'
- $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/deployment-status'
examples:
default:
$ref: '#/components/examples/deployment-status-items'
headers:
Link:
$ref: '#/components/headers/link'
'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
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:
- Deployments
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:
- Deployments
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}/environments/{environment_name}/deployment-branch-policies:
get:
summary: GitHub List Deployment Branch Policies
description: 'Lists the deployment branch policies for an environment.
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.'
tags:
- Deployments
operationId: listDeploymentBranchPolicies
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/deployments/branch-policies#list-deployment-branch-policies
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/environment-name'
- $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: object
properties:
total_count:
description: The number of deployment branch policies for the environment.
type: integer
example: 2
branch_policies:
type: array
items:
$ref: '#/components/schemas/deployment-branch-policy'
required:
- total_count
- branch_policies
examples:
default:
$ref: '#/components/examples/deployment-branch-policies-list'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: deployments
subcategory: branch-policies
security:
- bearerHttpAuthen
# --- truncated at 32 KB (687 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-deployments-api-openapi.yml