GCS Delete Bucket

A GitHub Action to delete GCS (Google Cloud Storage) buckets. ⚠️ DESTRUCTIVE ACTION - Use with caution in production environments.

Features

• Delete buckets - Delete GCS buckets
• 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 deleted
• Simple integration - Easy to use in GitHub Actions workflows

Prerequisites

Configure GCP credentials before using this action.

Option 1: Workload Identity Federation (Production)

Use google-github-actions/auth@v2 with Workload Identity Federation (recommended):

- name: Authenticate to Google Cloud
  uses: google-github-actions/auth@v2
  with:
    workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider
    service_account: my-service-account@my-project.iam.gserviceaccount.com

Option 2: GCS Emulator (Testing)

Use the GCS emulator for local testing:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Start GCS emulator
        run: |
          docker run -d -p 9023:9023 fsouza/fake-gcs-server -scheme http

      - name: Delete bucket in emulator
        uses: predictr-io/gcs-delete-bucket@v0
        env:
          STORAGE_EMULATOR_HOST: http://localhost:9023
        with:
          bucket-name: test-bucket
          force-delete: true

Usage

Delete Empty Bucket

Delete a GCS bucket (fails if bucket is not empty):

- name: Delete GCS bucket
  uses: predictr-io/gcs-delete-bucket@v0
  with:
    bucket-name: my-bucket

Force Delete Bucket

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

- name: Force delete GCS bucket
  uses: predictr-io/gcs-delete-bucket@v0
  with:
    bucket-name: my-bucket
    force-delete: true

Delete with Output

Use the output to check if bucket was deleted:

- name: Delete bucket
  id: delete-bucket
  uses: predictr-io/gcs-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	GCS bucket name to delete	Yes	-
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 (for versioned buckets)
3. Deletes in batches - Deletes objects in batches with concurrency control
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)
• 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/gcs-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/gcs-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
• 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/gcs-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/gcs-create-bucket@v0
  with:
    bucket-name: temp-${{ github.run_id }}

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

- name: Delete temporary bucket
  if: always()
  uses: predictr-io/gcs-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/gcs-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: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.SERVICE_ACCOUNT }}

      - name: Delete bucket
        uses: predictr-io/gcs-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
• GCP credentials are not configured
• Required permissions are missing
• Bucket is not empty and force-delete is not enabled
• Network errors or GCP service issues occur

Performance Considerations

Large Buckets

For buckets with millions of objects:

• Deletion happens in batches of 1000 objects
• Multiple objects are deleted in parallel (50 at a time)
• 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 deleted.

Required GCP Permissions

The service account must have these permissions:

{
  "roles": [
    "roles/storage.admin"
  ]
}

Or these specific permissions:

• storage.buckets.delete
• storage.buckets.get
• storage.objects.list
• storage.objects.delete

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. Label your buckets: Label 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 lifecycle policies for automatic cleanup instead

License

MIT

Contributing

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

Related Actions

• gcs-create-bucket - Create GCS buckets
• url-to-gcs - Download URL content directly to GCS

Support

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