GitHub Actions

Use LocalStack in GitHub Actions

This guide shows you how to start LocalStack in a Github Actions job.

Setting up your Github Actions job

In order to start LocalStack, we recommend to start it in a separate build step, to separate its log output / status from the rest of your job.

We recommend taking the following steps:

  • Install the LocalStack CLI (and maybe also awslocal).
  • Make sure your LocalStack docker image is up-to-date by pulling the latest version.
  • Use the LocalStack CLI to start LocalStack. Make sure to use the -d flag to start the LocalStack docker container in detached mode.
  • Wait for the container to report that it is up and running.

An official GitHub action for this also planned, to make the configuration easier and less verbose.

The following example can be integrated into your GitHub workflow. As an example, it will use awslocal to create bucket and list it afterwards.

  1. name: localstack-action-example
  2. on: push
  3. jobs:
  4.   example-job:
  5.     runs-on: ubuntu-latest
  6.     steps:
  7.       - name: Start LocalStack
  8.         env:
  9.           LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
  10.         run: |
  11.           # install LocalStack cli and awslocal
  12.           pip install localstack awscli-local[ver1]
  13.           # Make sure to pull the latest version of the image
  14.           docker pull localstack/localstack
  15.           # Start LocalStack in the background
  16.           localstack start -d
  17.           # Wait 30 seconds for the LocalStack container to become ready before timing out
  18.           echo "Waiting for LocalStack startup..."
  19.           localstack wait -t 30
  20.           echo "Startup complete"          
  21.       - name: Run some Tests against LocalStack
  22.         run: |
  23.           awslocal s3 mb s3://test
  24.           awslocal s3 ls
  25.           echo "Test Execution complete!"

If you want to add further configuration for LocalStack, you can use the env section of your build step to set the configuration variables as described here.

Activating LocalStack Pro

If you want to use LocalStack Pro in your GitHub Actions job, you should use a Github Encrypted Secret to store your API key securely. In the above example, you can see us setting the LOCALSTACK_API_KEY environment variable to the value of the secret LOCALSTACK_API_KEY.

You can set your secret at an environment, repository or organization level, for more information see here. In the simplest case, you just set it at the repository level. For this, you go, in your repository, to Settings => Secrets and press “New Repository Secret”.

There, you create the secret for your API key like in the following image, replacing foobar with your API key.

Adding the LocalStack API key as secret in GitHub

Last modified November 24, 2021: update CI examples to use localstack>=0.13.0.1 CLI features (03ff7715)