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 asproduction
orqa
. -
auto_merge
parameter is used to ensure that the requested ref is not behind the repository's main branch. The default value istrue
. -
required_contexts
parameter allows you to specify a subset of commit status that must besuccess
. By default, every status must be in asuccess
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!
Top comments (0)