Build the deployment system around GitHub deployment API

I've been working as a DevOps engineer for the last three years and built the deployment system around GitHub deployment API. In this article, I'll explain the deployment API for those of you who want to build the deployment system.

GitHub Deployment API

GitHub provides the deployment API to trigger deploying a specific ref (branch, SHA, tag) and dispatches the deployment event. The workflow seems relatively straightforward:

• Request to deploy a specific ref with a payload, and GitHub dispatches the deployment event.
• A system such as GitHub Action or Jenkins listens for the event and runs the actual deployment.

If you want to deploy the specific branch to the dev environment, you can do it by the API call below. Then GitHub dispatches the deployment event to your tools. The deployment event has information that your tools can deploy, such as the commit SHA, environment, and payload.

curl --location \
--request POST 'https://api.github.com/repos/{OWNER}/{REPO}/deployments' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "ref": "{BRANCH}",
    "environment": "dev"
}'

For details, the deployment API provides various parameters to verify a deployment.

• ref parameter specifies branch, tag, or SHA. Many teams often deploy branches and verify them before merging a pull request.
• environment parameter allows specifying a runtime environment. Teams often have multiple environments for verifying, such as production or qa.
• auto_merge parameter is used to ensure that the requested ref is not behind the repository's main branch. The default value is true.
• required_contexts parameter allows you to specify a subset of commit status that must be success. By default, every status must be in a success state.

What is Gitploy?

GitHub provides a beautiful deployment API. But it is not easy to build a new deployment system around the deployment API, especially for a small team (or organization) it doesn't have enough resources to build. If you find the tooling to fill these gaps, Gitploy can be one of the options. Gitploy provides a straightforward UI and great features for deployment such as rollback, review, lock.

Thanks for reading, and leave me comments on what do you think!