Unity Cloud Build automation pipeline with webhooks, and querying the Build API

Once you’ve figured out a general process for deploying game releases, you certainly don’t want to be manually completing every step of the process every time there is a release. If you add up the time spent copying build releases, updating websites with new build information, sending out notifications or change logs, etc… that time can really add up in the long run. Unity Cloud Build helps solve some of this, but there is more that can be done…

Unity Cloud Build already allows you to hook up to your Git (or other) repository to the Cloud Builds platform, and have automated builds created of your project whenever you push code up to your repository. This is great, and allows you to automate builds for various platforms – PC, Mac, Mobile, etc all by just updating your source repository. You can even configure it to watch a specific branch and create builds from that branch, effectively allowing you to branch off of the trunk/master and work in feature branches, then merge work back into ‘release’ branches.

The question then is, how do you continue this automation pipeline after Unity Cloud has finished your build?

The answer is to use a: Webhook.

A webhook is an HTTP POST request that Unity Cloud Build can send to an API endpoint you specify, whenever a particular event in your build pipeline occurs. For example, on the successful completion of a build. (ProjectBuildSuccess event).

You can choose a particular content type that the webhook payload is delivered with (one that your API would understand like application/json). Let’s look at an example of configuring a webhook that will send a POST request to an API endpoint I manage/own when a build of my Unity project successfully completes.

For this I will be running a simple Node.js express web server with body-parser middleware. In my Node.js server, I have set up a route for POST actions to go to called ‘builds’. When a POST request is sent to this endpoint, I’ll simply log the content of the POST body to the console to show the information that Unity Cloud Build sends along.

After setting up a Unity Cloud Build step, I went to define a webhook in the “Notifications” tab. I provided the public URL for my endpoint where the HTTP POST request will be sent to, set the content type to application/json, and chose the event that I want this to happen on. For testing I didn’t bother with providing a secret to help secure the body of the POST, as this would then need additional processing of the content on the other side to interpret it.

edit-webhook

Note: if you are doing this yourself as a test/proof of concept, and don’t have SSL on your domain, you should disable the SSL verify option. (You should always secure with SSL if you are using this in production though, as you don’t necessarily want information about builds being passed around un-encrypted).

With the webhook defined, and saved, to test it, I simply kick off a build of the Unity project. (You can manually start a build if you don’t want to hassle with making changes to your repository).

After the build completed, as expected it sent the POST request to my API’s /builds endpoint. (You may want to click to expand the image below to actually see the details the POST drops off in the body!)

unity-cloud-builds-webhook-post-content

From this point onward, I could then do whatever I needed with the information sent across in the body. Here is a quick example. Let’s say there is some interesting information I wanted out of the actual build log that is generated from a build. Say I wanted to publish some of that information to another website after a build completed.

I would take the build number from the webhook POST request’s body content when it hits my API on the /builds endpoint, craft a new POST request myself, and send this to the Unity Cloud Builds v1 API, including the following request parameters: orgid, projectid, buildtargetid, and finally the build number which I got from the webhook’s POST request. This is what the request would look like for a ‘get build log’:

get-build-log-request

I fire that off, and the Unity Cloud Build API should respond with my full build log. I can then parse that log for the information I need, and update my site with it.

get-build-log-response

Once that is all setup, all I need to do is update my Unity project source code in version control, and Unity Cloud Build will build the project, upon success, it will POST some information about the build to my own API, this information will then be used to in turn query the build API for the specific build log relating to this build, the response will come back, my system will parse that log, take the interesting information, and through some other mechanism, update a website, which might at that point end the whole automation pipeline.

Hopefully this gives you some interesting ideas or inspiration to automate your own builds. The sky is really the limit. RESTful APIs make automation and interoperability of systems so easy!