GitHub - localstack/setup-localstack: Sets up LocalStack CLI in your GitHub Actions workflow ☁️

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 Auth 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

Pin to v0.3.2 or later. v0.3.2 is the first release published with GitHub Immutable Releases enabled, meaning its tag and assets cannot be modified or deleted. Pinning to an immutable tag (or its commit SHA) protects your workflow from supply-chain tampering.

Get started with a minimal example

- name: Start LocalStack
  uses: LocalStack/setup-localstack@v0.3.2
  with:
    image-tag: 'latest'
    install-awslocal: 'true'
  env:
    LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}

NOTE: The LOCALSTACK_AUTH_TOKEN environment variable is required. Since use-pro now defaults to true, the action will use the Pro image by default. The use-pro input will be removed in a future release.

Install only CLIs and startup later

- name: Install LocalStack CLIs
  uses: LocalStack/setup-localstack@v0.3.2
  with:
    skip-startup: 'true'
    install-awslocal: 'true'

...

- name: Start LocalStack
  uses: LocalStack/setup-localstack@v0.3.2
  with:
    image-tag: 'latest'
  env:
    LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}

Save a state later on in the pipeline

- name: Save LocalStack State
  uses: LocalStack/setup-localstack@v0.3.2
  with:
    install-awslocal: 'true'
    state-backend: cloud-pods
    state-action: save
    state-name: my-cloud-pod
  env:
    LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}

NOTE: The LOCALSTACK_AUTH_TOKEN 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/setup-localstack@v0.3.2
  with:
    install-awslocal: 'true'
    state-backend: cloud-pods
    state-action: load
    state-name: my-cloud-pod
  env:
    LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}

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

NOTE: The LOCALSTACK_AUTH_TOKEN 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/setup-localstack@v0.3.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_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}

...

with:
  uses: LocalStack/setup-localstack@v0.3.2
  with:
      github-token: ${{ secrets.GITHUB_TOKEN }}
      state-backend: ephemeral
      state-action: stop
  env:
    LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}

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 Auth Token to be configured). Will be removed in a future release.	`true`

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/setup-localstack@v0.3.2
        with:
          image-tag: 'latest'
          install-awslocal: 'true'
          configuration: DEBUG=1
          state-backend: cloud-pods
          state-action: load
          state-name: my-cloud-pod
        env:
          LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}

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

      - name: Save LocalStack State
        uses: LocalStack/setup-localstack@v0.3.2
        with:
          state-backend: local
          state-action: save
          state-name: my-ls-state-artifact
        env:
          LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
          WORKFLOW_ID: ${{ env.MY_GOLDEN_LS_STATE }}

License

MIT License