Skip to content

cleanup: add descriptions, update auth-token usage #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
steffyP merged 4 commits into from
Jan 27, 2026
Merged

cleanup: add descriptions, update auth-token usage #56

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d5dcd6e
add description to actions and replace reference to api-key with auth…
steffyP Jan 21, 2026
2b2dd71
change referenced of LOCALSTACK_API_KEY to LOCALSTACK_AUTH_TOKEN in R…
steffyP Jan 21, 2026
54bae55
changed year and ownership in the LICENSE file
steffyP Jan 21, 2026
3757038
replace secrets usage to use LOCALSTACK_AUTH_TOKEN
steffyP Jan 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 11 additions & 10 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,8 @@ jobs:
"use-pro": "true",
}
env:
LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
# intentially left `LOCALSTACK_API_KEY` as env here, to ensure the fallback still works for old version
LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}

- name: Run Version Test Against LocalStack
Expand Down Expand Up @@ -58,7 +59,7 @@ jobs:
"use-pro": "true",
}
env:
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}

- name: Generate random pod name
Expand All @@ -80,14 +81,14 @@ jobs:
"state-action": "save",
}
env:
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}

- name: Verify Cloud Pod
run: |
localstack pod list | grep ${{ steps.pod_name.outputs.name }}
env:
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}


load-cloud-pod-test:
Expand All @@ -112,7 +113,7 @@ jobs:
"state-action": "load"
}
env:
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}

- name: Verify loaded resources
Expand All @@ -125,7 +126,7 @@ jobs:
- name: Clean up remote pod
run: localstack pod delete ${{ needs.cloud-pods-save-test.outputs.pod-name }}
env:
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}


- name: Verify successful cleanup of Cloud Pod
Expand All @@ -137,7 +138,7 @@ jobs:
fi
echo "Pod successfully deleted."
env:
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}


local-state-save-test:
Expand All @@ -159,7 +160,7 @@ jobs:
"use-pro": "true",
}
env:
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}

- name: Run AWS commands
Expand All @@ -178,7 +179,7 @@ jobs:
"state-backend": "local",
}
env:
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}

local-state-load-test:
Expand All @@ -204,7 +205,7 @@ jobs:
"state-backend": "local",
}
env:
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
GH_ACTION_VERSION: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.ref_name }}

- name: Run AWS Commands
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/ephemeral.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ jobs:
"extension-auto-install": "localstack-extension-mailhog",
}
env:
LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}
PREVIEW_CMD: |-
awslocal s3 mb s3://test-bucket
Expand Down Expand Up @@ -78,5 +78,5 @@ jobs:
"state-action": "stop"
}
env:
LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}
2 changes: 1 addition & 1 deletion LICENSE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
MIT License

Copyright (c) 2022 Harsh Mishra
Copyright (c) 2022-2026 LocalStack
Copy link
Member Author

@steffyP steffyP Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Q: is that the right way to do it? Happy to change it back, but I guess as we have the action in the organization it makes more sense to use "LocalStack"?

Copy link
Member

@alexrashed alexrashed Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, looks good to me! Imho this is only there for historical reasons, the action was handed over from @HarshCasper early after the initial creation. However, maybe we could just adjust it according to @HarshCasper's directions in a follow up.


Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
28 changes: 14 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
A GitHub Action to setup [LocalStack](https://github.com/localstack/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](https://docs.localstack.cloud/get-started/#localstack-cli) to launch the Docker container with an optional API token for pro usage.
- Configuring the [LocalStack CLI](https://docs.localstack.cloud/get-started/#localstack-cli) to launch the Docker container with an optional Auth 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/)
Expand All @@ -23,9 +23,9 @@ A GitHub Action to setup [LocalStack](https://github.com/localstack/localstack)
image-tag: 'latest'
install-awslocal: 'true'
env:
LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
```
> **NOTE**: The `LOCALSTACK_API_KEY` environment variable is required to be set if `use-pro` is set to `true`.
> **NOTE**: The `LOCALSTACK_AUTH_TOKEN` 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
Expand All @@ -43,7 +43,7 @@ If the key is not found LocalStack by default falls back to the CE edition and d
with:
image-tag: 'latest'
env:
LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
```

### Save a state later on in the pipeline
Expand All @@ -56,9 +56,9 @@ If the key is not found LocalStack by default falls back to the CE edition and d
state-action: save
state-name: my-cloud-pod
env:
LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
```
> **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.
> **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
```yml
Expand All @@ -70,11 +70,11 @@ If the key is not found LocalStack by default falls back to the CE edition and d
state-action: load
state-name: my-cloud-pod
env:
LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
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_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.
> **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)
```yml
Expand All @@ -88,7 +88,7 @@ uses: LocalStack/setup-localstack@v0.2.3
# Optional script/command to run
preview-cmd: deploy.sh
env:
LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}

...

Expand All @@ -99,7 +99,7 @@ with:
state-backend: ephemeral
state-action: stop
env:
LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
```

## Inputs
Expand All @@ -119,10 +119,10 @@ with:
| `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-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` |
| `use-pro` | Whether to use the Pro version of LocalStack (requires Auth Token to be configured) | `false` |

## Example workflow
```yml
Expand All @@ -147,7 +147,7 @@ jobs:
state-action: load
state-name: my-cloud-pod
env:
LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}

- name: Run Tests against LocalStack
run: |
Expand All @@ -162,7 +162,7 @@ jobs:
state-action: save
state-name: my-ls-state-artifact
env:
LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
WORKFLOW_ID: ${{ env.MY_GOLDEN_LS_STATE }}
```

Expand Down
2 changes: 1 addition & 1 deletion action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ inputs:
required: true
default: 'true'
use-pro:
description: 'Whether to use LocalStack Pro (requires a valid API key)'
description: 'Whether to use LocalStack Pro (requires a valid CI Auth Token)'
required: false
default: 'false'
configuration:
Expand Down
1 change: 1 addition & 0 deletions cloud-pods/action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
name: 'Save/Load a LocalStack Cloud Pod'
description: 'Save or load a LocalStack Cloud Pod'

inputs:
name:
Expand Down
1 change: 1 addition & 0 deletions finish/action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
name: Finish CI Build
description: Finish CI Build

inputs:
github-token:
Expand Down
1 change: 1 addition & 0 deletions local/action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
name: 'Save/Load LocalStack state'
description: 'Save or load LocalStack state'

inputs:
name:
Expand Down
1 change: 1 addition & 0 deletions prepare/action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
name: Start CI Build
description: Start CI Build

inputs:
github-token:
Expand Down
5 changes: 3 additions & 2 deletions startup/action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
name: 'Start up Localstack'
description: 'Starts up Localstack'

inputs:
image-tag:
Expand All @@ -10,7 +11,7 @@ inputs:
required: true
default: 'true'
use-pro:
description: 'Whether to use LocalStack Pro (requires a valid API key)'
description: 'Whether to use LocalStack Pro (requires a valid CI Auth Token)'
required: false
default: 'false'
configuration:
Expand Down Expand Up @@ -62,7 +63,7 @@ runs:
run: |
if [ "$USE_PRO" = true ]; then
if [ "x$LOCALSTACK_AUTH_TOKEN" = "x" -o "x$LOCALSTACK_API_KEY" = "x" ]; then
echo "WARNING: LocalStack API key not detected, please verify your configuration..."
echo "WARNING: LocalStack Auth Token not detected, please verify your configuration..."
fi
CONFIGURATION="DNS_ADDRESS=127.0.0.1 ${CONFIGURATION}"
IMAGE_NAME="${IMAGE_NAME:-localstack/localstack-pro:${IMAGE_TAG}}"
Expand Down
1 change: 1 addition & 0 deletions tools/action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
name: 'Install Localstack tools'
description: 'Installs `localstack` and optionally `awslocal` CLI'

inputs:
install-awslocal:
Expand Down