GitHub Integration (Heroku GitHub Deploys)
Last updated 17 May 2017
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 needs to approve Heroku for use with the organization. More details are available on GitHub.
After you link your Heroku app 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 your 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 branch other than the one that’s configured for automatic deployment. For example, you might have a development app synced to the
development GitHub branch, but you temporarily want to 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 is overwritten on the next successful GitHub push to the
When you enable automatic deploys for a GitHub branch, Heroku builds and deploys 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:
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.
Once you’ve connected your GitHub repo to your Pipeline, you can turn on Heroku CI, our visual, low-configuration test runner that integrates easily with Heroku Pipelines (and so complements Review apps, existing Heroku apps, and our GitHub integrations). Any Heroku Pipeline is already Heroku CI ready – just turn it on in the Pipeline’s settings tab.
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 app’s 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 might 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.
Does GitHub integration automatically run schema migrations?
By default, Heroku does not run migrations specified by frameworks like Rails during deploys.
Heroku Release Phase (currently in beta) lets you perform common tasks like schema migrations before a new version of your app is run. See its documentation for more information.
Does GitHub integration work with Git Submodules?
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.
Why can’t Heroku access my GitHub repository?
When the GitHub integration is unable to access contents of your 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.