Deploying with Git
Last updated May 04, 2023
Table of Contents
- Prerequisites: Install Git and the Heroku CLI
- Create a Heroku Remote
- Deploy Your Code
- Multiple Remotes and Environments
- Detach From the Build Process
- Behavior of Simultaneous Deploys
- HTTP Git Authentication
- Reset a Git Repository
- Keep Your Repository Size Small
- Limits
- Deploy Code Tracked in Subversion or Other Revision Control Systems
- Additional Resources
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.
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
...
Initialize the Git repository in your app’s root directory. If your app is in a subdirectory of your repository, it doesn’t run when pushed to Heroku.
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.
While Heroku Git is convenient for deployment, it’s not intended to be a stable git repository. Use GitHub (recommended), GitLab, BitBucket, or another version control system to track your codebase.
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 -a 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
This method supports applications that rely on Git submodules, in addition to many other dependency resolution strategies.
Heroku doesn’t support git lfs. Using this method can cause pushes to fail.
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
Heroku uses HTTPS as its Git transport (the SSH transport is not supported). The Heroku CLI automatically places credentials in the .netrc
file on heroku login
. The Git client uses cURL when interacting with HTTP(S) remotes, and cURL uses the credentials from the .netrc
file. See the CLI authentication article for details.
You can’t authenticate with the Heroku HTTPS Git endpoint using your Heroku username (email) and password. The Heroku HTTPS Git endpoint only accepts API-key based HTTP Basic authentication. Use an API key as described in this section.
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
Resetting the Git repository deletes all source code and Git history, so make sure you have another copy of the repository first.
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.
You can learn much more about .gitignore
in our article on the topic.
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)"
It’s recommended to use the -f
(force flag) to avoid conflicts with other developers’ pushes. Since you’re not using Git for your revision control, but as a transport only, using the force flag is a reasonable practice.
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.