Skip to main content

LIST OBJECTS UNDER A PREFIX IN A CLOUD STORAGE BUCKET

This guide shows you how to list the objects stored under one prefix in a Cloud Storage bucket. The list keeps each object's metadata as Swamp data, so later workflow steps and queries can read it.

Prerequisites

  • A @swamp/gcp/storage/objects behavior bound to the bucket, with bucket and project set. This guide uses a behavior named build-logs for the bucket acme-build-logs in the project acme-prod. See Create and Run a Behavior.
  • Google Cloud credentials with permission to list objects in the bucket, from Application Default Credentials, the GOOGLE_APPLICATION_CREDENTIALS_JSON or GCP_ACCESS_TOKEN environment variable, or the behavior's accessToken or credentialsJson global argument wired to a vault

Pull the extension

If the repository does not have the Cloud Storage extension yet, pull it:

swamp extension pull @swamp/gcp/storage

The output looks like:

INF extension·pull: Pulling "@swamp/gcp/storage"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/gcp/storage"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/gcp/storage"@"2026.10.13.1"
INF extension·pull: Extracted 28 files:

List the objects

Run list with the prefix and a limit on the number of results:

swamp behavior run build-logs list \
  --input prefix=ci/2026-10/ \
  --input 'maxResults:json=100'

This lists up to 100 objects in acme-build-logs whose names start with ci/2026-10/ and writes the metadata of each object to Swamp as resource state.

maxResults is a number, so it uses the :json= suffix. A plain key=value input is always passed as a string.

Narrow or widen the listing

  • To select names by pattern instead of a fixed prefix, pass a glob pattern as matchGlob.
  • To get only the objects directly under the prefix and group deeper names into sub-prefixes, pass --input delimiter=/.
  • To list a range of names, pass startOffset and endOffset.
  • To include noncurrent generations in a versioned bucket, pass --input 'versions:json=true'.
  • To limit how many pages of results are fetched, pass maxPages as a number.

Read the results

The object metadata from the run is stored as Swamp data under the build-logs behavior. To filter it, select fields, or pass it to another step, see Query and Manage Data. For every input of the objects type's list method, see the Google Cloud Storage extensions reference.