The Deployments API provides your projects hosted on GitHub Enterprise Server with the capability to launch them on a server that you own. Combined with the Status API, you'll be able to coordinate your deployments the moment your code lands on the default branch.
This guide will use that API to demonstrate a setup that you can use. In our scenario, we will:
- Merge a pull request
- When the CI is finished, we'll set the pull request's status accordingly.
- When the pull request is merged, we'll run our deployment to our server.
Our CI system and host server will be figments of our imagination. They could be Heroku, Amazon, or something else entirely. The crux of this guide will be setting up and configuring the server managing the communication.
If you haven't already, be sure to download ngrok, and learn how to use it. We find it to be a very useful tool for exposing local connections.
Note: you can download the complete source code for this project from the platform-samples repo.
Writing your server
We'll write a quick Sinatra app to prove that our local connections are working. Let's start with this:
require 'sinatra'
require 'json'
post '/event_handler' do
payload = JSON.parse(params[:payload])
"Well, it worked!"
end
(If you're unfamiliar with how Sinatra works, we recommend reading the Sinatra guide.)
Start this server up. By default, Sinatra starts on port 4567, so you'll want
to configure ngrok to start listening for that, too.
In order for this server to work, we'll need to set a repository up with a webhook.
The webhook should be configured to fire whenever a pull request is created, or merged.
Go ahead and create a repository you're comfortable playing around in. Might we
suggest @octocat's Spoon/Knife repository?
After that, you'll create a new webhook in your repository, feeding it the URL
that ngrok gave you, and choosing application/x-www-form-urlencoded as the
content type:
Click Update webhook. You should see a body response of Well, it worked!.
Great! Click on Let me select individual events., and select the following:
- Deployment
- Deployment status
- Pull Request
These are the events GitHub Enterprise Server will send to our server whenever the relevant action occurs. We'll configure our server to just handle when pull requests are merged right now:
post '/event_handler' do
@payload = JSON.parse(params[:payload])
case request.env['HTTP_X_GITHUB_EVENT']
when "pull_request"
if @payload["action"] == "closed" && @payload["pull_request"]["merged"]
puts "A pull request was merged! A deployment should start now..."
end
end
end
What's going on? Every event that GitHub Enterprise Server sends out attached a X-GitHub-Event
HTTP header. We'll only care about the PR events for now. When a pull request is
merged (its state is closed, and merged is true), we'll kick off a deployment.
To test out this proof-of-concept, make some changes in a branch in your test repository, open a pull request, and merge it. Your server should respond accordingly!
Working with deployments
With our server in place, the code being reviewed, and our pull request merged, we want our project to be deployed.
We'll start by modifying our event listener to process pull requests when they're merged, and start paying attention to deployments:
when "pull_request"
if @payload["action"] == "closed" && @payload["pull_request"]["merged"]
start_deployment(@payload["pull_request"])
end
when "deployment"
process_deployment(@payload)
when "deployment_status"
update_deployment_status
end
Based on the information from the pull request, we'll start by filling out the
start_deployment method: