Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 37 ยท Deployment and Releases

Git Deploys and Slugs

Deploy to Heroku with git push, deploy a feature branch or subfolder, use GitHub integration, control slug contents with .slugignore and stay under the slug size limit.

You already pushed once in Deploy your first app. This lesson looks at deploying properly: what Heroku does with your push, the different ways to trigger a deploy, how to keep the build small, and how to read what happened.

What a push does

A Heroku app has a Git remote that is not a normal repository host. It is a build trigger. When you run git push heroku main, three things happen:

  1. Git sends your commits to the remote.
  2. The platform checks out the pushed main branch and runs the buildpacks against it in a temporary build environment.
  3. If the build succeeds, the output is compressed into a slug, a new release is created, and dynos restart from it.

Two details matter. First, only the main (or master) branch of the remote is built; pushes to other remote branch names are accepted but do nothing. Second, the build sees only committed files: uncommitted changes and files in .gitignore are not part of it. If a file works locally but is missing on Heroku, it is almost always ignored or uncommitted.

Ways to deploy

Method Command or setup When to use
Git push git push heroku main Solo work, simple apps
Feature branch git push heroku my-branch:main Trying a branch on a staging app
GitHub integration Connect the repo in the dashboard, enable automatic deploys from a branch Teams; deploys follow merges
Pipelines Promote a build from staging to production Controlled releases (see the CI chapter)
Docker images heroku container:push and release Container-based apps (see Docker deploys)
API / CLI builds heroku builds:create or the Platform API Scripts and CI systems

With GitHub integration you can also ask Heroku to wait for CI to pass before deploying, so a broken commit never reaches your app.

Deploying a subfolder

Heroku builds from the root of what is pushed. If your app lives in backend/ of a larger repository, you can push only that subtree:

CONSOLE
$ git subtree push --prefix backend heroku main

This works, but subtree pushes get awkward with history. Many teams instead add a community buildpack that builds from a subdirectory, or split the code into two apps.

Reading and re-triggering builds

CONSOLE
$ heroku builds
$ heroku builds:info BUILD_ID
$ git commit --allow-empty -m "Rebuild"
$ git push heroku main

An empty commit is the standard way to rebuild without changing code, for example after changing the stack or clearing the build cache. A build that exceeds the platform's build time limit (around 15 minutes) is stopped and fails.

What goes into a slug

The slug contains your committed source files, the dependencies the buildpack installed, and the runtime. It has a hard size limit of 500 MB compressed. Large slugs take longer to build and to start dynos, and above the limit the deploy is refused with an error. The usual causes of oversized slugs:

  • committed binaries, datasets or node_modules,
  • assets and screenshots that are only needed locally,
  • test folders and documentation,
  • development dependencies that the buildpack installed.

Using .slugignore

A file named .slugignore in the repository root lists patterns of files that must be removed from the slug after the build (though they are still in Git and available to buildpacks during the build). It works like .gitignore:

TEXT
*.psd
/docs
/test
/spec
README.md
*.map

Use it for files that your running app never needs. Do not use it for things the build needs (it runs after the build compiles) and do not rely on it to hide secrets; the files remain in your Git history on the remote.

Stand-in: apply a .slugignore and measure the slug

The program below models the effect of .slugignore on a file list with made-up sizes, using pattern matching similar to .gitignore for simple cases. It is a teaching tool, not the platform's matcher.

Python Stand-in: what does .slugignore remove?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Large, unneeded files vanish from the slug; the app's real code and assets are untouched.

Stand-in: slug size budget

When builds start failing on size, you need to know what is big. This stand-in sorts a made-up listing and flags what to move out of the slug or into object storage.

Python Stand-in: find what bloats the slug

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Good deploy habits

  • Commit first, then push. Run git status to confirm that nothing important is untracked.
  • Never edit on the server. heroku run bash is temporary; the fix belongs in Git.
  • Deploy small and often. Small changes are simpler to diagnose and to roll back.
  • Watch the release. After a push, run heroku releases and heroku logs --tail for a minute.
  • Keep secrets out of Git. They belong in config vars.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which remote branch does Heroku build from when you push?

    Only pushes to the remote's main or master branch trigger a build. To deploy another local branch, push it as branch:main.
  2. 2. What is the size limit of a slug?

    Slugs are limited to 500 MB after compression.
  3. 3. What does a .slugignore file do?

    .slugignore keeps files you do not need at runtime out of the slug, reducing its size.
  4. 4. How do you rebuild with no code changes?

    git commit --allow-empty followed by git push heroku main triggers a fresh build.
  5. 5. A file works locally but is missing on Heroku. What is the first thing to check?

    Builds use only committed files, so ignored or uncommitted files are absent.

Summary

  • A push to main triggers a build, a slug and a new release; only committed files are included.
  • Deploy via Git, GitHub integration, pipelines, containers or the API.
  • Keep slugs under 500 MB compressed; .slugignore removes runtime-irrelevant files.
  • Empty commits rebuild without changes; always commit before you push.

Next: Releases and rollbacks