Application Preview

Introduction

Application Preview generates a preview environment from GitHub Actions workflows. For example, you can create a preview URL for every GitHub Pull Request (PRs). It allows temporary deployment of AWS powered applications on a LocalStack Ephemeral Instance to preview changes. This feature is currently only available for GitHub repositories that use GitHub Actions.

Getting started

This guide is designed for users new to Application Preview and assumes basic knowledge of GitHub Actions. We will configure a CI pipeline that runs on pull requests using GitHub Actions.

Prerequisites

• LocalStack Account
• GitHub Account

Create the Application Preview

To create an Application Preview, use the LocalStack/setup-localstack action.

Create a file named preview-pipeline.yml in the .github/workflows directory of your custom repository. The example below contains the details that can be used for a step in an existing CI pipeline that activates on every pull request.

The pipeline deploys the application to a LocalStack Ephemeral Instance. The steps necessary for building and deploying the application to LocalStack should be listed within the preview-cmd property. The example below aggregates these steps into a single deployment script called deploy.sh. A comment containing the preview link is automatically added to a Pull Request when created. This preview is available for 30 minutes

uses: LocalStack/setup-localstack@v0.2.3
with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    state-backend: ephemeral
    state-action: start
    # Adding this option prevents Ephemeral Instance to be stopped after the `preview-cmd` run
    skip-ephemeral-stop: 'true'
    # Optional script/command to run
    preview-cmd: deploy.sh
env:
    LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}

The LOCALSTACK_API_KEY must be set as a repository secret. You can create a CI key via the LocalStack Web Application (note that you may need permission from your administrator to access this capability). To add this secret to a GitHub repository, go to the “Settings” tab and then on the left-hand navigation choose “Secrets and variables” and then “Actions”. The GITHUB_TOKEN is automatically generated by GitHub and requires no further configuration.

Stop the Application Preview

It’s important to understand that the ephemeral instance that powers the application preview is created before the steps in the preview-cmd are run. If the preview-cmd fails to complete successfully, the ephemeral instance will still be running on your account. To address this, you can create an additional workflow step that shuts down the ephemeral instance if the workflow run fails (see the GitHub Actions documentation for help in determining whether a workflow completed successfully).

To stop the Application Preview, you can configure the state-action to stop.

uses: LocalStack/setup-localstack@v0.2.2
with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    state-backend: ephemeral
    state-action: stop
env:
    LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}

Configuration

Overriding the Application Preview URL

The Application Preview URL is automatically generated and added as a comment to the Pull Request. However, if your application is served on a different URL, you can override the URL using the LS_PREVIEW_URL. It is beneficial if you are using a CloudFront distribution or a custom domain.

Here is an example of how to override the URL:

preview-cmd: |
    make build;
    make bootstrap;
    make deploy;
    make build-frontend;
    make deploy-frontend;
    distributionId=$(awslocal cloudfront list-distributions | jq -r '.DistributionList.Items[0].Id');
    echo LS_PREVIEW_URL=$AWS_ENDPOINT_URL/cloudfront/$distributionId/ >> $GITHUB_ENV;    

Examples

• Creating ephemeral application previews with LocalStack and GitHub Actions and the example repository