Last updated February 06, 2023

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 customers, open-source project maintainers or add-on providers who wish to provide their customers with a quick and easy way to deploy and configure a Heroku app.

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:

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.

Button Terms of Use

The Heroku Terms of Use (Default) governs the Terms of Use of your button unless you provide your own Terms of Use in your GitHub repository. It is common practice to link to your Terms of Use in your README file or to add them as a license file to your GitHub repository.

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. 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",
  "repository": "https://github.com/heroku/node-js-getting-started",
  "logo": "https://node-js-sample.herokuapp.com/node.png",
  "keywords": ["node", "express", "static"]
}

If your app requires Heroku add-ons, custom environment variables, or a post-deploy 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-getting-started/tree/main

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.

Here’s an example:

[![Deploy](https://www.herokucdn.com/deploy/button.svg)](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.svg" alt="Deploy">
</a>

A button.svg is also available.

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.svg)](https://heroku.com/deploy?template=https://github.com/heroku/node-js-getting-started)

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-getting-started">
  <img src="https://www.herokucdn.com/deploy/button.svg" alt="Deploy">
</a>

Parametrizing buttons

It’s possible to supply url parameters in the Button URL used for overriding or providing default values for environment variables in the app.json file. You can add url parameters of the form env[SLACK_SUBDOMAIN]=testdomain to the button URL.

For example, you might have the following button URL:

https://heroku.com/deploy?template=https://github.com/rauchg/slackin/tree/0.5.1&env[SLACK_SUBDOMAIN]=testdomain

This will cause the Heroku app-set interface to prefill testdomain for the SLACK_SUBDOMAIN environment variable.

Example uses include:

1. button parametrization, eg. I host multiple buttons on the same source repo using the same app.json file, each setting up the app in slightly different ways
2. button personalization, eg. if a user is logged in and browsing your documentation, you can provide OAuth keys or auth in the button urls so that the user doesn’t have to find and input them on Heroku

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-getting-started/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-getting-started.git
2. cd node-js-getting-started
3. Create Heroku app: heroku create
4. Provision any add-ons specified in the app.json file with heroku addons:create
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.
• Heroku Buttons for Private Repos will not appear in the Heroku Elements Buttons Gallery, nor will they be usable by users who do not have access to the private GitHub code repo.

Further reading

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

• Introducing the app.json Application Manifest
• Heroku Platform API Reference: App Setups
• app.json Schema