Today, we are announcing an important addition to the Heroku Platform API: The /apps/:app/builds endpoint. This endpoint exposes the Heroku slug compilation process as a simple API primitive. You can use the endpoint to turn any publicly hosted source-tarball into a slug running on a Heroku app in seconds.
Here’s output from a Go program that invokes the new endpoint:
$ ./build -app limitless-fjord-5604 -archive https://github.com/heroku/node-js-sample/archive/master.tar.gz
.........
-----> Node.js app detected
-----> Requested node range: 0.10.x
-----> Resolved node version: 0.10.28
-----> Downloading and installing node
…
$ curl http://limitless-fjord-5604.herokuapp.com/
Hello World!
Here’s what is going on: an app name is passed to the script along with a URL to a tarball containing source code that we want to build and deploy to the app. For this example, we’re using a tarball generated by GitHub, containing a hello-world Node.js app.
The script takes these inputs and uses /apps/:app/builds to create a new build on Heroku. The Platform API responds with the Id of the new build. New builds starts out in pending state. The Go program starts polling for status of the build. In the background, the build service fetches the tarball, unpacks it, and feeds the source through the standard Heroku slug compiler.
Once the build has completed, the state changes from pending to either succeeded or failed. The Go program then fetches the build output using the result endpoint and prints it in the terminal. The build is automatically deployed to the app and we can cURL it to get a Hello World! response.
Uses for the builds endpoint
The builds endpoint exposes the full power of the Heroku slug compiler and release-infrastructure in a very simple API. It is designed for use in automated CI deployment flows. The builds endpoint complements the slug and release endpoints that we announced last year. Combining these endpoints, developers can create flows where source code is pushed to a repository (not on Heroku), built into a slug by invoking the /apps/:app/builds endpoint and then deployed to one or more apps on the platform using the slug and release endpoints.
The builds endpoint has been in private beta for a while and we already have a few cool uses. @atmos has built hubot-deploy, a chat-bot plugin that lets you deploy to Heroku from your favorite hubot-enabled chat room. And we have created a deploy plugin for hk.
What we’re releasing today is the first version of the builds endpoint. We have already gotten lots of great feedback and based on that, we are considering future additions such as:
- Ability to
POSTtarballs directly (versus accepting link to downloadable tarball) - Adding streaming build output as the build progresses
- Making releasing to app optional (currently, all successful builds are deployed immediately)
- Support for fetching source using the Git protocol
To get started with the builds endpoint, check out the Dev Center tutorial, inspect the reference docs or have a look at the Go sample app.
We are always keen to hear user’s thoughts on what we build. For API feedback, get in touch at api-feedback@heroku.com.