GCS Create Bucket

A GitHub Action to create GCS (Google Cloud Storage) buckets. Seamlessly integrate bucket creation into your CI/CD workflows with support for versioning, storage classes, and access control.

Features

• Create buckets - Create GCS buckets in any location (region or multi-region)
• Skip if exists - Optionally succeed without error if bucket already exists
• Storage classes - Support for STANDARD, NEARLINE, COLDLINE, and ARCHIVE
• Versioning - Enable or disable bucket versioning
• Uniform bucket-level access - Modern IAM-only access control
• Public access prevention - Enforce or inherit public access settings
• Labels - Support for bucket labeling
• 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: Create bucket in emulator
        uses: predictr-io/gcs-create-bucket@v0
        env:
          STORAGE_EMULATOR_HOST: http://localhost:9023
        with:
          bucket-name: test-bucket

Usage

Create Basic Bucket

Create a basic GCS bucket with default settings:

- name: Create GCS bucket
  uses: predictr-io/gcs-create-bucket@v0
  with:
    bucket-name: my-unique-bucket-name

Create Bucket in Specific Location

Create a bucket in a specific region or multi-region:

# Single region
- name: Create bucket in us-central1
  uses: predictr-io/gcs-create-bucket@v0
  with:
    bucket-name: my-bucket-us
    location: us-central1

# Multi-region
- name: Create bucket in EU
  uses: predictr-io/gcs-create-bucket@v0
  with:
    bucket-name: my-bucket-eu
    location: EU

Create Bucket with Skip-If-Exists

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

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

Create Bucket with Different Storage Class

Create a bucket with NEARLINE, COLDLINE, or ARCHIVE storage class:

- name: Create archive bucket
  uses: predictr-io/gcs-create-bucket@v0
  with:
    bucket-name: my-archive-bucket
    storage-class: ARCHIVE

Create Bucket with Versioning

Create a bucket with versioning enabled:

- name: Create versioned bucket
  uses: predictr-io/gcs-create-bucket@v0
  with:
    bucket-name: my-versioned-bucket
    versioning: true

Create Bucket with Fine-Grained Access Control

Create a bucket without uniform bucket-level access (allows ACLs):

- name: Create bucket with ACLs
  uses: predictr-io/gcs-create-bucket@v0
  with:
    bucket-name: my-acl-bucket
    uniform-bucket-level-access: false

Create Bucket with Public Access

Create a bucket that inherits public access settings (not enforced):

- name: Create public bucket
  uses: predictr-io/gcs-create-bucket@v0
  with:
    bucket-name: my-public-bucket
    public-access-prevention: inherited

Create Bucket with Labels

Create a bucket with labels:

- name: Create labeled bucket
  uses: predictr-io/gcs-create-bucket@v0
  with:
    bucket-name: my-labeled-bucket
    labels: |
      {
        "environment": "production",
        "team": "backend",
        "project": "my-app"
      }

Create Fully Configured Bucket

Create a bucket with all options:

- name: Create fully configured bucket
  uses: predictr-io/gcs-create-bucket@v0
  with:
    bucket-name: my-production-bucket
    location: us-central1
    storage-class: STANDARD
    versioning: true
    uniform-bucket-level-access: true
    public-access-prevention: enforced
    skip-if-exists: true
    labels: |
      {
        "environment": "production",
        "managed_by": "github-actions"
      }

Use Outputs

Use the bucket name and URL in subsequent steps:

- name: Create bucket
  id: create-bucket
  uses: predictr-io/gcs-create-bucket@v0
  with:
    bucket-name: my-bucket

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

Inputs

Input	Description	Required	Default
bucket-name	GCS bucket name (must be globally unique and DNS-compliant)	Yes	-
location	Bucket location: region (e.g., "us-central1") or multi-region (e.g., "US", "EU")	No	US
skip-if-exists	If "true", succeed without error if bucket already exists	No	false
storage-class	Storage class: "STANDARD", "NEARLINE", "COLDLINE", or "ARCHIVE"	No	STANDARD
versioning	Enable versioning: "true" or "false"	No	false
uniform-bucket-level-access	Enable uniform bucket-level access: "true" or "false"	No	true
public-access-prevention	Public access prevention: "enforced" or "inherited"	No	enforced
labels	Bucket labels as JSON object	No	-

Outputs

Output	Description
bucket-name	Name of the created GCS bucket
bucket-url	URL of the created GCS bucket (gs://bucket-name)
created	Whether the bucket was newly created ("true") or already existed ("false")

GCS Bucket Naming Rules

GCS bucket names must follow these rules:

• Between 3 and 63 characters long (or up to 222 for domain-named buckets)
• Consist only of lowercase letters, numbers, hyphens, underscores, and dots
• Begin and end with a lowercase letter or number
• Must not be formatted as an IP address (e.g., 192.168.1.1)
• Must not contain the word 'google' or close misspellings
• Must not start with 'goog' prefix
• Must be globally unique across all Google Cloud

Storage Classes

STANDARD

Best for frequently accessed data ("hot" data). No minimum storage duration.

NEARLINE

Best for data accessed less than once a month. 30-day minimum storage duration.

COLDLINE

Best for data accessed less than once a quarter. 90-day minimum storage duration.

ARCHIVE

Best for data accessed less than once a year. 365-day minimum storage duration.

Locations

GCS supports both regional and multi-regional locations:

Multi-Region

• US - Data centers in the United States
• EU - Data centers in the European Union
• ASIA - Data centers in Asia

Regional Examples

• us-central1 - Iowa
• us-east1 - South Carolina
• europe-west1 - Belgium
• asia-northeast1 - Tokyo

See GCS locations for the full list.

Uniform Bucket-Level Access

When enabled (default), uniform bucket-level access disables ACLs and uses only IAM for access control. This is the recommended modern approach for managing access to GCS buckets.

Set to false only if you need fine-grained, object-level ACLs.

Public Access Prevention

enforced (default)

Prevents public access to bucket data, even if IAM policies or ACLs would grant it.

inherited

Inherits the organization's public access prevention policy. Use this if you need to host public content.

Labels

GCS labels are key-value pairs for organizing resources. Labels are automatically normalized:

• Keys are converted to lowercase
• Invalid characters are replaced with hyphens
• Maximum 64 labels per bucket

Common Use Cases

Data Lake Storage

- uses: predictr-io/gcs-create-bucket@v0
  with:
    bucket-name: company-data-lake
    location: US
    storage-class: STANDARD
    versioning: true
    labels: '{"purpose": "datalake", "retention": "7years"}'

Archive Storage

- uses: predictr-io/gcs-create-bucket@v0
  with:
    bucket-name: company-archives
    location: us-central1
    storage-class: ARCHIVE
    versioning: true
    labels: '{"purpose": "archive"}'

Static Website Hosting

- uses: predictr-io/gcs-create-bucket@v0
  with:
    bucket-name: my-website-bucket
    location: US
    public-access-prevention: inherited
    uniform-bucket-level-access: false
    labels: '{"purpose": "website"}'

Error Handling

The action will fail if:

• Bucket name is invalid or already exists (unless skip-if-exists is true)
• GCP credentials are not configured
• Required permissions are missing
• Location is invalid
• Storage class is invalid

Required GCP Permissions

The service account must have these permissions:

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

Or these specific permissions:

• storage.buckets.create
• storage.buckets.get
• storage.buckets.update

License

MIT

Contributing

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

Related Actions

• gcs-delete-bucket - Delete GCS buckets
• url-to-gcs - Download URL content directly to GCS

Support

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