Skip to main content

Bucket Setup

Binary upload stores files in your own cloud storage bucket. For each request, Workshop mints a short-lived presigned URL, and the host uploads straight to the bucket. Workshop never holds the file.

Two providers are supported: Amazon S3 (s3://) and Google Cloud Storage (gs://).

Create a bucket​

Create a private bucket with no public access.

Uploaded files are stored at the root of the bucket, keyed by their SHA-256. The Test Bucket check writes objects under a __workshop_test__/ prefix so they are easy to find and remove. A lifecycle rule that expires __workshop_test__/ objects is a good safety net in case a cleanup ever fails.

Grant Workshop access​

Workshop uses its own cloud credentials, the task role on AWS and the workload service account on Google Cloud. Grant that identity access to the bucket.

On S3:

  • s3:PutObject to store uploads. The presigned URL passes this permission to the host.
  • s3:DeleteObject to remove the Test Bucket object after a check.
  • s3:ListBucket to detect the bucket's region.

On Google Cloud Storage:

  • storage.objects.create to store uploads.
  • storage.objects.delete to remove the Test Bucket object after a check.
  • The Service Account Token Creator role on the service account itself. Workshop signs the upload URL with the IAM signBlob API, which needs this role.

Read access is not required. A write-only role is enough.

Connect the bucket​

Open Settings, find the binary upload section, and enter your bucket URL as s3://your-bucket or gs://your-bucket. Workshop validates the scheme and bucket name. Clear the field to turn binary upload off.

Test the bucket​

Use Test Bucket to confirm the setup with an upload and cleanup round-trip. Run it in presigned mode, which exercises the same path real uploads use.

The check reports the stage that failed:

  • presign: Workshop could not sign an upload URL. Check credentials, and on Google Cloud the Service Account Token Creator role.
  • upload: the bucket rejected the write. Check the bucket policy and the PutObject permission.
  • cleanup: the upload worked but the test object could not be deleted. This is a soft warning. Delete the leftover __workshop_test__/ object by hand.

Bucket policy notes​

Each presigned URL is bound to one exact object key, the file's SHA-256. The host can write that single object and nothing else.

Do not require a content type on uploads. Santa does not send one, and a policy that requires a content type will reject every upload.

Each URL is valid for a few minutes, so an upload must finish within that window. No CORS configuration is needed, because the upload runs server to server rather than from a browser.

See Also​