Google Cloud Functions skill for Codex

Done well means: the handler runs locally with the Functions Framework before it is deployed, event handlers are idempotent and decide explicitly which errors retry, the function and its trigger each use a dedicated service account, and secrets come from Secret Manager.

2nd gen functions are Cloud Run services built from source by Cloud Build; Google renamed the product “Cloud Run functions” in 2024. gcloud functions deploy --gen2 still works and is used below. Everything in gcp-cloud-run about scaling and IAM applies underneath.

Before writing code

1. Read AGENTS.md, the existing package.json / requirements.txt / go.mod, and any deploy script or Terraform. Match the runtime version already in use.
2. Check what is deployed (needs network and gcloud auth):

gcloud functions list --regions="$REGION"
gcloud functions describe thumbnail --region="$REGION" --format=yaml
gcloud functions runtimes list --region="$REGION"     # valid --runtime values

Pick the trigger

Source	Deploy flags	Handler type
HTTPS call, webhook	--trigger-http	HTTP
Pub/Sub topic	--trigger-topic=orders	CloudEvent
Object finalized in a bucket	--trigger-event-filters=type=google.cloud.storage.object.v1.finalized --trigger-event-filters=bucket=uploads	CloudEvent
Firestore document write	--trigger-event-filters=type=google.cloud.firestore.document.v1.written --trigger-event-filters=database=(default) --trigger-event-filters-path-pattern=document='users/{id}'	CloudEvent
Audit-logged API call	--trigger-event-filters=type=google.cloud.audit.log.v1.written plus serviceName and methodName filters	CloudEvent
Schedule	HTTP function + Cloud Scheduler job with an OIDC token	HTTP

If the work runs longer than about 9 minutes, needs a custom container, or bundles several routes, deploy a Cloud Run service instead.

Handlers

Node.js (npm i @google-cloud/functions-framework):

import functions from "@google-cloud/functions-framework";

functions.http("api", async (req, res) => {
  if (req.method !== "POST") return res.status(405).send("method not allowed");
  res.json({ ok: true });
});

functions.cloudEvent("onUpload", async (event) => {
  const { bucket, name, generation } = event.data;      // storage object payload
  const key = `${bucket}/${name}#${generation}`;        // idempotency key
  if (await alreadyProcessed(key)) return;              // duplicate delivery: ack
  await makeThumbnail(bucket, name);
  await markProcessed(key);
});

Python (functions-framework in requirements.txt):

import base64, json
import functions_framework

@functions_framework.cloud_event
def on_order(cloud_event):
    msg = cloud_event.data["message"]
    order = json.loads(base64.b64decode(msg["data"]))
    if not order.get("id"):
        print(json.dumps({"severity": "WARNING", "message": "dropping order without id"}))
        return  # permanent error: return normally so it is NOT retried
    process(order)  # raise on transient errors to trigger a retry

Initialise clients (DB pools, SDK clients) at module scope so warm instances reuse them; never keep per-request state there.

Run locally

npx @google-cloud/functions-framework --target=api --port=8080
functions-framework --target=on_order --signature-type=cloudevent --debug   # Python

curl -X POST localhost:8080 -H 'Content-Type: application/json' \
  -H 'ce-id: 1' -H 'ce-specversion: 1.0' -H 'ce-source: //pubsub' \
  -H 'ce-type: google.cloud.pubsub.topic.v1.messagePublished' \
  -d '{"message":{"data":"eyJpZCI6IjQyIn0="}}'

Unit-test the business function separately from the framework wrapper; it is faster and needs no emulator.

Deploy

gcloud functions deploy on-upload --gen2 --region="$REGION" \
  --runtime=nodejs22 --source=. --entry-point=onUpload \
  --trigger-event-filters=type=google.cloud.storage.object.v1.finalized \
  --trigger-event-filters=bucket=uploads-prod \
  --trigger-location=europe-west1 \
  --service-account=thumbs-runtime@"$PROJECT".iam.gserviceaccount.com \
  --trigger-service-account=thumbs-trigger@"$PROJECT".iam.gserviceaccount.com \
  --set-secrets=API_KEY=vision-key:2 \
  --memory=512Mi --timeout=300s --max-instances=20 --retry

gcloud functions deploy api --gen2 --region="$REGION" --runtime=python312 \
  --source=. --entry-point=api --trigger-http --no-allow-unauthenticated \
  --concurrency=20 --cpu=1 --memory=512Mi

• Use a runtime from gcloud functions runtimes list; do not guess the newest one.
• --concurrency above 1 requires --cpu of at least 1 and a thread-safe handler.
• Event-driven timeouts cap at 540 seconds; HTTP functions allow up to 3600 seconds.
• .gcloudignore controls what is uploaded; exclude node_modules, .venv, tests, .env.
• Deploying to production is outward-facing: show the command and target project, and wait for user confirmation.

Permissions that make triggers work

Identity	Needs
Runtime SA (--service-account)	Only what the code touches, e.g. roles/storage.objectUser on the bucket
Trigger SA (--trigger-service-account)	roles/run.invoker on the function, roles/eventarc.eventReceiver on the project
Cloud Storage service agent	roles/pubsub.publisher on the project, for Storage triggers
Pub/Sub service agent	roles/iam.serviceAccountTokenCreator on the trigger SA (older projects)
Build SA	Cloud Build may run as the default compute SA; pass --build-service-account to use a dedicated one with roles/cloudbuild.builds.builder

Most “trigger deployed but nothing happens” reports are a missing role in this table, or a trigger location that does not match the bucket’s location.

Retries and idempotency

• Without --retry, a failed event is dropped. With --retry, it is retried with backoff until the event age limit (about 24 hours for Pub/Sub-backed triggers). A handler that always throws on a bad message becomes a retry loop and a cost spike.
• Classify errors: transient (timeouts, 429, 5xx) raise; permanent (validation, missing object) log and return.
• Delivery is at-least-once. Deduplicate on event.id or a domain key (object generation, order ID) stored in Firestore or the DB with a create-if-absent write.
• For poison messages, configure a dead-letter topic on the underlying Pub/Sub subscription.
• A Storage-triggered function that writes back into the same bucket retriggers itself. Write outputs to another bucket or prefix and filter on it in code.

Migrating 1st gen

1st gen	2nd gen
exports.fn = (req, res) / (data, context)	functions.http / functions.cloudEvent with a CloudEvent
One request per instance	--concurrency up to 1000
--trigger-resource / --trigger-event	--trigger-event-filters (Eventarc)
Max 540 s for all	3600 s for HTTP

Deploy the 2nd gen function under a new name, shift callers or triggers, then delete the 1st gen function only after the user confirms.

Gotchas

• --allow-unauthenticated on an HTTP function makes it public; ask before using it.
• Background work after res.send() or after the CloudEvent handler resolves is throttled and may never run. Await everything.
• Large node_modules uploads slow builds; let Cloud Build install dependencies from the lockfile instead.
• Environment variable changes create a new revision; --update-env-vars merges, --set-env-vars replaces all.
• Logs from console.log of a JSON object string with severity become structured entries.

Verification

gcloud functions describe on-upload --region="$REGION" --format='value(state,serviceConfig.uri,eventTrigger.retryPolicy)'
gcloud functions logs read on-upload --region="$REGION" --limit=50
gcloud storage cp ./sample.jpg gs://uploads-prod/test/sample.jpg   # fire a real event (confirm first in prod)

• State is ACTIVE; the test event produces exactly one success log and the expected output.
• Sending the same event twice produces one side effect, not two.

Report template

**Function:** on-upload (gen2, nodejs22, europe-west1), entry point onUpload
**Trigger:** storage object finalized on uploads-prod, retry on, trigger SA thumbs-trigger@
**Runtime SA:** thumbs-runtime@ with storage.objectUser on uploads-prod and thumbs-prod
**Idempotency:** key bucket/name#generation in Firestore collection processed_uploads
**Tested:** local CloudEvent curl, one staging upload, duplicate event ignored