AWS S3 Create Bucket

A GitHub Action to create AWS S3 buckets. Seamlessly integrate bucket creation into your CI/CD workflows with support for versioning, encryption, and access control.

Features

• Create buckets - Create S3 buckets in any AWS region
• Skip if exists - Optionally succeed without error if bucket already exists
• Versioning - Enable or suspend bucket versioning
• Encryption - Support for AES256 and AWS KMS encryption
• Access control - Configure public access block settings
• Object Lock - Enable object lock for compliance (immutable at creation)
• Tags - Support for bucket tagging
• 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: s3
    steps:
      - name: Create bucket in LocalStack
        uses: predictr-io/aws-s3-create-bucket@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:
          bucket-name: 'test-bucket'

Usage

Create Basic Bucket

Create a basic S3 bucket with default settings:

- name: Create S3 bucket
  uses: predictr-io/aws-s3-create-bucket@v0
  with:
    bucket-name: 'my-unique-bucket-name'

Create Bucket in Specific Region

Create a bucket in a specific AWS region:

- name: Create S3 bucket
  uses: predictr-io/aws-s3-create-bucket@v0
  with:
    bucket-name: 'my-bucket-eu'
    region: 'eu-west-1'

Create Bucket with Skip-If-Exists

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

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

Create Bucket with Versioning

Create a bucket with versioning enabled:

- name: Create versioned bucket
  uses: predictr-io/aws-s3-create-bucket@v0
  with:
    bucket-name: 'my-versioned-bucket'
    versioning: 'Enabled'

Create Bucket with KMS Encryption

Create a bucket with AWS KMS encryption:

- name: Create encrypted bucket
  uses: predictr-io/aws-s3-create-bucket@v0
  with:
    bucket-name: 'my-encrypted-bucket'
    encryption: 'aws:kms'
    kms-key-id: 'arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012'

Create Bucket with Public Access Allowed

Create a bucket that allows public access (public access blocked by default):

- name: Create public bucket
  uses: predictr-io/aws-s3-create-bucket@v0
  with:
    bucket-name: 'my-public-bucket'
    block-public-access: 'false'

Create Bucket with Object Lock

Create a bucket with object lock enabled for compliance (cannot be changed after creation):

- name: Create compliance bucket
  uses: predictr-io/aws-s3-create-bucket@v0
  with:
    bucket-name: 'my-compliance-bucket'
    object-lock-enabled: 'true'
    versioning: 'Enabled'  # Required for object lock

Create Bucket with Tags

Create a bucket with tags:

- name: Create tagged bucket
  uses: predictr-io/aws-s3-create-bucket@v0
  with:
    bucket-name: 'my-tagged-bucket'
    tags: |
      {
        "Environment": "production",
        "Team": "backend",
        "Project": "my-app",
        "CostCenter": "engineering"
      }

Create Fully Configured Bucket

Create a bucket with all options:

- name: Create fully configured bucket
  uses: predictr-io/aws-s3-create-bucket@v0
  with:
    bucket-name: 'my-production-bucket'
    region: 'us-west-2'
    versioning: 'Enabled'
    encryption: 'aws:kms'
    kms-key-id: 'arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012'
    block-public-access: 'true'
    skip-if-exists: 'true'
    tags: |
      {
        "Environment": "production",
        "ManagedBy": "github-actions"
      }

Use Outputs

Use the bucket name and ARN in subsequent steps:

- name: Create bucket
  id: create-bucket
  uses: predictr-io/aws-s3-create-bucket@v0
  with:
    bucket-name: 'my-bucket'

- name: Use bucket outputs
  run: |
    echo "Bucket Name: ${{ steps.create-bucket.outputs.bucket-name }}"
    echo "Bucket ARN: ${{ steps.create-bucket.outputs.bucket-arn }}"
    echo "Was Created: ${{ steps.create-bucket.outputs.created }}"

Inputs

Input	Description	Required	Default
bucket-name	S3 bucket name (must be globally unique and DNS-compliant)	Yes	-
region	AWS region for the bucket	No	us-east-1
skip-if-exists	If "true", succeed without error if bucket already exists	No	false
versioning	Enable versioning: "Enabled" or "Suspended"	No	Suspended
encryption	Server-side encryption: "AES256" or "aws:kms"	No	AES256
kms-key-id	KMS key ID for aws:kms encryption (required if encryption is "aws:kms")	No	-
block-public-access	Block all public access: "true" or "false"	No	true
object-lock-enabled	Enable object lock for compliance: "true" or "false" (cannot be changed after creation)	No	false
tags	Bucket tags as JSON object	No	-

Outputs

Output	Description
bucket-name	Name of the created S3 bucket
bucket-arn	ARN of the created S3 bucket
created	Whether the bucket was newly created ("true") or already existed ("false")

S3 Bucket Naming Rules

S3 bucket names must follow these rules:

• Between 3 and 63 characters long
• Consist only of lowercase letters, numbers, dots (.), and hyphens (-)
• Begin and end with a letter or number
• Must not be formatted as an IP address (e.g., 192.168.1.1)
• Must not contain consecutive periods (..)
• Must not start with 'xn--' prefix
• Must not end with '-s3alias' suffix
• Must be globally unique across all AWS accounts

Encryption

AES256 (Default)

Amazon S3-managed encryption keys (SSE-S3). S3 automatically encrypts objects using 256-bit Advanced Encryption Standard.

AWS KMS

AWS Key Management Service (SSE-KMS). Provides additional control and audit trail. Requires kms-key-id parameter.

Object Lock

IMPORTANT: Object Lock can only be enabled at bucket creation time and cannot be disabled later. It requires versioning to be enabled. Use Object Lock for compliance and regulatory requirements to prevent object deletion for a fixed period or indefinitely.

Public Access Block

By default, all public access is blocked. This prevents:

• New public ACLs and public objects
• Public access granted through any ACLs
• New public bucket or access point policies
• Public and cross-account access through any policies

Set block-public-access: 'false' only if you need to host public content.

Common Use Cases

Data Lake Storage

- uses: predictr-io/aws-s3-create-bucket@v0
  with:
    bucket-name: 'company-data-lake'
    region: 'us-east-1'
    versioning: 'Enabled'
    encryption: 'aws:kms'
    kms-key-id: '${{ secrets.KMS_KEY_ID }}'
    tags: '{"Purpose": "DataLake", "Retention": "7years"}'

Static Website Hosting

- uses: predictr-io/aws-s3-create-bucket@v0
  with:
    bucket-name: 'my-website-bucket'
    block-public-access: 'false'
    tags: '{"Purpose": "StaticWebsite"}'

Backup Storage

- uses: predictr-io/aws-s3-create-bucket@v0
  with:
    bucket-name: 'company-backups'
    versioning: 'Enabled'
    object-lock-enabled: 'true'
    encryption: 'AES256'
    tags: '{"Purpose": "Backups", "Compliance": "Required"}'

Error Handling

The action will fail if:

• Bucket name is invalid or already exists (unless skip-if-exists is true)
• AWS credentials are not configured
• Required permissions are missing
• Region is invalid
• KMS key ID is required but not provided (when encryption is "aws:kms")

Required AWS Permissions

The IAM role or user must have these permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:CreateBucket",
        "s3:HeadBucket",
        "s3:PutBucketVersioning",
        "s3:PutEncryptionConfiguration",
        "s3:PutBucketPublicAccessBlock",
        "s3:PutBucketTagging"
      ],
      "Resource": "arn:aws:s3:::*"
    }
  ]
}

If using KMS encryption, also add:

{
  "Effect": "Allow",
  "Action": [
    "kms:Decrypt",
    "kms:GenerateDataKey"
  ],
  "Resource": "arn:aws:kms:*:*:key/*"
}

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Related Actions

• aws-s3-delete-bucket - Delete S3 buckets
• url-to-s3 - Download URL content directly to S3

Support

For issues, questions, or contributions, please visit the GitHub repository.