-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
11 changed files
with
490 additions
and
86 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,34 +8,120 @@ A GitHub Action to setup [LocalStack](https://github.com/localstack/localstack) | |
| - Pulling a specific version of the LocalStack Docker Image into the GitHub Action runner. | ||
| - Configuring the [LocalStack CLI](https://docs.localstack.cloud/get-started/#localstack-cli) to launch the Docker container with an optional API token for pro usage. | ||
| - Installing [LocalStack AWS CLI](https://github.com/localstack/awscli-local), a thin wrapper around the `aws` command line interface for use with LocalStack to run integration tests over AWS services. | ||
| - Export/import [LocalStack state](https://docs.localstack.cloud/user-guide/state-management/export-import-state/) as an artifact | ||
| - Save/load [LocalStack Cloud Pods](https://docs.localstack.cloud/user-guide/state-management/cloud-pods/) | ||
| - Start/stop a [LocalStack Ephemeral Instance](https://docs.localstack.cloud/user-guide/cloud-sandbox/application-previews/) _(EXPERIMENTAL)_ | ||
|
|
||
| ## Usage | ||
|
|
||
| To get started, you can use this minimal example: | ||
| ### Get started with a minimal example | ||
|
|
||
| ```yml | ||
| - name: Start LocalStack | ||
| uses: LocalStack/setup-localstack@v0.1.2 | ||
| uses: LocalStack/setup-localstack@v0.2.0 | ||
| 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. | ||
|
|
||
| ### Inputs | ||
| ### Install only CLIs and startup later | ||
| ```yml | ||
| - 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 | ||
| ```yml | ||
| - 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 | ||
| ```yml | ||
| - 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 App Preview (Ephemeral Instance) | ||
| ```yml | ||
| uses: LocalStack/setup-localstack@$v0.2.0 | ||
| 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/setup-localstack@${{ env.GH_ACTION_VERSION }} | ||
| with: | ||
| github-token: ${{ secrets.GITHUB_TOKEN }} | ||
| state-backend: ephemeral | ||
| state-action: stop | ||
| env: | ||
| LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }} | ||
| ``` | ||
| ## Inputs | ||
| | Input | Description | Default | | ||
| | ------------------ | -------------------------------------------------------------------------------- | -------- | | ||
| | `ci-project` | Name of the CI project to track in LocalStack Cloud | | | ||
| | `configuration` | Configuration variables to use while starting LocalStack container | `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` | | ||
| | `configuration` | Configuration variables to use while starting LocalStack container | `None` | | ||
| | `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` | | ||
|
|
||
| > **NOTE**: The `LOCALSTACK_API_KEY` environment variable is required to be set if `use-pro` is set to `true`. | ||
|
|
||
| ### Example workflow | ||
|
|
||
| ## Example workflow | ||
| ```yml | ||
| name: LocalStack Test | ||
| on: [ push, pull_request ] | ||
|
|
@@ -48,20 +134,33 @@ jobs: | |
| - uses: actions/checkout@v3 | ||
| - name: Start LocalStack | ||
| uses: LocalStack/setup-localstack@v0.1.2 | ||
| uses: LocalStack/setup-localstack@v0.2.0 | ||
| 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!" | ||
| 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 | ||
|
|
||
Oops, something went wrong.