GitHub: Cloud Authoring and Deployments


This document will cover the steps necessary to complete your migration to your own GitHub Organization with Heroku deployments.

This is step 4 out of 4 in the process of migrating your Knapsack workspace. If you need to start at the beginning, please visit this article.

Cloud Authoring: GitHub App

Cloud Authoring enabled through GitHub requires the installation of our GitHub App. This is the method we use to authenticate to your repository to be able to submit pull requests and merge code.

  • Before proceeding — it is important the GitHub app is installed and configured for the Knapsack repository.
  • Note: You must have the proper GitHub Organization permissions to install and configure the app.

Deployments: Heroku

  • Note: the below section covers configuration for our default GitHub deployment method. If you're interested in Deploy Previews (per-PR deployments) — please see our help doc on the subject.

The following sections will break down all aspects of reconnecting deployments to Heroku. First we will breakdown the required repository secrets that enable deployments to Heroku.

Required repository secrets

Deployments to Heroku rely on the following repository secrets:

  • HEROKU_EMAIL   — The email associated with the Heroku account
  • HEROKU_API_KEY   — The API Key associated with the Heroku account (found in profile settings)
  • HEROKU_GIT_URL   — The value provided from the "create" command in this document OR located on the app dashboard within Heroku's admin interface

The specific requirements (secrets to add/update) and steps necessary to re-enable deployments to Heroku are determined by a combination of:

  1. The repository transfer method (step 2 of the migration process)
  2. The choice to either maintain use of the provided Heroku App OR create your own (step 3 in the migration process)

Formal Repository Transfer

If the repository was migrated using the formal GitHub ownership transfer method AND:

You are using the provided Heroku app:

  • Update HEROKU_EMAIL and HEROKU_API_KEY to match the account we added to your app.

You are using your own Heroku app:

  • You will need to update al three secrets:

Manual Remote Push

If your Knapsack repo was migrated using the "push to new remote" method, you'll need to add all three secrets fresh:


Putting it all together 🎉

Now that you've configured the required repository secrets to re-enable Heroku deployments — it's time to test things out!

  1. We recommend making a very small change, to a README file perhaps, and then merging that directly into the main branch.
  2. Keep an eye on the "Actions" tab in GitHub for a successful build and deploy.
  3. Visit your newly deployed Knapsack workspace and verify everything deployed successfully.

Testing Cloud Authoring

Now that everything is hooked up, building, and deploying — it's time to test Cloud Authoring.

  1. Within the Knapsack UI — create a new branch and make a small visual change. This could be a simple text change or style adjustment.
  2. Merge your changes right in
  3. Wait about 5-10 minutes for the full deploy to complete —> Verify your changes made it live 🎉

Reach out to your Knapsack representative or email us at if you run into any issues along the way or would like to chat with a Solutions Engineer.