Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Working with Bundler
      • Rails Support
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Data For Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Heroku Architecture
  • Stacks (operating system images)
  • Upgrading to the Latest Stack

Upgrading to the Latest Stack

English — 日本語に切り替える

Last updated September 21, 2022

Table of Contents

  • Introduction
  • General upgrading strategy
  • Testing an app on a new stack
  • Upgrading an app
  • Rolling back
  • Common issues

The Heroku-18 stack is deprecated and will reach end-of-life on April 30th, 2023. Please upgrade to a newer stack as soon as possible. See the Heroku-18 End-Of-Life FAQ for more details.

Introduction

This article describes how to upgrade your app to use the latest Heroku stack. Refer to the Stacks article to understand what a stack is, which stacks are available, and how to determine the stack your application is currently using.

When a Heroku app is built, the source code for your application, together with the fetched dependencies and output of the build such as the language and framework, are assembled into a bundle known as a slug. This slug will typically only be compatible with the stack on which it was built, so apps that have previously had a deploy must be rebuilt in order to be compatible with a new stack.

Changing an existing app’s stack is a very similar process to a standard app deploy. First, the stack setting of the app is updated to request a change in the target stack used during the build. Next, a new build needs to be triggered so that a new slug is created that targets/is compatible with the new stack. This new build is deployed in exactly the same way as a standard build - for example there is no downtime for the stack upgrade to occur, and rollbacks can be performed in the same way.

General upgrading strategy

After determining what stack your application is currently using, you must decide which stack to migrate to. In general, you should always move to the very latest available stack.

You should first review the changes between the stack you’re currently running, and the intended destination stack, as well as their respective recommendations for upgrades from an earlier stack. The Stacks article contains a list of all stacks, and the detail page for each stack linked therein contains upgrading notes.

When upgrading more than one stack generation, e.g. from Heroku-18 to Heroku-22, remember to review the upgrade notes for all intermediate stack generations to gain a comprehensive understanding of the all the changes involved.

Before upgrading your production app to a new stack, it is highly recommended you either create a test app with the new stack first (detailed in the next section), or try the upgrade with an existing staging or development app first.

Testing an app on a new stack

You may either use a Review App to create a temporary version of your app on the desired stack, or manually create a new app that uses the desired stack and deploy your code to it.

Review apps (recommended)

If your organization uses Review Apps, we recommend testing a new stack by creating a branch that changes the stack definition in app.json as follows:

{
   "stack": "heroku-22"
}

Pushing this branch and creating a Pull Request for it will then deploy the app on the new stack as a Review App, where it can be thoroughly tested.

Manually created test app

You may also test your codebase on a different stack by creating a new test app from an existing application.

Creating a new test app

From an existing app’s codebase, run heroku create with arguments that create a separate test app under a different name and Git remote:

$ heroku create --remote heroku-22 --stack heroku-22 <your app name>-heroku-22

This command will:

  • Create a new app named “<your app name>-heroku-22”;
  • Set the stack image to the Heroku-22 stack for that newly created app;
  • Set up a new Git remote named “heroku-22”.

Your Git repository now contains at least two remotes: heroku, pointing to your existing production app, and heroku-22, pointing to the new app you just created. Pushing changes to one of these apps will not impact the respective other app.

Migrating add-ons and config vars

In order for your app to be fully functional, you must also mirror any add-ons and config vars.

To list your existing app’s add-ons, run:

$ heroku addons --remote heroku

For each of the add-ons listed, create a corresponding counterpart on your test app:

$ heroku addons:create --remote heroku-22 <add-on>

Next, examine your existing app’s config vars, as well as the new app’s config vars that were already set by any add-ons you may have provisioned:

$ heroku config --shell --remote heroku
…
$ heroku config --shell --remote heroku-22
…

For any config var present on your existing app that isn’t yet set on your test app, set it on the test app:

$ heroku config:set --remote heroku-22 <name>=<value>

The --shell option of heroku config outputs variables in a format that you can easily copy, and then paste into a heroku config:set command line.

Deploying the test app

Deploying your new app will not affect your currently running app.

Push the source to the test app’s remote:

$ git push heroku-22 main
Counting objects: 67, done.
...
-----> Ruby app detected
-----> Compiling Ruby/Rack
...

Once the app is deployed, you should verify that it is working correctly, and if not, make any required changes. If you encounter issues not covered in the stack upgrade notes for that stack version and need assistance, open a support ticket with the stack name in the subject line.

$ heroku open --remote heroku-22
$ heroku logs --remote heroku-22

Removing the test app

After you have finished verifying that the test app works correctly, you can remove it like so:

$ heroku apps:destroy --remote heroku-22

Upgrading an app

Setting the stack

To upgrade via the Heroku CLI, use the stack:set command on your production app:

$ heroku stack:set heroku-22 -a <app name>
Setting stack to heroku-22... done
You will need to redeploy ⬢ <app-name> for the change to take effect.
Run git push heroku main to trigger a new build on ⬢ <app-name>.

For apps that have previously been built, this does not immediately change the stack of the app - a new build is required (which will target the chosen stack) for the change to take effect. For apps where code has never been deployed (such as add-on only apps), the stack change will take immediate effect and so for them a new deploy is not required.

If you have no changes to your source pending release, you can create an empty commit with no changes, to trigger a new build:

$ git commit --allow-empty -m "Upgrading to heroku-22"
[main 973c3f7] Upgrading to heroku-22

To create the new release, push to your production app:

$ git push heroku main

Your production app is now running on the latest stack, and you should verify that everything is working as expected.

Updating app.json

If you are using app.json, you should also specify the stack there to ensure that your Review Apps and Heroku CI runs use the same stack:

{
   "stack": "heroku-22"
}

An existing app’s stack cannot be changed using app.json. The stack specified is only applied to newly created apps that are a Review App, a Heroku CI test run app, or an app created using a Heroku Buttons.

Pipeline promotions

When using the Heroku Pipelines feature, promoting an app copies its slug to the target app and overwrites the target app’s stack to match the stack of the originating app. As such there is no need to use stack:set on the downstream (production) app directly. Instead, upgrade the stack of the staging app, verify the app is running as expected, and then perform a pipeline promotion as normal.

Upgrading via Dashboard

To upgrade via the Heroku Dashboard, navigate to your app settings page and click the Upgrade Stack button. Confirm that you want to upgrade, which will set the stack to the latest version.

The Upgrade Stack button is only shown if you have sufficient permissions to update the stack on the app.

For apps that have previously been built, you will see that the stack upgrade is pending; the upgrade will take effect on the next deploy. For apps where code has never been deployed (such as add-on only apps), the stack change will take immediate effect and so for them a new deploy is not required.

Rolling back

If your app is not working after you changed the stack, you can revert back until you’ve contacted customer support, debugged and resolved the issue.

First you need the release version of the last release that was using the previous stack:

$ heroku releases
=== production-app Releases
v13  Deploy 973c3f7                  joe@example.com   2022/06/12 10:55:16
v12  Deploy ddb317d                  jill@example.com  2022/06/09 15:33:59
...

Then roll back to that release:

$ heroku rollback v12

Your production app is now again running on the previous stack.

Alternatively, if you would prefer not to use the rollback feature, you can change the stack back using heroku stack:set <original-stack-name> and then complete the stack downgrade by performing another deploy.

Common issues

Old buildpack versions

The buildpacks defined for an app can be specified using several different forms of buildpack reference. Pinning to a specific buildpack version tag/branch/SHA will mean any compatibility fixes for new stacks won’t be picked up automatically, which may cause the build to fail on newer stacks.

List the current buildpacks using:

$ heroku buildpacks

If you see any buildpack URLs ending with a # followed by a Git reference (e.g. a commit SHA, branch name or tag name), these should be be replaced with a buildpack URL that does not contain the version suffix. See buildpack references for more details.

Third-party buildpacks

We expect most third-party buildpacks will work with a new stack. If your app is using a third-party buildpack, and you experience an issue building your app, we recommend clearing the build cache:

$ heroku plugins:install heroku-builds
$ heroku builds:cache:purge

If clearing the build cache doesn’t work, we suggest opening up an issue on the buildpack’s GitHub page.

Stack-specific issues

See the “What’s new” and “Upgrade notes” sections on each stack’s detail page, for commonly encountered issues that are specific to that stack:

  • Heroku-18
  • Heroku-20
  • Heroku-22

Keep reading

  • Stacks (operating system images)

Feedback

Log in to submit feedback.

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences