15.1 Source Deployment, Event Receivers, and API Versions

Source Deployment, Event Receivers, and API Versions

A developer can deploy an application without manually building a container first, but source deployment does not eliminate the build, registry, identity or runtime boundaries. The blueprint expects a working application deployment, not merely a command that uploads code. Verify the complete path from source to an invokable service and from an incoming event to a durable application result.

From Source to a Revision

With Cloud Run source deployment, Google Cloud builds source into a container using the supported build process and stores the image in Artifact Registry before deploying it. A repository Dockerfile can control the build; otherwise supported buildpacks can detect the runtime. This is not a process that runs arbitrary source files directly on the service frontend. Review the actual build logs and resulting image when dependencies or startup fail.

## Example for a prepared test project and supported source directory.
gcloud run deploy order-api \
    --source=. \
    --region=us-central1 \
    --service-account=order-runtime@my-project.iam.gserviceaccount.com \
    --no-allow-unauthenticated

The deployer, build service account, service agent and runtime identity have different duties. Current source-deployment guidance uses Cloud Run Source Developer for the deployer, the appropriate permission to use the runtime service account, and Cloud Run Builder for the configured build account, along with required service-usage access. Do not give runtime code deployment or signing authority simply because the builder needs it. Check project policy and current default build-account selection rather than assuming the legacy Cloud Build account is always used.

A failed dependency download belongs to the build stage. A container that never binds to the configured port belongs to startup. A successfully running service that returns 403 to a caller belongs to invocation authentication/authorization or ingress, not necessarily the compiler. Inspect these stages separately. Keep application configuration and secrets outside the image and verify that the built artifact is the one actually deployed.

Configure Delivery and the Receiver Together

Eventarc can invoke a Cloud Run receiver for supported events using CloudEvents. A direct Cloud Storage finalized trigger selects the event type and bucket, uses a trigger identity authorized to invoke the service, and must meet the source/trigger/destination location rules. Verify the relevant service-agent permissions and event-provider configuration as well as the receiver's own runtime IAM. A receiver's permission to read an object does not authorize Eventarc to invoke the service.

A Pub/Sub push subscription can instead send an authenticated HTTPS request directly. Its default envelope contains message data encoded as base64 plus attributes and delivery metadata; an explicitly configured unwrapped payload has a different shape. A CloudEvent receiver should not blindly parse every Pub/Sub POST as if its raw HTTP body were the original business JSON. Select a framework/parser matching the actual transport and write a contract test with an authentic representative event shape.

When using OIDC invocation, set an audience appropriate for the Cloud Run service and grant Invoker to the delivery identity. Validate business payload fields in the application. IAM verification authenticates the caller; it does not prove an object name, tenant ID or payment amount is semantically valid. If the service uses internal ingress, verify that the delivery path qualifies under Cloud Run's documented project/perimeter and URL rules.

Durable Processing and Failure Handling

Events can be delivered more than once. Use a stable business event ID and commit the business effect plus processed receipt atomically when they share a database. Acknowledge only after that commit or after a durable handoff to the next queue. Returning success before an in-memory background task completes can lose work if the container is terminated. Returning an error after an external payment succeeded can cause duplicate payment unless the external API uses an idempotency key.

Separate transient failures from invalid messages. A temporary database outage may need retry with bounded backoff and monitoring. A permanently malformed payload needs a deliberate dead-letter/quarantine path rather than an infinite crash loop. Retain enough context to repair/replay failed events without logging secret payloads. Monitor age and retries, not only whether the service process is alive.

Cloud Scheduler is for recurring cron-like triggers. It can invoke a supported HTTP target or publish a Pub/Sub message; it is different from a one-off per-customer Cloud Tasks schedule. Select the time zone deliberately, and account for daylight-saving changes if wall-clock scheduling is required. Recurring dispatch is not exactly-once execution: make the job idempotent and use an explicit business period/key so a retry cannot repeat a monthly charge. An OIDC-protected HTTP target still needs an authorized scheduler identity and the appropriate audience. Scheduling success is not proof that downstream business processing finished.

API Versioning Is a Public Contract

An immutable Cloud Run revision identifies deployed configuration/code, while an API version identifies a consumer contract. A new revision can implement the same /v1/orders API with a bug fix. A breaking field or behavior change might require /v2/orders or another explicit versioning strategy. Route versions through API Gateway, Apigee or the application as appropriate; versioning is not achieved by renaming a container tag alone.

Keep authentication and authorization requirements consistent across versions unless an intentional reviewed change requires otherwise. For an API Gateway config, deploy a new immutable config and update the gateway deliberately. For Apigee, distinguish proxy revisions/deployment environments from the externally exposed API version and product access rules. Continue to validate the backend's business input; a gateway definition does not automatically enforce every payload constraint.

Before shifting production traffic, test old and new clients, schema compatibility, event receiver formats and downstream effects. Use a tagged candidate revision for authorized tests and then a measured canary where suitable. An A/B experiment needs a defined cohort and business measurement; random routing weights alone do not guarantee the same user stays in the same cohort. Roll back traffic if the candidate is unhealthy, while accounting for any persisted data changes that routing cannot undo.

Sources checked October 18, 2026: Cloud Run source deployment, deployment IAM, Eventarc documentation, Cloud Scheduler documentation.

Deployment Verification Checklist