README.md

Setup LocalStack

A GitHub Action to setup LocalStack on your GitHub Actions runner workflow by:

• Pulling a specific version of the LocalStack Docker Image into the GitHub Action runner.
• Configuring the LocalStack CLI to launch the Docker container with an optional API token for pro usage.
• Installing LocalStack AWS CLI, a thin wrapper around the aws command line interface for use with LocalStack to run integration tests over AWS services.
• Export/import LocalStack state as an artifact
• Save/load LocalStack Cloud Pods
• Start/stop a LocalStack Ephemeral Instance (PREVIEW)

Usage

Get started with a minimal example

- name: Start LocalStack
  uses: LocalStack/[email protected]
  with:
    image-tag: 'latest'
    install-awslocal: 'true'
  env:
    LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}

NOTE: The LOCALSTACK_API_KEY environment variable is required to be set if use-pro is set to true.
If the key is not found LocalStack by default falls back to the CE edition and displays a warning.

Install only CLIs and startup later

- name: Install LocalStack CLIs
  uses: LocalStack/[email protected]
  with:
    skip-startup: 'true'
    install-awslocal: 'true'

...

- name: Start LocalStack
  uses: LocalStack/[email protected]
  with:
    image-tag: 'latest'
  env:
    LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}

Save a state later on in the pipeline

- name: Save LocalStack State
  uses: LocalStack/[email protected]
  with:
    install-awslocal: 'true'
    state-backend: cloud-pods
    state-action: save
    state-name: my-cloud-pod
  env:
    LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}

NOTE: The LOCALSTACK_API_KEY environment variable is required to be set to save/load LocalStack's state either as a Cloud Pod or as a file artifact.

Load an already saved state

- name: Start LocalStack and Load State
  uses: LocalStack/[email protected]
  with:
    install-awslocal: 'true'
    state-backend: cloud-pods
    state-action: load
    state-name: my-cloud-pod
  env:
    LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}

NOTE: To load a local state from a different GitHub Actions workflow, one must set the WORKFLOW_ID environment variable.

NOTE: The LOCALSTACK_API_KEY environment variable is required to be set to save/load LocalStack's state either as a Cloud Pod or as a file artifact.

Manage Application Previews (on an Ephemeral Instance)

uses: LocalStack/[email protected]
  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 }}

...

with:
  uses: LocalStack/[email protected]
  with:
      github-token: ${{ secrets.GITHUB_TOKEN }}
      state-backend: ephemeral
      state-action: stop
  env:
    LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}

Inputs

Input	Description	Default
auto-load-pod	Which pod to load on startup of LocalStack (application preview)	None
ci-project	Name of the CI project to track in LocalStack Cloud
configuration	Configuration variables to use while starting LocalStack container	None
extension-auto-install	Which extensions to install on startup of LocalStack (application preview)	None
github-token	Github token used to create PR comments
image-tag	Tag of the LocalStack Docker image to use	latest
include-preview	Whether to include the created Ephemeral Instance URL in the PR comment	false
install-awslocal	Whether to install the awslocal CLI into the build environment	true
lifetime	How long an ephemeral instance should live	30
preview-cmd	Command(s) used to create a Ephemeral Instance of the PR (can use $AWS_ENDPOINT_URL)
skip-ephemeral-stop	Skip stopping LocalStack Ephemeral Instance	false
skip-startup	Explicitly prevent LocalStack start up, only installs CLI(s). Recommended to manage state later on in the pipeline or start up an ephemeral instance.	false
skip-wait	Skip waiting for LocalStack to start up	false
state-action	Valid values are load, save, start, stop, `` (empty, don't manage state). Values start/`stop` only usable with app previews.	``
state-backend	Either store the state of LocalStack locally, as a Cloud Pod or start an Ephemeral Instance. Valid values are cloud-pods, ephemeral or local. Use this option in unison with state-action to control behaviour.	cloud-pods
state-name	Name of the state artifact (without extension)	false
use-pro	Whether to use the Pro version of LocalStack (requires API key to be configured)	false

Example workflow

name: LocalStack Test
on: [ push, pull_request ]

jobs:
  localstack-action-test:
    name: 'Test LocalStack GitHub Action'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Start LocalStack
        uses: LocalStack/[email protected]
        with:
          image-tag: 'latest'
          install-awslocal: 'true'
          configuration: DEBUG=1
          use-pro: 'true'
          state-backend: cloud-pods
          state-action: load
          state-name: my-cloud-pod
        env:
          LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}

      - name: Run Tests against LocalStack
        run: |
          awslocal s3 mb s3://test
          awslocal s3 ls
          echo "Test Execution complete!"

      - name: Save LocalStack State
        uses: LocalStack/[email protected]
        with:
          state-backend: local
          state-action: save
          state-name: my-ls-state-artifact
        env:
          LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
          WORKFLOW_ID: ${{ env.MY_GOLDEN_LS_STATE }}

License

MIT License