AWS S3 Delete Bucket

A GitHub Action to delete AWS S3 buckets. ⚠️ DESTRUCTIVE ACTION - Use with caution in production environments.

Features

• Delete buckets - Delete S3 buckets in any AWS region
• Force delete - Optionally delete all objects and versions before deleting bucket
• Safe by default - Fails if bucket is not empty (unless force-delete is enabled)
• Comprehensive logging - Detailed information about objects and versions deleted
• 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: Delete bucket in LocalStack
        uses: predictr-io/aws-s3-delete-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'
          force-delete: 'true'

Usage

Delete Empty Bucket

Delete an S3 bucket (fails if bucket is not empty):

- name: Delete S3 bucket
  uses: predictr-io/aws-s3-delete-bucket@v0
  with:
    bucket-name: 'my-bucket'

Force Delete Bucket

Delete a bucket and all its contents (objects and versions):

- name: Force delete S3 bucket
  uses: predictr-io/aws-s3-delete-bucket@v0
  with:
    bucket-name: 'my-bucket'
    force-delete: 'true'

Delete Bucket in Specific Region

Delete a bucket in a specific AWS region:

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

Delete with Output

Use the output to check if bucket was deleted:

- name: Delete bucket
  id: delete-bucket
  uses: predictr-io/aws-s3-delete-bucket@v0
  with:
    bucket-name: 'my-bucket'
    force-delete: 'true'

- name: Check deletion status
  run: |
    echo "Bucket deleted: ${{ steps.delete-bucket.outputs.deleted }}"

Inputs

Input	Description	Required	Default
bucket-name	S3 bucket name to delete	Yes	-
region	AWS region for the bucket	No	us-east-1
force-delete	If "true", delete all objects and versions before deleting bucket	No	false

Outputs

Output	Description
deleted	Whether the bucket was successfully deleted ("true" or "false")

Force Delete Behavior

When force-delete: 'true' is set:

1. Lists all objects - Retrieves all objects in the bucket (up to 1000 at a time)
2. Lists all versions - Retrieves all object versions and delete markers (for versioned buckets)
3. Deletes in batches - Deletes objects in batches of 1000
4. Deletes the bucket - After all objects are removed, deletes the bucket itself

⚠️ WARNING: Force delete is irreversible and will permanently delete:

• All objects in the bucket
• All object versions (if versioning is enabled)
• All delete markers
• The bucket itself

Safety Features

Safe by Default

By default, the action will fail if the bucket is not empty. This prevents accidental data loss.

# This will FAIL if bucket has any objects
- uses: predictr-io/aws-s3-delete-bucket@v0
  with:
    bucket-name: 'my-bucket'

Explicit Force Delete

You must explicitly set force-delete: 'true' to delete non-empty buckets:

# This will delete all objects and the bucket
- uses: predictr-io/aws-s3-delete-bucket@v0
  with:
    bucket-name: 'my-bucket'
    force-delete: 'true'

Detailed Logging

The action provides detailed information about what's being deleted:

• Number of objects deleted
• Number of versions deleted
• Any errors encountered during deletion

Common Use Cases

Cleanup Test Environments

Delete test buckets after CI/CD runs:

- name: Run tests
  run: npm test

- name: Cleanup test bucket
  if: always()
  uses: predictr-io/aws-s3-delete-bucket@v0
  with:
    bucket-name: 'test-bucket-${{ github.run_id }}'
    force-delete: 'true'

Ephemeral Buckets

Create and delete buckets for temporary storage:

- name: Create temporary bucket
  uses: predictr-io/aws-s3-create-bucket@v0
  with:
    bucket-name: 'temp-${{ github.run_id }}'

- name: Use bucket
  run: |
    # Upload and process data
    aws s3 cp data.txt s3://temp-${{ github.run_id }}/

- name: Delete temporary bucket
  if: always()
  uses: predictr-io/aws-s3-delete-bucket@v0
  with:
    bucket-name: 'temp-${{ github.run_id }}'
    force-delete: 'true'

Conditional Cleanup

Only delete if certain conditions are met:

- name: Delete bucket on failure
  if: failure()
  uses: predictr-io/aws-s3-delete-bucket@v0
  with:
    bucket-name: 'my-bucket'
    force-delete: 'true'

Manual Cleanup Workflow

Create a manual workflow to clean up old buckets:

name: Cleanup Old Buckets

on:
  workflow_dispatch:
    inputs:
      bucket-name:
        description: 'Bucket name to delete'
        required: true
      force:
        description: 'Force delete (true/false)'
        required: true
        default: 'false'

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE }}
          aws-region: us-east-1

      - name: Delete bucket
        uses: predictr-io/aws-s3-delete-bucket@v0
        with:
          bucket-name: ${{ github.event.inputs.bucket-name }}
          force-delete: ${{ github.event.inputs.force }}

Error Handling

The action will fail if:

• Bucket name is empty or invalid
• AWS credentials are not configured
• Required permissions are missing
• Bucket is not empty and force-delete is not enabled
• Network errors or AWS service issues occur

Performance Considerations

Large Buckets

For buckets with millions of objects:

• Deletion happens in batches of 1000 objects
• Progress is logged for each batch
• GitHub Actions has a maximum run time of 6 hours

Versioned Buckets

Buckets with versioning enabled may take longer to delete because:

• All versions of each object must be listed and deleted
• Delete markers must also be removed

Required AWS Permissions

The IAM role or user must have these permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:DeleteBucket",
        "s3:ListBucket",
        "s3:ListBucketVersions",
        "s3:DeleteObject",
        "s3:DeleteObjectVersion"
      ],
      "Resource": [
        "arn:aws:s3:::*",
        "arn:aws:s3:::*/*"
      ]
    }
  ]
}

Note: For production use, restrict the Resource to specific bucket ARNs.

Best Practices

1. Use in test environments: Primarily use force-delete in test/CI environments
2. Verify bucket name: Double-check bucket names before deleting
3. Use conditionals: Use if: always() or if: failure() for cleanup steps
4. Tag your buckets: Tag buckets with environment info to prevent accidental deletion
5. Backup important data: Always backup important data before deletion
6. Use IAM restrictions: Restrict deletion permissions to specific buckets in production

Dangerous Operations Warning

⚠️ THIS ACTION PERMANENTLY DELETES DATA

• Deleted objects cannot be recovered (unless versioning/backup is enabled)
• Use force-delete: 'true' with extreme caution
• Test thoroughly in non-production environments first
• Consider using S3 lifecycle policies for automatic cleanup instead

License

MIT

Contributing

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

Related Actions

• aws-s3-create-bucket - Create S3 buckets
• url-to-s3 - Download URL content directly to S3

Support

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