CI/CD Integration

Integrating LocalStack into CI/CD environments enables automated integration testing without cloud infrastructure costs or vendor dependency. CI configurations differ from local development environments in authentication methods and startup workflows.

Key operational differences in CI/CD include:

• Authentication: Use a dedicated CI Auth Token instead of a personal Developer token.
• Initialization: Execute LocalStack in non-interactive mode using Docker Compose, the Docker CLI, or specialized CI actions.
• Isolation: Initialize a fresh LocalStack instance for each job to ensure reproducible test results.
• State Management: Utilize Cloud Pods or state export/import commands to persist infrastructure across pipeline stages.

Step 1: Configure CI Auth Token

Dedicated CI Auth Tokens are required for automated environments to ensure security and auditability.

1. Navigate to the Auth Tokens page in the LocalStack Web Application.
2. Generate a new CI Auth Token.
3. Store the token as a protected secret within your CI provider (e.g., LOCALSTACK_AUTH_TOKEN).

Security Best Practice

Never commit your auth tokens to source control. Always inject tokens via your CI provider’s secrets or environment variable system. Rotate compromised tokens immediately via the Web Application. Old tokens are invalidated instantly.

Note

Read the Auth Token guide for full details on token types and configuration.

Step 2: Start LocalStack in CI

Select the integration method compatible with your CI runner architecture.

GitHub Actions

Use the official GitHub Action to initialize LocalStack as a workflow step:

.github/workflows/integration-tests.yml

name: Integration Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Run tests
        run: |
        # Your test commands here, e.g.:
          pip install awscli-local
          awslocal s3 mb s3://integration-test-bucket
          pytest tests/integration/

The setup-localstack action pulls the image, starts the container, and waits for LocalStack to be ready.

Docker Compose

Define LocalStack as a service in your docker-compose.yml for containerized environments:

services:
  localstack:
    container_name: localstack-main
    image: localstack/localstack-pro
    ports:
      - "127.0.0.1:4566:4566"
      - "127.0.0.1:4510-4559:4510-4559"
    environment:
      - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?}
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"

Start the service and verify readiness before executing tests:

docker compose up -d localstack
# Wait for LocalStack to be ready
until curl -s http://localhost:4566/_localstack/health | grep -q '"running"'; do sleep 1; done

Note

Mounting /var/run/docker.sock is required for Lambda emulation, which uses Docker to run function containers.

Docker CLI

Initialize the container directly using the Docker engine:

docker run \
  --rm -d \
  --name localstack-main \
  -p 127.0.0.1:4566:4566 \
  -p 127.0.0.1:4510-4559:4510-4559 \
  -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \
  -v /var/run/docker.sock:/var/run/docker.sock \
  localstack/localstack-pro

# Wait for readiness
until curl -s http://localhost:4566/_localstack/health | grep -q '"running"'; do sleep 1; done

Technical Comparison: Local vs. CI/CD

Feature	Local Development	CI/CD Environment
Interface	lstk or LocalStack CLI	Docker Compose / docker run, or lstk --non-interactive
Authentication	Browser-based or stored credentials	LOCALSTACK_AUTH_TOKEN environment variable
Token Type	Individual Developer Token	Dedicated CI Token
State	Persistent by choice	Ephemeral (standard) or Snapshotted (Cloud Pods)
Startup Mode	Interactive (TUI) (default lstk)	Non-interactive (Headless) (docker compose, docker run -d, lstk --non-interactive)

State Persistence in CI

While most pipelines favor ephemeral instances for clean test cycles, certain workflows require persisting infrastructure state across jobs or runners.

• Cloud Pods: Save or load snapshots using the setup-localstack action with the state-backend: cloud-pods configuration.
• Snapshot Persistence Engine: Enable PERSISTENCE=1 and mount a host volume to retain data across container restarts on the same runner.
• State Export/Import Commands: Use localstack state export and localstack state import to pass infrastructure state via CI artifacts or caching mechanisms.

Next steps

You have configured LocalStack for automated environments and explored various CI/CD integration patterns. Proceed to the AI & Agent Workflows Guide to learn how to integrate LocalStack with AI coding assistants and automate infrastructure tasks.

Resources

• GitHub Actions Integration: Advanced workflows and configuration options.
• CircleCI Guide: Implementation details for CircleCI environments.
• GitLab CI Integration: Service-based setup for GitLab runners.
• AWS CodeBuild: Native AWS CI/CD integration.