Skip to main content

BOOTSTRAP A CLOUD STORAGE DATASTORE FOR A REPOSITORY

This guide shows you how to move a Swamp repository's datastore to a new private Cloud Storage bucket. The bootstrap also creates a project-scoped custom IAM role that grants only the permissions the datastore uses.

Prerequisites

  • Application Default Credentials for a principal that has roles/storage.admin and roles/iam.roleAdmin, or equivalent permissions, on the target project
  • The Cloud Storage API and the IAM API enabled on the target project
  • A principal for running Swamp after setup that already has the custom role, or that you will bind to it
  • A behavior named swamp-gcs-datastore-provisioner of type @swamp/gcs-datastore-bootstrap/provisioner, created with its required bucket_name, project_id and location global arguments
  • A command/shell behavior named swamp-gcs-datastore-setup, which the workflow's final step uses

See Create and Run a Behavior to create the two behaviors.

Pull the extension

Pull the bootstrap extension. It contains the provisioner behavior type and the bootstrap workflow:

swamp extension pull @swamp/gcs-datastore-bootstrap

The output looks like:

INF extension·pull: Pulling "@swamp/gcs-datastore-bootstrap"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/gcs-datastore-bootstrap"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/gcs-datastore-bootstrap"@"2026.10.13.1"
INF extension·pull: Extracted 7 files:
INF extension·pull: Pulling dependency "@swamp/gcs-datastore"@"2026.10.13.1"
INF extension·pull: Pulling "@swamp/gcs-datastore"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/gcs-datastore"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/gcs-datastore"@"2026.10.13.1"
INF extension·pull: Extracted 12 files:

Wire the provisioner to the workflow inputs

Open the provisioner definition with swamp behavior edit swamp-gcs-datastore-provisioner and set its global arguments to the workflow inputs:

globalArguments:
  bucket_name: "${{ inputs.bucket_name }}"
  project_id: "${{ inputs.project_id }}"
  location: "${{ inputs.location }}"
  prefix: "${{ inputs.prefix }}"
  role_id: "${{ inputs.role_id }}"

Decide on the location before you run the workflow. It is set when the bucket is created and cannot be changed by patching the bucket later. It accepts a multi-region such as US, a region such as us-central1, or a dual-region such as NAM4.

Run the workflow

swamp workflow run @swamp/bootstrap-gcs-datastore \
  --input bucket_name=acme-swamp-state \
  --input project_id=acme-prod \
  --input location=US

The workflow runs provision to create or verify a private bucket with uniform bucket-level access, enforced public access prevention and versioning, together with a custom role that grants storage.buckets.get, storage.objects.get, storage.objects.create, storage.objects.delete and storage.objects.list, and then its final step switches the repository's datastore to @swamp/gcs-datastore.

If you want the repository's objects under a prefix inside the bucket, add --input prefix=swamp. If you want a different role ID, add --input role_id=<id>. Without it, the role is named swampGcsDatastore_ followed by the bucket name with hyphens replaced by underscores, for example swampGcsDatastore_acme_swamp_state.

Bind the role and confirm

Bind the custom role to every principal that will run Swamp against this repository, such as developers, CI runners and swamp serve instances. Each of them needs Application Default Credentials for that principal in its environment.

Run swamp datastore status to check that the repository now uses the Cloud Storage datastore. The bucket, prefix, concurrency and timeout settings it accepts are described in Datastore Configuration. If several repositories will share this bucket, see Set Up a Giga-Swamp.