Deployments

Learn and practice the functionalities of deployments in the GitHub API.

We'll cover the following

Overview

Deployment is a request to deploy resources from one development environment to another to bring them into effective action. These requests can be of any branch, tag, or ID. Deployments minimize the worry of implementation details of various application types. They do so by building a loosely-coupled relation between different deployments.

The external services can mark deployments with different deployment statuses. The list below shows these status types:

  • error
  • failure
  • pending
  • in_progress
  • queued
  • success

We can add description and log_url optionally to the deployment status for more clarity. The deployment and its status are dispatched by GitHub to third parties that upgrade its status as per the progress. As the third party receives the deployment, it is deployed to our server.

Create a deployment

A recommended practice before merging or pulling a branch is to first deploy and verify it. The deployment can be made in these three different environments:

  1. production
  2. staging
  3. qa

The default environment is set to production.

The table below shows some important parameters of the body to create a deployment:

Output body parameters of creating a deployment

Name

Type

Present In

Description

ref

string

body

This is the reference we need to deploy. It can be SHA, branch, or tag.

task

string

body

This is a task that needs to be executed. This can be deploy or deploy:migrations.

auto_merge

string

body

If the requested reference is behind the default branch, it is merged into the default branch automatically.

required_context

boolean

body

This verifies the context against commit status checks. We can send an empty array to bypass the checking entirely.

payload

object or string

body

This is in the JSON format and contains extra information about the deployment.

environment

string

body

This is the environment. It can be production, staging, or qa.

description

string or null

body

This describes deployment.

transient_environment

boolean

body

It is true if that specific deployment will no longer be used in future.

production_environment

boolean

body

It is true when the environment is production.

Let’s try creating a deployment by specifying <ref> in line 7. We extract and save the deployment ID to be used later in the lesson.

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
data = json.dumps({
    'ref': '<ref>'
})
url='https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/deployments'
response = requests.post(url, headers=headers, data=data)
print(json.dumps(response.json(), indent=4))

Get a deployment

We can get a deployment specifically by providing its ID.

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
url='https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/deployments/{{DEPLOYMENT_ID}}'
response = requests.get(url, headers=headers)
print(json.dumps(response.json(), indent=4))

List deployments

Let’s try listing all the deployments of the repository and also see whether our created deployment exists there.

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
url='https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/deployments'
response = requests.get(url, headers=headers)
print(json.dumps(response.json(), indent=4))

Delete a deployment

When we call the delete deployment API using the deployment ID, it checks if there is one or multiple deployments in the repository. If there is one deployment, it gets deleted. However, if there are multiple deployments, the inactive ones are deleted.

The code below performs this functionality:

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
url='https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/deployments/{{DEPLOYMENT_ID}}'
response = requests.delete(url, headers=headers)
if response.status_code == 204:
    print('The deployment was deleted successfully.')
else:
    print('Something went wrong.')