Be sure to initialize the Git repository in your app’s root directory. If your app is in a subdirectory of your repository, it won’t run when it is pushed to Heroku.

Your app’s code is now tracked in a local Git repository. It has not yet been pushed to any remote servers.

Creating a Heroku remote

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

For a new Heroku 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.

Renaming remotes

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:

$ git remote rename heroku heroku-staging

Renaming your Heroku remote can be handy if you have multiple Heroku apps that use the same codebase (for example, the staging and production versions of an app). In this case, each Heroku app has its own remote in your local repository.

The remainder of this article assumes your app has a single Heroku remote that is named heroku.

Deploying code

To deploy your app to Heroku, you typically use the git push command to push the code from your local repository’s master branch to your heroku remote, like so:

Build deploy ordering

If multiple parallel builds are started for an app (either by the same user performing multiple pushes, by app collaborators pushing concurrently or because builds are created concurrently with other mechanisms like Build API or GitHub Sync), then the last build to complete will generally be the one that ends up being deployed for the app, even if that build was started before other builds.

Take an example of two builds, A and B: Build A is started, runs slowly and completes in 2 minutes. 30 seconds after build A is started, build B is started and completes in 1 minute. Build B is deployed for the app when it completes. 30 seconds later, build A completes and is deployed for the app. The end result is that build A is deployed on the app, even though build B was started later.

Detach from build process

When deploying code using git push, you can detach from the build process by pressing Ctrl + C. However, your build will continue to process in the background and will create a new release as soon as it finished.

HTTP Git authentication

By default, Heroku uses HTTP as its Git transport. The Heroku CLI will automatically place credentials in the .netrc file on heroku login. The Git client uses cURL when interacting with HTTP remotes, and cURL will use the credentials from the .netrc file. See the Authentication section and the CLI authentication article for details.

The Heroku HTTP Git endpoint only accepts API-key based HTTP Basic authentication. A username is not required and any value passed for username is ignored.

You cannot authenticate with the Heroku HTTP Git endpoint using your Heroku username (email) and password. Use an API key as described in this section

If, for any reason, you authenticate to the Git service with incorrect credentials, you’ll 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

When you do heroku login, the CLI will write an entry for git.heroku.com into your .netrc file (or its Windows equivalent). Since the Git client uses cURL when interacting with HTTP Git remotes, correct authentication will now happen transparently.

If you’re using other Git clients, such as EGit or Tower, configure them to use an empty string for username (or any string you like – it’s ignored) and your account API key for password. The API key is available in the CLI and in Dashboard.

SSH Git transport

The default Git transport configured by the Heroku CLI is HTTP, but SSH transport is also supported. SSH and HTTP transport can be used interchangeably by the same user and by multiple users collaborating on the same app. To have the Heroku CLI configure SSH transport, you can pass a --ssh-git flag to the heroku create, heroku git:remote and heroku git:clone commands.

HTTP URLs will still be written to .git folders but Git will rewrite, on the fly, all Heroku HTTP Git URLs to use SSH.

To remove this rewrite setting, run:

$ git config --global --remove-section url.ssh://git@heroku.com/

SSH is not supported for SSO users. SSO users must use HTTPS as a git transport.

Multiple remotes and environments

The same techniques used to deploy to production can be used to deploy a development branch of your application to a staging application on Heroku, as described in Managing Multiple Environments for an App.

Build cache

Buildpacks can optionally cache content for re-use between builds. A typical use-case for the buildpack is to speed up builds by caching dependencies so that they don’t have to be re-fetched on every build. This greatly speeds up builds.

If you suspect that a build-problem is related to this caching, you can use the heroku-repo plugin to clear the cache.

Repository size

While there is not a hard limit on your repository size, very large
repositories (over 600 MB) are not recommended; they may cause timeouts
and slow pushes overall. Running heroku apps:info will show you your
repository size. The app build cache is stored inside the app repository, so
don’t be surprised if the repository is larger remotely than locally.

Common causes of large repositories are binary files checked into the
repository (Git is notoriously bad at handling binaries) or
constantly-changing development logs. Removing files committed by
accident can be done with
git filter-branch,
though after running it you will have to push with the --force
option, which is something that requires coordination among your team.

Other limits

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

Users are limited to a rolling window of 75 Git requests per hour, per user, per app. Once this limit is reached, Git requests are denied until request levels drop below the limit for a few minutes, with the error message:

! 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, cannot exceed 1 GB.

Using subversion or other revision control systems

What if you’re already using Subversion or another revision control system to
track your source code? Although we believe that Git is one of the best choices
available for revision control, you don’t need to stop using your current
revision control system. Git can be purely a deployment mechanism, existing
side-by-side with your other tool.

The -f (force flag) is recommended in order to avoid conflicts with other developers’ pushes. Since you are not using Git for your revision control, but as a transport only, using the force flag is a reasonable practice.