heroku-fork

Heroku CLI plugin to fork an existing app into a new app.

DEPRECATED: Heroku fork is deprecated as a core command. It will no longer be included in the CLI by default 2017-12-01. We recommend using review apps instead of fork if it will work for your use-case:. You may also fork the Github project to continue using this project as a CLI plugin. See Developing CLI Plugins for more information on developing plugins.

Installation

heroku plugins:install heroku-fork

Commands

heroku fork [NEWNAME]

Fork an existing app into a new one

--region specify a region

--skip-pg skip postgres databases

--from app to fork from

--to app to create

-a, --app undefined

Copy config vars and Heroku Postgres data, and re-provision add-ons to a new app.
New app name should not be an existing app. The new app will be created as part of the forking process.

Example:

  $ heroku fork --from my-production-app --to my-development-app

Use 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.

warning 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.

Setup

You must have the Heroku CLI installed to use the features described here. Verify your CLI installation and update it to the latest version with heroku update.

Fork application

note For the purpose of this guide the originating app is called sourceapp and the new forked app is targetapp.

callout 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.

Invoke 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.

warning 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.

callout Don't create targetapp yourself. 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 --region flag:

$ heroku fork --from sourceapp --to targetapp --region eu

Add-on failures

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.

callout 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.

Heroku Postgres

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 --skip-pg flag:

$ heroku fork --from sourceapp --to targetapp --skip-pg

With --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.

callout 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 (DATABASE_URL), use heroku pg:promote as described by the Heroku Postgres documentation to make it a primary database.

Custom domains

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.

SSL

warning 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 targetapp.

$ 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.

Scheduler

The Heroku Scheduler add-on requires that the job schedule be manually transferred. Open the scheduler dashboard for both sourceapp and 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

Deploy

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 protected]:targetapp.git
...

Add a git remote named forked representing the deploy URL for targetapp.

$ git remote add forked [email protected]: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.

Git repository

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.

Dynos

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

Collaborators

No users from the source app are transferred over to the forked app. You need to add collaborators yourself.

$ heroku access:add [email protected] -a targetapp

Database followers

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.

Labs features

Any enabled Heroku Labs features on sourceapp are not re-enabled on targetapp.