Skip to content

localstack/setup-localstack

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

Setup LocalStack

LocalStack Test

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

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