Application Preview

Introduction

Application Preview generates a preview environment from GitHub Pull Requests (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. This file should contain the CI pipeline that activates on every pull request.

The pipeline deploys the application to a LocalStack Ephemeral Instance using a deploy.sh script or similar for full application deployment. A comment containg the preview link is automatically added to a Pull Request when created.

uses: LocalStack/setup-localstack@v0.2.2
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 }}

You must also set the LOCALSTACK_API_KEY as a repository secret, available from the LocalStack Web Application. The GITHUB_TOKEN is automatically generated by GitHub and requires no further configuration.

Stop the Application Preview

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