Creating a 'Deploy to Heroku' Button

Last Updated: 20 April 2015

app.json deployment

Table of Contents

The ‘Deploy to Heroku’ button enables users to deploy apps to Heroku without leaving the web browser, and with little or no configuration. The button is ideal for add-on providers and open-source project maintainers who wish to provide customers with a quick and easy way to deploy a Heroku app running source code that they maintain.

The button is well-suited for use in README files, and is intended to serve as a replacement to a list of manual steps typically required to configure an app.

Here’s an example button that deploys a sample Node.js app to Heroku:

Deploy

This document describes the requirements for apps that use the ‘Deploy to Heroku’ service, and how to use these buttons make it easy to deploy source code you maintain to Heroku.

Requirements

The basic requirements for creating a button are that your app has a valid app.json file in its root directory, and that the app source code is hosted in a GitHub repository.

Heroku Button will not work with repos that have Git submodules. Heroku Button relies on the Build API and uses tarballs fetched from GitHub. GitHub does not include submodule contents when repo-content tarballs are generated.

Creating the app.json file

app.json is a manifest format for describing web apps. It declares environment variables, add-ons, and other information required to run an app on Heroku.

There are no specific tools required to create an app.json file for your project, but there’s an app.json CLI that makes it easy to create, validate, and update app.json files. The app.json schema has no required fields, but fields such as name, description, and logo are recommended as they provide helpful context to users and give your app a distinct identity.

Here’s a sample app.json file:

{
  "name": "Node.js Sample",
  "description": "A barebones Node.js app using Express 4",
  "repository": "https://github.com/heroku/node-js-sample",
  "logo": "https://node-js-sample.herokuapp.com/node.svg",
  "keywords": ["node", "express", "static"]
}

If your app requires Heroku add-ons, custom environment variables, or a postdeploy script, those can be specified too. For more information, view the app.json schema documentation.

Testing the app.json file

Now that you’ve created an app.json file for your app and added it to the app’s repo, there are a few ways to test that it is valid and that the app can be successfully deployed. You can validate and deploy using the CLI, or use your web browser to deploy from Heroku’s new Dashboard:

https://heroku.com/deploy?template=https://github.com/heroku/node-js-sample/tree/master

Adding the Heroku button

Once you’ve verified that your app.json file is valid and working as expected, it’s time to add a button to your repo README.

There are two ways of referencing the template source code repository:

  • Resolve template implicitly. Useful on GitHub-hosted documentation. If you don’t specify a template parameter, Heroku infers it from the location of the button using the referer header (this does not work with private GitHub repos, because no referer header is sent). This makes the button stable under forks of the repository.
  • Using an explicit template parameter that points to the repo - useful for buttons sitting outside of the GitHub repositories, in blog posts for example and for private GitHub repositories.

Using an implicit template

If you’re embedding the button in a GitHub repository’s README file, Heroku will automatically infer the repository URL from the referer header when someone clicks on the button.

This is convenient because it avoids hard-coding the specific repository URL into the button, allowing forks and branches of the repository to work properly without a change to the button href.

Here’s an example:

[![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy)

Here’s the equivalent content as HTML if you’d prefer not to use Markdown:

<a href="https://heroku.com/deploy">
  <img src="https://www.herokucdn.com/deploy/button.png" alt="Deploy">
</a>

Adding an explicit parameter

Use the following Markdown snippet as a template, changing the template query parameter to the URL of your repository:

[![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy?template=https://github.com/heroku/node-js-sample)

Here’s the equivalent content as HTML if you’d prefer not to use Markdown:

<a href="https://heroku.com/deploy?template=https://github.com/heroku/node-js-sample">
  <img src="https://www.herokucdn.com/deploy/button.png" alt="Deploy">
</a>

Button image

When linking to the Heroku Button set-up flow, you can either use a raw link or an image link. If using an image, Heroku makes available both PNG and SVG versions at these URLs:

  • https://www.herokucdn.com/deploy/button.png
  • https://www.herokucdn.com/deploy/button.svg

Using a custom Git branch

If you’d like the button to deploy from a specific Git branch, you can use a fully qualified GitHub URL as the template parameter:

https://github.com/heroku/node-js-sample/tree/master

Debugging Heroku Buttons

If you have added a Heroku Button to a repo and find that button-clicks do not succeed in deploying an app, then follow these steps to debug the problem.

Make sure source code builds and deploys

First, make sure that the source code you’re trying to buttonize builds and deploys on Heroku. Using the Node.js sample above as an example:

  1. Clone the code into a fresh dir: git clone https://github.com/heroku/node-js-sample.git
  2. cd node-js-sample
  3. Create Heroku app: heroku create
  4. Provision any add-ons specified in the app.json file with heroku addons:add
  5. Add any app config vars specified in the app.json with heroku config:set KEY=VALUE
  6. Push the code with git: git push heroku master
  7. Make sure the app builds
  8. Run the postdeploy command (if any) with heroku run
  9. Open the app and make sure it’s running correctly: heroku open

Note that the build process used by Heroku Button does not have Git submodule support (the default Heroku git-push process does restore submodules).

Invoke app setups

If the above works correctly, the next debugging step is to invoke the app-setups API endpoint directly. This is the API endpoint called by the Heroku Button UI to create and configure apps. After creating an app-setup using the API, you can query for status and examine build output. See the Setting Up Apps Using the Heroku Platform API for details.

Private GitHub repos

Heroku Button works on both public and private GitHub repos. Using Heroku Button on private repos comes with some limitations:

  • You must specify a template URL parameter in the button link because GitHub does not send a referer header for private repos. This means that forks and branches on private repos will typically have buttons that point to the parent repo or the default branch.
  • When setting up an app from a button hosted in a private GitHub repo, the current Heroku user must be linked with GitHub and have access to the repo. If a Heroku user that’s not linked to a GitHub account tries to button-deploy a private repo, the user will be prompted to authenticate with GitHub.

Further reading

For more detailed information about app.json and how it integrates with the Heroku platform, see the following documents: