Last updated February 09, 2022
This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.
heroku fork command is deprecated and no longer included in the base installation of the Heroku CLI. If you want to fork your app in order to test code changes, consider using review apps instead.
heroku fork to copy an existing application, including add-ons, config vars, and Heroku Postgres data.
It is a common practice to maintain more than one environment for each application. For example, a staging and production environment for each app along with any number of ephemeral test environments for features in various stages of development. To ensure parity across applications, create new apps as forks from the production environment.
Forked applications are created in the account of the user executing
heroku fork. The forking user will be the owner of the app and responsible for any application charges. For this reason, your account needs to be verified if the application you’re forking contains paid resources.
For the purpose of this guide the originating app is called
sourceapp and the new forked app is
Any add-ons with paid plans on the old app will be provisioned with the same paid plans on the new app. Adjust your add-on plans as needed by up- or down-grading after forking.
heroku fork to create the target app, copy all Heroku Postgres data and config vars to the new app, and re-provision all add-ons with the same plan. Depending on the size of your database this process may take some time.
Only Heroku Postgres data is automatically copied to the new application. All other add-ons are simply re-provisioned and you will need to manually manage any requisite data export/import for these services.
heroku fork creates the target app as part of the forking process.
$ heroku fork --from sourceapp --to targetapp Creating fork targetapp... done Copying slug... done Adding heroku-postgresql:dev... done Creating database backup from sourcapp... .. done Restoring database backup to targetapp... .. done Copying config vars... done Fork complete, view it at http://targetapp.herokuapp.com/
To fork an app to a non-default region, use the
$ heroku fork --from sourceapp --to targetapp --region eu
Some add-ons may fail provisioning if they’re no longer available.
$ heroku fork --from sourceapp --to targetapp Creating fork targetapp... done Copying slug... ........ done Adding airbrake:developer... done Adding bonsai:test... skipped (not found) ...
If the add-ons can’t be provisioned because the original plan no longer exists, upgrade the plan on the source app and retry the fork.
If you’ve already run
heroku fork you will need to destroy the target app before retrying:
heroku destroy -a targetapp.
$ heroku addons:upgrade bonsai:starter -a sourceapp Upgrading to bonsai:starter on sourceapp... done, v207 (free)
Manual add-on configuration
There are some add-ons that require additional configuration after provisioning. There may be others beyond the add-ons listed so please review your app’s add-ons for any that have manually entered configuration.
All Heroku Postgres databases on your application will be copied from your
sourceapp to your target app using
pg:copy. Heroku Postgres fork is not used for this. If you have followers, this will result in duplicate copies that are not currently following your leader database.
For the larger size databases, this step will take a long time. You can skip this step by passing
$ heroku fork --from sourceapp --to targetapp --skip-pg
--skip-pg flag, Heroku Postgres databases will not be created on the target app. You can create it manually after
heroku fork, or you could also use Heroku Postgres fork.
It is recommended to make sure if you have an expected Heroku Postgres setup with your target app. Please run
heroku pg:info and/or
heroku config command to make sure that everything has copied as you expected. If the copied database is not being the primary database (
heroku pg:promote as described by the Heroku Postgres documentation to make it a primary database.
Since custom domains can only belong to a single app at a time, no custom domains are copied as part of the forking process. If you want to use custom domains in your new environment you will need to add them yourself as well as make the necessary DNS additions.
If your forked app doesn’t need to use SSL, remove the add-on with
heroku addons:destroy ssl to avoid unnecessary charges.
Although the forking process re-provisions the SSL Endpoint on
targetapp it does not add any certs on your behalf. If your app uses custom domains with SSL you need to add new certs to your SSL endpoint instance on
$ heroku certs:add server.crt server.key -a targetapp Resolving trust chain... done Adding SSL Endpoint to targetapp... done example now served by tokyo-1234.herokussl.com
Add a new DNS CNAME record utilizing this new endpoint URL to serve requests via HTTPS.
The Heroku Scheduler add-on requires that the job schedule be manually transferred. Open the scheduler dashboard for both
targetapp side-by-side to view the diffs and manually copy the jobs.
$ heroku addons:open scheduler -a sourceapp $ heroku addons:open scheduler -a targetapp
Forking your application doesn’t automatically create a new git remote in your current project. To deploy to
targetapp you will need to establish the git remote yourself. Use
heroku info to retrieve the Git URL of the new application and the set it manually.
$ heroku info -a targetapp === targetapp ... Git URL: email@example.com:targetapp.git ...
Add a git remote named
forked representing the deploy URL for
$ git remote add forked firstname.lastname@example.org:targetapp.git
Deploy to the new environment with:
$ git push forked master
If you wish to make the new app the default deployment target you can rename the git remotes.
$ git remote rename heroku old $ git remote rename forked heroku
Forked app state
Forked apps are as close to the source app as possible. However, there are some differences.
When forking, the slug currently running in the forked app is copied to the new app. The Git repository contents of old app are not copied to the Git repository of the new app.
Forked applications are similar to new apps in that they are scaled to the default dyno formation consisting of a single web dyno and no worker or other dynos.
Scale your forked application’s dynos to meet your needs:
$ heroku ps:scale web=1 worker=1 -a targetapp
No users from the source app are transferred over to the forked app. You need to add collaborators yourself.
$ heroku access:add email@example.com -a targetapp
The forking process copies all databases present on
sourceapp but does not retain any fork/follow relationships between them. Remove extraneous databases yourself and manually re-establish any forks or followers.
Any enabled Heroku Labs features on
sourceapp are not re-enabled on