Goal: Pub/Sub events trigger Cloud Run without running a subscriber loop in the container.
Setup:
1. Create the push subscription with the Cloud Run URL as endpoint and an OIDC token -
```
gcloud pubsub subscriptions create [SUB] --topic [TOPIC] --push-endpoint [RUN-URL] --push-auth-service-account [PUBSUB-SA] --push-auth-token-audience [RUN-URL]
```
2. Grant the Pub/Sub SA run.invoker on the Cloud Run service.
3. The service validates the OIDC token (audience = the URL) and processes the message.
Message format: by default messages arrive WRAPPED: JSON with message.data (base64), message.attributes, message.messageId. Your handler must unwrap. You can opt into unwrapped delivery for raw payloads; know which one you configured.
Handler rules:
- Return 2xx quickly on success. Anything else (including timeouts) triggers redelivery.
- Ack is implicit in the 2xx. There is no separate ack call in push.
- Make the handler idempotent: at-least-once delivery means duplicates happen.
- Long processing: return 2xx and continue async, or use a pull subscriber instead. Push has delivery deadlines; slow handlers redeliver.
Traps:
- Forgetting the invoker grant gives 403s on every push. The subscription looks healthy while nothing is processed.
- Deploying a new revision changes nothing about the URL, but changing the service URL requires updating the push endpoint.
- Push endpoint must be public HTTPS. For private services, keep auth on and use the OIDC path; do not open the service to the world.
Verify: publish a test message, confirm one 2xx in the service logs and the expected side effect exactly once.