localstack · steffyP · Jan 19, 2026 · Jan 21, 2026 · Jan 21, 2026 · Jan 21, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -9,35 +9,6 @@ on:
     - cron: '48 23 * * 0'
 
 jobs:
-  localstack-action-test:
-    name: 'Test LocalStack GitHub Action'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
-
-      # We must hack the action call as remote to be able to use the relative paths
-      # Could it break with different CWD? 🤔
-      - name: Start LocalStack
-        uses: jenseng/dynamic-uses@8bc24f0360175e710da532c4d19eafdbed489a06 # v1
-        with:
-          uses: LocalStack/setup-localstack@${{ env.GH_ACTION_VERSION }}
-          with: |-
-            {
-              "image-tag": "latest",
-              "install-awslocal": "true",
-              "configuration": "DEBUG=1",
-              "use-pro": "true",
-            }
-        env:
-          LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
-          GH_ACTION_VERSION: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
-
-      - name: Run Tests Against LocalStack
-        run: |
-          awslocal s3 mb s3://test
-          awslocal s3 ls
-          echo "Test Execution complete!"
-
   localstack-action-version-test:
     name: 'Test LocalStack Version with Github Actions'
     runs-on: ubuntu-latest
@@ -58,17 +29,20 @@ jobs:
               "use-pro": "true",
             }
         env:
-          LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
-          GH_ACTION_VERSION: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+          # intentially left `LOCALSTACK_API_KEY` as env here, to ensure the fallback still works for old version
+          LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }} 
+          GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}
 
       - name: Run Version Test Against LocalStack
         run: |
           LS_VERSION=$(docker ps | grep localstack | cut -d " " -f4 | cut -d ":" -f2)
           exit $(test "x${LS_VERSION}" = "x3.2.0")
 
-  cloud-pods-test:
+  cloud-pods-save-test:
     name: 'Test Cloud Pods Action'
     runs-on: ubuntu-latest
+    outputs:
+      pod-name: ${{ steps.pod_name.outputs.name }}
     steps:
       - name: ⚡️ Checkout the repository
         uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
@@ -85,8 +59,12 @@ jobs:
               "use-pro": "true",
             }
         env:
-          LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
-          GH_ACTION_VERSION: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+          LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
+          GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}
+
+      - name: Generate random pod name
+        id: pod_name
+        run: echo "name=cloud-pods-test-$RANDOM" >> $GITHUB_OUTPUT
 
       - name: Run AWS commands
         run: |
@@ -99,21 +77,29 @@ jobs:
           uses: LocalStack/setup-localstack@${{ env.GH_ACTION_VERSION }}
           with: |-
             {
-              "state-name": "cloud-pods-test",
+              "state-name": "${{ steps.pod_name.outputs.name }}",
               "state-action": "save",
             }
         env:
-          LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
-          GH_ACTION_VERSION: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+          LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
+          GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}
 
-  local-state-test:
-    name: 'Test Local State Action'
+      - name: Verify Cloud Pod
+        run: |
+          localstack pod list | grep ${{ steps.pod_name.outputs.name }}
+        env:
+          LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
+
+
+  load-cloud-pod-test:
+    name: 'Test Loading Cloud Pod'
     runs-on: ubuntu-latest
+    needs: cloud-pods-save-test
     steps:
       - name: ⚡️ Checkout the repository
         uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
 
-      - name: Start LocalStack
+      - name: Start LocalStack and Load Pod
         uses: jenseng/dynamic-uses@8bc24f0360175e710da532c4d19eafdbed489a06 # v1
         with:
           uses: LocalStack/setup-localstack@${{ env.GH_ACTION_VERSION }}
@@ -123,31 +109,108 @@ jobs:
               "install-awslocal": "true",
               "configuration": "DEBUG=1",
               "use-pro": "true",
-              "state-name": "cloud-pods-test",
-              "state-action": "load",
-              "state-backend": "local",
+              "state-name": "${{ needs.cloud-pods-save-test.outputs.pod-name }}",
+              "state-action": "load"
             }
         env:
-          LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
-          GH_ACTION_VERSION: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+          LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
+          GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}
 
-      - name: Run AWS Commands
+      - name: Verify loaded resources
         run: |
-          awslocal s3 mb s3://test
-          awslocal s3 rb s3://test
-          awslocal sqs create-queue --queue-name test-queue
-          awslocal sqs delete-queue --queue-url $(awslocal sqs get-queue-url --queue-name test-queue --output text)
+          echo "Verifying S3 bucket..."
+          awslocal s3 ls | grep "test"
+          echo "Verifying SQS queue..."
+          awslocal sqs list-queues | grep "test-queue"
+
+      - 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 }}
+
+
+      - name: Verify successful cleanup of Cloud Pod
+        run: |
+          echo "Verifying that the pod has been deleted..."
+          if localstack pod list | grep -q ${{ needs.cloud-pods-save-test.outputs.pod-name }}; then
+            echo "Cleanup failed! Pod ${{ needs.cloud-pods-save-test.outputs.pod-name }} was not deleted."
+            exit 1
+          fi
+          echo "Pod successfully deleted."
+        env:
+          LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
+
+
+  local-state-save-test:
+    name: 'Test Local State Save Action'
+    runs-on: ubuntu-latest
+    steps:
+      - name: ⚡️ Checkout the repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+
+      - name: Start LocalStack
+        uses: jenseng/dynamic-uses@8bc24f0360175e710da532c4d19eafdbed489a06 # v1
+        with:
+          uses: LocalStack/setup-localstack@${{ env.GH_ACTION_VERSION }}
+          with: |-
+            {
+              "image-tag": "latest",
+              "install-awslocal": "true",
+              "configuration": "DEBUG=1",
+              "use-pro": "true",
+            }
+        env:
+          LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
+          GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}
+
+      - name: Run AWS commands
+        run: |
+          awslocal s3 mb s3://test-local
+          awslocal sqs create-queue --queue-name test-queue-local
 
       - name: Save the State Artifact
         uses: jenseng/dynamic-uses@8bc24f0360175e710da532c4d19eafdbed489a06 # v1
         with:
           uses: LocalStack/setup-localstack@${{ env.GH_ACTION_VERSION }}
           with: |-
             {
-              "state-name": "cloud-pods-test",
+              "state-name": "local-pods-test",
               "state-action": "save",
               "state-backend": "local",
             }
         env:
-          LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
+          LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
+          GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}
+
+  local-state-load-test:
+    name: 'Test Local State Load Action'
+    needs: local-state-save-test
+    runs-on: ubuntu-latest
+    steps:
+      - name: ⚡️ Checkout the repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+
+      - name: Start LocalStack
+        uses: jenseng/dynamic-uses@8bc24f0360175e710da532c4d19eafdbed489a06 # v1
+        with:
+          uses: LocalStack/setup-localstack@${{ env.GH_ACTION_VERSION }}
+          with: |-
+            {
+              "image-tag": "latest",
+              "install-awslocal": "true",
+              "configuration": "DEBUG=1",
+              "use-pro": "true",
+              "state-name": "local-pods-test",
+              "state-action": "load",
+              "state-backend": "local",
+            }
+        env:
+          LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_API_KEY }}
           GH_ACTION_VERSION: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+
+      - name: Run AWS Commands
+        run: |
+          echo "Verifying S3 bucket..."
+          awslocal s3 ls | grep "test-local"
+          echo "Verifying SQS queue..."
+          awslocal sqs list-queues | grep "test-queue-local"
diff --git a/.github/workflows/ephemeral.yml b/.github/workflows/ephemeral.yml
@@ -1,5 +1,10 @@
 name: LocalStack Ephemeral Instance Test
-on:  pull_request
+on:  
+  pull_request:
+    paths-ignore:
+      - ./*.md
+      - LICENSE
+  workflow_dispatch:
 
 jobs:
   preview-test:
@@ -26,7 +31,7 @@ jobs:
             }
         env:
           LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
-          GH_ACTION_VERSION: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+          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
             awslocal sqs create-queue --queue-name=test-queue
@@ -78,4 +83,4 @@ jobs:
             }
         env:
           LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }}
-          GH_ACTION_VERSION: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+          GH_ACTION_VERSION: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.sha) || github.ref_name }}
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Harsh Mishra
+Copyright (c) 2022-2026 LocalStack
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -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/)
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 }}
 
 ...
 
@@ -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
@@ -122,7 +122,7 @@ with:
 | `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
@@ -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: |
@@ -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 }}
 ```
 

diff --git a/action.yml b/action.yml
@@ -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:

diff --git a/cloud-pods/action.yml b/cloud-pods/action.yml
@@ -1,4 +1,5 @@
 name: 'Save/Load a LocalStack Cloud Pod'
+description: 'Save or load a LocalStack Cloud Pod'
 
 inputs:
   name:

diff --git a/finish/action.yml b/finish/action.yml
@@ -1,4 +1,5 @@
 name: Finish CI Build
+description: Finish CI Build
 
 inputs:
   github-token: