Deploy Previews (Per PR Deployments)

IMPORTANT NOTES:

  • Enabling per-PR deployments requires additional hosting fees via Heroku. Please work with your Account Executive or Customer Success Manager to plan for billing impact.
  • At the time of writing — deploy previews are only available through GitHub, utilizing the Heroku GitHub App.

Introduction

Development teams often need to evaluate changes before they become part of the main product. These could be new features, bug fixes, or updates.

The conventional way to do this has been to set up a separate staging environment for testing, but this can be time-consuming, complex, and often isn't an exact reflection of the live environment.

Heroku Review Apps

With Heroku's Review Apps feature, you can streamline this process. Whenever you open a pull request on your GitHub repository, Heroku will automatically spin up a disposable app, reflecting the changes proposed in your pull request. It’s like having a fully functioning staging environment, tailor-made for each set of modifications.

This allows your team to preview, test, and even share the proposed changes in a live-like environment without impacting your production app.

This approach has numerous benefits:

  • It aids quality assurance
  • Facilitates user acceptance testing and
  • Accelerates the feedback loop

All while reducing the possibility of unexpected surprises when the changes are deployed to the production environment.

In essence, Review Apps can help your team deliver more reliable software, faster, with less effort involved in managing separate testing environments.

Enabling Review Apps in your Heroku account means opting for more efficient, reliable, and collaborative software development.

Knapsack Configuration

Activating Review Apps for your Knapsack workspace involves a series of straightforward steps.

Before we dive into the details, it's important to note:

  • Enabling this feature requires the creation of a separate Heroku team account for your workspace.
  • This is done to ensure that the additional resources consumed by Review Apps (like dynos) are properly managed and isolated to your application.
  • We will invite you to your new Heroku team account as a part of this flow.

Once everything is configured, we forward the billing for the additional costs associated with the Review Apps feature to you. This is to ensure that you maintain complete control over your resources and can directly monitor any additional charges. Please work with your Account Executive or Customer Success Manager to set up the proper billing workflow and gain the necessary approvals.

Getting Started

The following steps will guide you through the process of enabling Review Apps for your Knapsack workspace:

  1. Initiating the Process: To start the journey towards enabling Review Apps in your Knapsack workspace, please get in touch with your dedicated Customer Success or Account Representative. Alternatively, you can send an email to help@knapsack.cloud.
  2. Repository Access: If we don't currently have direct access to your repository—perhaps because your workspace was migrated—we'll need to collaborate with a member of your team who has administrative access to the repository. This step is crucial for installing and configuring the necessary GitHub apps.
  3. Adjusting the Workspace: After securing the necessary permissions, we'll proceed to tweak your Knapsack workspace. Specifically, we'll remove the existing deploy action from your GitHub Actions workflows. This change is important because, going forward, all deployments will be managed via the new GitHub app integration.
  4. Timing the Changes: We advise holding off on pushing these modifications until the GitHub app is fully installed and configured. You're now ready to proceed to the next step, "Configuring the GitHub App".

Configuring the GitHub App

  1. First, we'll need to connect your GitHub account with Heroku and then link the specific repository of the app you want to deploy.
    1. This is handled through logging into the Heroku dashboard and navigating to the "Deploy" section.
    2. Here you will see the option to connect your GitHub account and will be able to select the repository to sync.
  2. After that, we'll need to set up a Heroku Pipeline and enable Review Apps for it.
    1. While setting up the Review Apps, you can decide whether you want Heroku to create a new app for each pull request manually or automatically.
  3. Once enabled, Heroku creates a new Review App for every pull request that's opened on the GitHub repository.
    1. It deploys the exact version of your code that is reflected by the pull request.
  4. The Review App is accessible via a unique URL, so you can interact with it just as you would with a regular app on Heroku.
  5. After the pull request is closed (either by merging or just closing without merging), the Review App is destroyed automatically, including all associated add-ons and data.

Pulling it all together 🎉

Now that we've configured the integration — its time to run some quick tests to verify everything is configured correctly.

  • Testing main deployments — earlier in this process we recommended waiting to push the changes to the repo until the integration was configured. Push those changes now!
    • This should automatically kick off a deployment and you should see your updates appear in roughly 7-10 minutes.
  • Testing per-pr deployments — now that we've got the main branch updated to no longer use GitHub Actions for the Heroku deployments, we can now test the review apps feature.
    • We recommend creating a new branch within the Knapsack Cloud UI and submitting a "Request Review".
    • If you view the pull request — you'll eventually see a deployment show up that points to your new review app!

Support

Reach out to your Knapsack representative or email us at help@knapsack.cloud if you run into any issues along the way.