AWS SQS Create Queue

A GitHub Action to create AWS SQS queues. Seamlessly integrate queue creation into your CI/CD workflows with support for standard and FIFO queues.

Features

• Create queues - Create standard or FIFO SQS queues
• Skip if exists - Optionally succeed without error if queue already exists
• FIFO support - Full support for FIFO queues with throughput limits and deduplication
• Queue configuration - Configure visibility timeout, message retention, delays, and more
• Tags - Support for queue tagging
• Encryption - Support for KMS server-side encryption
• Simple integration - Easy to use in GitHub Actions workflows

Prerequisites

Configure AWS credentials before using this action.

Option 1: AWS Credentials (Production)

Use aws-actions/configure-aws-credentials@v4 for real AWS environments:

- name: Configure AWS Credentials
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::123456789012:role/my-github-actions-role
    aws-region: us-east-1

Option 2: LocalStack (Testing)

Use LocalStack as a service container for local testing:

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      localstack:
        image: localstack/localstack
        ports:
          - 4566:4566
        env:
          SERVICES: sqs
    steps:
      - name: Create queue in LocalStack
        uses: predictr-io/aws-sqs-create-queue@v0
        env:
          AWS_ENDPOINT_URL: http://localhost:4566
          AWS_ACCESS_KEY_ID: test
          AWS_SECRET_ACCESS_KEY: test
          AWS_DEFAULT_REGION: us-east-1
        with:
          queue-name: 'test-queue'
          queue-type: 'standard'

Usage

Create Standard Queue

Create a basic standard SQS queue:

- name: Create SQS queue
  uses: predictr-io/aws-sqs-create-queue@v0
  with:
    queue-name: 'my-queue'
    queue-type: 'standard'

Create FIFO Queue

Create a FIFO queue:

- name: Create FIFO queue
  uses: predictr-io/aws-sqs-create-queue@v0
  with:
    queue-name: 'my-queue.fifo'
    queue-type: 'fifo'

Create Queue with Skip-If-Exists

Create a queue but succeed without error if it already exists:

- name: Create queue (idempotent)
  uses: predictr-io/aws-sqs-create-queue@v0
  with:
    queue-name: 'my-queue'
    queue-type: 'standard'
    skip-if-exists: 'true'

Create Queue with Custom Configuration

Create a queue with custom settings:

- name: Create configured queue
  uses: predictr-io/aws-sqs-create-queue@v0
  with:
    queue-name: 'my-queue'
    queue-type: 'standard'
    visibility-timeout: '60'
    message-retention-period: '604800'
    max-message-size: '262144'
    delay-seconds: '0'
    receive-wait-time: '20'

Create FIFO Queue with Content-Based Deduplication

Create a FIFO queue with content-based deduplication:

- name: Create FIFO queue with deduplication
  uses: predictr-io/aws-sqs-create-queue@v0
  with:
    queue-name: 'my-events.fifo'
    queue-type: 'fifo'
    content-based-deduplication: 'true'
    fifo-throughput-limit: 'perMessageGroupId'

Create Queue with Tags

Create a queue with tags:

- name: Create tagged queue
  uses: predictr-io/aws-sqs-create-queue@v0
  with:
    queue-name: 'my-queue'
    queue-type: 'standard'
    tags: |
      {
        "Environment": "production",
        "Team": "backend",
        "Project": "my-app"
      }

Create Queue with KMS Encryption

Create a queue with server-side encryption:

- name: Create encrypted queue
  uses: predictr-io/aws-sqs-create-queue@v0
  with:
    queue-name: 'secure-queue'
    queue-type: 'standard'
    kms-master-key-id: 'alias/aws/sqs'
    kms-data-key-reuse-period: '300'

Complete Pipeline Example

Create queue and use outputs:

name: Setup Infrastructure

on:
  push:
    branches: [main]

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

      - name: Configure AWS
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: us-east-1

      - name: Create SQS queue
        id: create-queue
        uses: predictr-io/aws-sqs-create-queue@v0
        with:
          queue-name: 'deployment-queue.fifo'
          queue-type: 'fifo'
          skip-if-exists: 'true'
          content-based-deduplication: 'true'
          tags: |
            {
              "Environment": "production",
              "ManagedBy": "github-actions"
            }

      - name: Save queue URL
        run: |
          echo "Queue URL: ${{ steps.create-queue.outputs.queue-url }}"
          echo "Queue ARN: ${{ steps.create-queue.outputs.queue-arn }}"
          echo "Created: ${{ steps.create-queue.outputs.created }}"

      - name: Update config
        run: |
          echo "QUEUE_URL=${{ steps.create-queue.outputs.queue-url }}" >> $GITHUB_ENV

Inputs

Required Inputs

Input	Description
queue-name	SQS queue name (must end with .fifo for FIFO queues)

Optional Inputs

Input	Description	Default
queue-type	Queue type: standard or fifo	standard
skip-if-exists	If true, succeed without error if queue already exists	false
visibility-timeout	Visibility timeout in seconds (0-43200)	30
message-retention-period	Message retention period in seconds (60-1209600)	345600 (4 days)
max-message-size	Maximum message size in bytes (1024-262144)	262144 (256 KB)
delay-seconds	Delivery delay in seconds (0-900)	0
receive-wait-time	Receive message wait time for long polling (0-20)	0
content-based-deduplication	Enable content-based deduplication for FIFO queues	false
fifo-throughput-limit	FIFO throughput limit: perQueue or perMessageGroupId	perQueue
deduplication-scope	Deduplication scope: queue or messageGroup	queue
tags	Queue tags as JSON object	-
kms-master-key-id	AWS KMS master key ID for encryption	-
kms-data-key-reuse-period	KMS data key reuse period in seconds (60-86400)	300

Outputs

Output	Description
queue-url	URL of the created SQS queue
queue-arn	ARN of the created SQS queue
created	Whether the queue was newly created (true) or already existed (false)

Queue Types

Standard Queue

Default queue type with unlimited throughput and at-least-once delivery:

queue-name: 'my-standard-queue'
queue-type: 'standard'

FIFO Queue

First-In-First-Out queue with exactly-once processing and ordering:

queue-name: 'my-fifo-queue.fifo'
queue-type: 'fifo'

Note: FIFO queue names must end with .fifo suffix.

Skip If Exists

Control behavior when queue already exists:

• skip-if-exists: 'false' (default): Action fails if queue exists
• skip-if-exists: 'true': Action succeeds if queue exists, returns existing queue URL

Example with skip-if-exists:

- name: Create queue (idempotent)
  id: queue
  uses: predictr-io/aws-sqs-create-queue@v0
  with:
    queue-name: 'my-queue'
    skip-if-exists: 'true'

- name: Check if created
  run: |
    if [ "${{ steps.queue.outputs.created }}" == "true" ]; then
      echo "Queue was newly created"
    else
      echo "Queue already existed"
    fi

Tags Format

Tags must be provided as a JSON object:

tags: |
  {
    "Environment": "production",
    "Team": "platform",
    "CostCenter": "engineering"
  }

FIFO Queue Options

Content-Based Deduplication

Automatically deduplicate messages based on content hash:

content-based-deduplication: 'true'

When enabled, you don't need to provide deduplication IDs when sending messages.

FIFO Throughput Limit

Control FIFO throughput scoping:

• perQueue (default): 3000 messages/second across entire queue
• perMessageGroupId: 3000 messages/second per message group

fifo-throughput-limit: 'perMessageGroupId'

Deduplication Scope

Control deduplication scoping:

• queue (default): Deduplication across entire queue
• messageGroup: Deduplication per message group

deduplication-scope: 'messageGroup'

Encryption

Enable server-side encryption with KMS:

kms-master-key-id: 'arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012'
kms-data-key-reuse-period: '300'

You can also use KMS aliases:

kms-master-key-id: 'alias/aws/sqs'

Error Handling

The action handles common scenarios:

• Invalid queue name: Fails with validation error
• FIFO naming mismatch: Fails if FIFO queue doesn't end with .fifo
• Queue already exists: Fails unless skip-if-exists is true
• AWS permission errors: Fails with AWS SDK error message
• Invalid parameters: Fails with validation error for out-of-range values

Development

Setup

Clone and install dependencies:

git clone https://github.com/predictr-io/aws-sqs-create-queue.git
cd aws-sqs-create-queue
npm install

Development Scripts

# Build the action (compile TypeScript + bundle with dependencies)
npm run build

# Run TypeScript type checking
npm run type-check

# Run ESLint
npm run lint

# Run all checks (type-check + lint)
npm run check

Build Process

The build process uses @vercel/ncc to compile TypeScript and bundle all dependencies into a single dist/index.js file:

npm run build

Output:

• dist/index.js - Bundled action (includes AWS SDK)
• dist/index.js.map - Source map for debugging
• dist/licenses.txt - License information for bundled dependencies

Important: The dist/ directory must be committed to git. GitHub Actions runs the compiled code directly from the repository.

Making Changes

1. Edit source files in src/
2. Run checks to validate:

   npm run check

3. Build to update dist/:

   npm run build

4. Test locally (optional) - Use act or create a test workflow
5. Commit everything including dist/:

   git add src/ dist/
   git commit -m "Description of changes"

License

MIT