Getting Started Migrating Your Workspace

Introduction

Knapsack customers are welcome to maintain their workspace on the provided private GitHub repository within Knapsack's GitHub organization, along with the Heroku application.

We understand that Enterprise customers may have unique requirements and thus provide the flexibility of migrating their workspace to their own organization and linking it to their preferred Heroku application, whether it be the same application Knapsack stood up or owned by the Organization.

Supported Git Providers

Cloud Authoring capabilities available for:

  • GitHub
  • GitLab
  • BitButcket Data Center
  • Azure

Guide Outline

This guide will cover the 4 steps necessary to migrate your workspace.

  1. Beginning the migration process
  2. Migrating the repository
  3. Configuring Heroku after the migration
  4. Configuring Deployments and Cloud Authoring
    1. GitHub
    2. GitLab
    3. BitBucket Data Center
    4. Azure

Step 1: Beginning the migration process

If you are an Enterprise customer and wish to begin the migration process, please contact your designated Knapsack representative or send an email to help@knapsack.cloud, and our team will promptly reach out to provide guidance and assistance in completing the process.

Step 2: Migrating the repository

1) Knapsack will initiate the migration process OR schedule time to walk through the process together:

  • You or an organization admin will need to accept the transfer (an email will be generated).
  • In some cases — it makes more sense to push the Knapsack repository directly (and manually) to a new organization repository as opposed to the formal GitHub repository transfer process. 
    • In this circumstance we recommend adding a new remote in your existing Knapsack repo and pushing directly to the new remote.
  • Important: Please provide us with the new URL of your repository so we can update our database to reconnect your workspace and re-enable Cloud Authoring.

2) When the repository migration process is complete — the next step is to update repository references:

File(s) Update Required
knapsack.config.js

Requires an update to repoOwner  field to match the new repository owner (organization).

If the repo name has changed, update repoName as well.
package.json (root and within ./packages directory) Update the name and repository  fields to reflect the new location and organization namespace.
Perform a search and replace on the whole repository to swap out the old namespace with your organization's namespace

For example:

Search for @knapsack-cloud/  

and replace with @your-org/

3) Save all changes and run a test

  • First — run yarn at the root of your repo to ensure all changes to package.json worked. If so, packages should be updated.
  • Next — run yarn build and verify everything builds successfully.
  • If you encounter errors during this step, it's likely due to missing a reference to @knapsack-cloud/ that should be pointing to your org (e.g. @your-org/ )

4) Commit and push the changes

If the build in step 3 above completes successfully — proceed to commit and push your changes.

5) Keep an eye on the "Actions" tab for a successful build

Note: If using the manual migration approach — It is normal for the "Deploy" process to fail at this point due to missing Heroku repository secrets. We'll configure these in the next section (step 3).

6) Still within "Actions" — verify everything is building/releasing before moving onto step 3

Step 3: Configuring Heroku after the migration.

There are two main ways to handle the ownership of the Heroku application:

Option 1: Use the existing Heroku app we generated during the initial workspace creation process.

    1. This option is the easiest/quickest option for migration and does not require Heroku configuration on the customers side.
    2. For this flow, we will invite a member from your team to the existing Heroku application so we can use that member's Heroku email address and API Key for deployments.

Option 2: Create an organization-specific Heroku account and create a new application under that account.

    1. To create a new organization-specific Heroku account, please follow the steps outlined in our guide, "Configuring a new Heroku App".
    2. Note: If your team is setting up your own Heroku application, you'll need to install the Heroku CLI and authenticate after creating an account.

Note: If you require a different deployment strategy (e.g. something custom, not Heroku, etc), please reach out to help@knapsack.cloud.

Step 4: Proceed onto configuring Deployments and Cloud Authoring

Next, let's navigate over to our centralized hub for deployment recommendations and Cloud Authoring configurations.

Click Here to proceed to Step 4

Related Articles