Last updated 01 November 2016
Table of Contents
Heroku integrates with GitHub to make it easy to deploy code living on GitHub to apps running on Heroku. When GitHub integration is configured for a Heroku app, Heroku can automatically build and release (if the build is successful) pushes to the specified GitHub repo.
Enabling GitHub integration
You can configure GitHub integration in the Deploy tab of apps in the Heroku Dashboard.
To configure GitHub integration, you have to authenticate with GitHub. You only have to do this once per Heroku account.
GitHub repo admin access is required for you to configure automatic GitHub deploys. This is because Heroku has to register a service hook on the GitHub repo, and this action requires admin access.
If your repo is in a GitHub organization that has third-party application restrictions enabled, an organization admin will have to approve Heroku for use with the organization. More details are available on GitHub.
Once your Heroku app is linked to a GitHub repo, you can selectively deploy from branches or configure auto-deploys.
With manual deploys, you can create an immediate deployment of any branch from the GitHub repo that’s connected to the app. Use manual deploys if you want to control when changes are deployed to Heroku.
You can also use manual deploys to temporarily deploy a different branch than the one that’s configured to be automatically deployed (see below). For example, you might have a development app synced to the
development GitHub branch, but want to temporarily test a feature branch. Simply trigger a manual deploy of the feature branch to test it on the Heroku app. Note that release of the feature branch will be overwritten on the next successful GitHub push to the
When you enable automatic deploys for a GitHub branch, Heroku will build and deploy all pushes to that branch. If, for example, you have a development app on Heroku, you can configure pushes to your GitHub
development branch to be automatically built and deployed to that app.
If you’ve configured your GitHub repo to use automated Continuous Integration (with Travis CI, for example), you can check the “Wait for CI to pass before deploy” checkbox.
When enabled, Heroku will only auto-deploy after all GitHub statuses for which the following are both true:
- the commit has
- the commit context starts or ends with “ci”, or contains one of these strings: “continuous-integration”, “jenkins”, “buildkite”
That means that auto-deploy will only wait for CI to pass tests of the relevant commit, not tests scheduled for other commits or branches.
With review apps enabled for a Heroku app, Heroku will create temporary test apps for each pull-request that’s opened on the GitHub repo that’s connected to the parent app. Review apps are great if you’re using GitHub Flow to propose, discuss and merge changes to your code base. Because pull request branches are deployed to new apps on Heroku, it’s very simple for you and your collaborators to test and debug code branches. You can also run automated integration tests on the Heroku app representing a GitHub branch.
See the Review Apps article for details.
Links to diffs
For apps that are linked to GitHub repos, releases in the Dashboard “Activity” tab will include a “View Diff” link. Following the link will take you to the GitHub comparison view, showing the changes made since the last release.
Disconnecting from GitHub
Disconnecting individual apps
Individual apps can be disconnected in the GitHub pane of the deploy tab for the app.
You can disconnect your Heroku and GitHub accounts in the Applications pane on your Dashboard account page.
What about the Heroku Git repo?
For apps configured to use GitHub sync, we do not sync the contents of the GitHub repo to your apps repo - we rely exclusively on getting source from GitHub. You can currently still git-push to the Heroku Git remote. We recommend not doing so because it may confuse any collaborators as to what code is currently deployed to the app.
Where can I view build output.
Build output is available in the application’s “Activity” tab on Heroku Dashboard. You can view historical build output and also stream output of builds in progress.
Can I combine GitHub integration and Dropbox sync?
Dropbox Sync cannot currently be used with apps that are configured to use GitHub sync.
What about schema migrations?
By default, Heroku will not run migrations specified by frameworks like Rails during deploys. This problem is made worse with GitHub integration because deploys happen in the background. Heroku is aware of the problem and we’re working on solutions.
GitHub repos that use submodules will generally not deploy correctly on Heroku. This is because GitHub does not include submodule contents when repo-content tarballs are generated.
Unable to access repository
When the GitHub integration is unable to access contents of the repository, it is generally caused by one of the following reasons:
- The GitHub user has lost access to the repository. This can be addressed by requesting access to the repository again, or using a different GitHub user.
Third-party application restrictions have been enabled on the organization. When third-party application restrictions are enabled, the
Heroku DashboardOAuth application has to be granted access to the organization. For instructions on how to do so, please refer to the GitHub documentation.
- The repository no longer exists.
If any of these above do not apply, please open a support ticket.