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.

name: localstack-action-example
on: push
    runs-on: ubuntu-latest
      - name: Start LocalStack
        run: |
          # install LocalStack cli and awslocal
          pip install localstack awscli-local[ver1]
          # Make sure to pull the latest version of the image
          docker pull localstack/localstack
          # Start LocalStack in the background
          localstack start -d
          # Wait 30 seconds for the LocalStack container to become ready before timing out
          echo "Waiting for LocalStack startup..."
          localstack wait -t 30
          echo "Startup complete"          
      - name: Run some Tests against LocalStack
        run: |
          awslocal s3 mb s3://test
          awslocal s3 ls
          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