Send bucket events when an object is finalized, deleted or archived, using Pub/Sub notifications or Eventarc, and process them in Cloud Run or in an Encore subscriber after the upload.

A Cloud Storage bucket can tell you when an object is created, overwritten, deleted or archived, which is how thumbnail pipelines, malware scans and "file is ready" APIs usually start.
The configuration around that event is easy to get slightly wrong: a bucket can have only 10 notification configurations for a given event, delivery is at least once and not ordered, and a failed upload does not emit OBJECT_FINALIZE.
This guide sets up Pub/Sub notifications for Cloud Storage and an Eventarc trigger to Cloud Run, then shows how an Encore API publishes after a confirmed upload when you want the event in application code instead of from the bucket.
Create a topic, grant Cloud Storage permission to publish to it, and attach a notification for OBJECT_FINALIZE, as described in the Pub/Sub notifications documentation:
OBJECT_FINALIZE is sent when a new object, or a new generation of an existing object, is successfully created, including copies and restores. A failed upload does not trigger it. Replacing an object sends OBJECT_FINALIZE for the new generation and either OBJECT_ARCHIVE or OBJECT_DELETE for the old one. Notifications may take up to 30 seconds to start after you add the configuration, and there is no SLA for delivery time.
A consumer must be idempotent, and the message attributes include bucketId, objectId and objectGeneration. If you will modify the object from the consumer, use those generation numbers as preconditions.
If you need more than 10 consumers, create one notification to one topic and add subscriptions, instead of one notification per consumer.
Best fit: fan-out from one bucket to several backends that already know how to pull or push from Pub/Sub.
Eventarc uses Pub/Sub notifications underneath and delivers CloudEvents to a Cloud Run service. The event type google.cloud.storage.object.v1.finalized corresponds to a successful object creation or overwrite. Other types cover delete, archive and metadata updates.
The trigger and the Cloud Run service must be in the same project. The Eventarc service account needs permission to invoke the service and to receive the events. Retries are on by default; you can turn them off for a single delivery attempt. After a trigger is created, its event source filters cannot be changed: create a new trigger instead.
This still counts against the bucket's notification configuration limit, so prefer one notification and one topic when many services need the same event.
Best fit: a single Cloud Run worker that should receive bucket events as HTTP CloudEvents.
Encore brings infrastructure from code: you declare a bucket and a topic in Go, and a deploy provisions Cloud Storage and Pub/Sub in your GCP account. Encore does not attach bucket notifications or Eventarc triggers. When the upload is started by your API, a practical path is to publish after the client has uploaded to a signed URL and you have confirmed the object with Attrs.
A coding agent can add the bucket, the confirm handler and the subscriber in the same change, then use encore run to upload a file and watch the subscriber run on the laptop.
// uploads/uploads.go
package uploads
import (
"context"
"errors"
"time"
"encore.dev/pubsub"
"encore.dev/storage/objects"
"encore.dev/storage/sqldb"
)
var files = objects.NewBucket("uploads", objects.BucketConfig{})
var db = sqldb.NewDatabase("uploads", sqldb.DatabaseConfig{Migrations: "./migrations"})
type ObjectReady struct {
Key string `json:"key"`
Size int64 `json:"size"`
Version string `json:"version"`
}
var Ready = pubsub.NewTopic[*ObjectReady]("object-ready", pubsub.TopicConfig{
DeliveryGuarantee: pubsub.AtLeastOnce,
})
// object_outbox keeps a durable pending/published marker per object version:
// CREATE TABLE object_outbox (
// object_key TEXT NOT NULL,
// version TEXT NOT NULL,
// size BIGINT NOT NULL,
// status TEXT NOT NULL DEFAULT 'pending'
// CHECK (status IN ('pending', 'published')),
// PRIMARY KEY (object_key, version)
// );
// Call after the client PUTs to a signed URL and Attrs has passed the size check.
// version must be the provider generation (Attrs.Version on GCS) or another upload-specific id; never use ETag, which can repeat for identical-content replacements.
func confirmAndPublish(ctx context.Context, key, version string, size int64) error {
_, err := db.Exec(ctx, `
INSERT INTO object_outbox (object_key, version, size, status)
VALUES ($1, $2, $3, 'pending')
ON CONFLICT (object_key, version) DO NOTHING`, key, version, size)
if err != nil {
return err
}
return flushObjectOutbox(ctx, key, version)
}
func flushObjectOutbox(ctx context.Context, key, version string) error {
var size int64
err := db.QueryRow(ctx, `
SELECT size FROM object_outbox
WHERE object_key = $1 AND version = $2 AND status = 'pending'`, key, version).Scan(&size)
if errors.Is(err, sqldb.ErrNoRows) {
return nil // already published, or nothing to do
} else if err != nil {
return err
}
if _, err := Ready.Publish(ctx, &ObjectReady{Key: key, Size: size, Version: version}); err != nil {
return err
}
_, err = db.Exec(ctx, `
UPDATE object_outbox SET status = 'published'
WHERE object_key = $1 AND version = $2 AND status = 'pending'`, key, version)
return err
}
var _ = pubsub.NewSubscription(Ready, "scan-upload",
pubsub.SubscriptionConfig[*ObjectReady]{
Handler: func(ctx context.Context, ev *ObjectReady) error {
// Idempotent work: delivery is at least once, so key on object_key and version.
return nil
},
RetryPolicy: &pubsub.RetryPolicy{MaxRetries: 8, MinBackoff: 10 * time.Second, MaxBackoff: 5 * time.Minute},
},
)
encore run stores objects on disk and delivers the topic locally. On deploy, Encore provisions the bucket and the topic in your account, and Encore provisions an IAM role for the service, or a service account on GCP.
Best fit: APIs that already issue signed upload URLs and want the follow-up work declared next to the confirm handler.
Pick Pub/Sub notifications when several existing consumers should see every finalized object. Pick Eventarc when a Cloud Run service should receive those events as CloudEvents. Pick Encore when the upload already goes through your API and you want the follow-up work declared in the same repository, with local delivery under encore run.
In every case the consumer must be idempotent, because delivery is at least once.
Create a Pub/Sub notification on the bucket for OBJECT_FINALIZE, or an Eventarc trigger of type google.cloud.storage.object.v1.finalized that delivers to Cloud Run or another destination. Both are at-least-once, so the consumer must be idempotent, and a bucket can have at most 10 notification configurations for a given event.
No. Encore provisions the bucket in your GCP account, but it does not attach Pub/Sub notifications or Eventarc triggers. Have the API publish to a Pub/Sub topic after a signed upload is confirmed, and process that topic with a subscription that is safe to run twice.
Pub/Sub notifications are a bucket configuration that publish OBJECT_FINALIZE, OBJECT_DELETE, OBJECT_ARCHIVE and OBJECT_METADATA_UPDATE messages to a topic you choose. Eventarc sits on top of those notifications and delivers CloudEvents to Cloud Run, Workflows or other destinations with retry settings you configure on the trigger.
No. Cloud Storage guarantees at-least-once delivery to Pub/Sub, Pub/Sub also delivers at least once, and messages are not guaranteed to arrive in the order they were published. Use the object generation as a precondition if you will update the object from the consumer.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.