Last updated October 08, 2024

Heroku manages app deployments with Git, the popular version control system. You don’t need to be a Git expert to deploy code to Heroku, but it’s helpful to learn the basics.

This article describes how to deploy code using Git and Heroku Git remotes. If you already track your code in GitHub, consider deploying with the Heroku GitHub integration instead of following the steps in this article.

Prerequisites: Install Git and the Heroku CLI

You must have Git and the Heroku CLI installed to deploy with Git.

• Git installation instructions

• Heroku CLI installation instructions

Before you can deploy your app to Heroku, initialize a local Git repository and commit your application code to it.

The following example demonstrates initializing a Git repository for an app that lives in the example-app directory:

$ cd example-app
$ git init
Initialized empty Git repository in .git/
$ git add .
$ git commit -m "My first commit"
Created initial commit 5df2d09: My first commit
 44 files changed, 8393 insertions(+), 0 deletions(-)
 create mode 100644 README
 create mode 100644 Procfile
 create mode 100644 app/controllers/source_file
...

You’re now tracking your app’s code in a local Git repository. It doesn’t yet exist on any remote servers.

Create a Heroku Remote

Git remotes are versions of your repository that live on other servers. You deploy your app by pushing its code to a special Heroku-hosted remote that’s associated with your app.

For a New App

The heroku create CLI command creates a new empty application on Heroku, along with an associated empty Git repository. If you run this command from your app’s root directory, the empty Heroku Git repository is automatically set as a remote for your local repository.

$ heroku create example-app
Creating app... done, ⬢ example-app
https://thawing-inlet-61413.herokuapp.com/ | https://git.heroku.com/example-app.git

You can use the git remote command to confirm that a remote named heroku has been set for your app:

$ git remote -v
heroku  https://git.heroku.com/example-app.git (fetch)
heroku  https://git.heroku.com/example-app.git (push)

For an Existing App

Add a remote to your local repository with the heroku git:remote command. All you need is your Heroku app’s name:

$ heroku git:remote -a example-app
set git remote heroku to https://git.heroku.com/example-app.git

Rename a Remote

By default, the Heroku CLI names all of the Heroku remotes it creates for your app heroku. You can rename your remotes with the git remote rename command. For example, rename heroku to heroku-staging:

$ git remote rename heroku heroku-staging

Renaming your Heroku remote can be handy if you have multiple Heroku apps that use the same codebase. In this case, each Heroku app has its own remote in your local repository.

The Dev Center documentation assumes your app has a single Heroku remote that is named heroku.

Deploy Your Code

To deploy your app to Heroku, use the git push command to push the code from your local repository’s main branch to your heroku remote. For example:

$ git push heroku main
Initializing repository, done.
updating 'refs/heads/main'
...

Use this same command whenever you want to deploy the latest committed version of your code to Heroku.

Heroku only deploys code that you push to the master or main branches of the remote. Pushing code to another branch of the heroku remote has no effect.

Deploy From a Branch Besides main

To deploy code to Heroku from a non-main branch of your local repository (for example, testbranch), use the following syntax push it to the remote’s main branch:

$ git push heroku testbranch:main

Multiple Remotes and Environments

You can use the same techniques used to deploy to production to deploy a development branch of your application to a staging application on Heroku. See Managing Multiple Environments for an App for more info.

Detach From the Build Process

After you initiate a Heroku deploy with git push, you can detach from the resulting build process by pressing Ctrl + C. Detaching doesn’t cancel the build or the deploy. The build continues in the background and creates a new release as soon as it completes.

Behavior of Simultaneous Deploys

It’s possible to initiate a deploy before a previous deploy of the same app completes. For example, two collaborators on an app push different commits to the heroku remote at roughly the same time.

If this situation occurs, the different versions of your app deploy to Heroku in the order in which their respective builds complete. This order can differ from the order in which the pushes occurred.

For example, consider two builds, A and B. If Build B starts after Build A but finishes before it, Heroku deploys Build B first. Then, when Build A eventually completes, Heroku deploys it, replacing Build B.

HTTP Git Authentication

If you authenticate to the Git service with incorrect credentials, you get this error:

remote: ! WARNING:
remote: ! Do not authenticate with username and password using git.
remote: ! Run `heroku login` to update your credentials, then retry the git command.
remote: ! See documentation for details: https://devcenter.heroku.com/articles/git#http-git-authentication

If you’re using other Git clients, such as EGit or Tower, configure them to use an empty string for username and your account API key for password. The API key is available in the CLI and in the dashboard.

Reset a Git Repository

To reset or purge an app’s Heroku Git repository, use the heroku-repo CLI plugin:

$ heroku plugins:install heroku-repo
$ heroku repo:reset --app appname

Keep Your Repository Size Small

The uncompressed size of a checkout of HEAD from the repository, combined with the size of restored submodules, can’t exceed 1 GB.

It’s not recommended to deploy large repositories over 600 MB They can cause timeouts and slow pushes overall. Running heroku apps:info shows you your repository size.

Common causes of large repositories are binary files checked into the repository or constantly changing development logs. You can remove files committed by accident with git filter-branch. After running it, you must push your changes with the --force option, requiring coordination among your team.

After reducing the size of your repository locally, you must reset the app’s Git repository before pushing it to Heroku again.

Limits

To protect the Git service, Heroku imposes certain limits on Git repository use and content size.

Heroku limits users to a rolling window of 75 Git requests per hour, per user, per app. After reaching this limit, Heroku denies Git requests until request levels drop below the limit for a few minutes. You see an error message like:

 !  Too many requests for this Git repo. Please try again later.

If you reach this limit, ensure there are not automated processes or scripts polling the Git repository.

In addition, the uncompressed size of a checkout of HEAD from the repository, combined with the size of restored submodules, can’t exceed 1 GB.

Deploy Code Tracked in Subversion or Other Revision Control Systems

While Git is one of the best choices available for revision control, you don’t need to stop using your current revision control system. You can use Git purely as a deployment mechanism, existing side by side with your other tool.

For example, if you’re using Subversion, initialize your Git repository as described in the Pre-requisites section. Then, add a .gitignore file to tell Git to ignore your Subversion directories.

$ git init
$ echo .svn > .gitignore
$ git add .
$ git commit -m "using git for heroku deployment"

Now tell Subversion to ignore Git:

$ svn propset svn:ignore .git .
property 'svn:ignore' set on '.'
$ svn commit -m "ignoring git folder (git is used for heroku deployment)"

Each time you wish to deploy to Heroku:

$ git add -A
$ git commit -m "commit for deploy to heroku"
...

$ git push -f heroku

Additional Resources

• Git on Rails shows common conventions for using Git to track Rails apps.
• Git cheat sheet
• Git - SVN Crash Course
• The Pro Git book is a great resource that covers all of Git.