Create triggers from Pub/Sub events

In Cloud Run, you can trigger services in response toPub/Sub messages using Eventarc. When youspecify a Pub/Sub trigger for your service, you also specify aPub/Sub topic. As a result of this trigger, your service is called wheneveryou publish a message to the specified topic.

TheGoogle Events repository contains additional resources for working with event data.

Before you begin

  1. Make sure you have set up a new project for Cloud Run as describedin thesetup page.

  2. Enable the Artifact Registry, Cloud Build, Cloud Run Admin API, Eventarc, Cloud Logging, and Pub/Sub APIs:

    Enable the APIs

Set required roles

You or your administrator must grant the deployer account, the trigger identity,and optionally, the Pub/Sub service agent the followingIAM roles.

Required roles for the deployer account

To get the permissions that you need to trigger from Pub/Sub events, ask your administrator to grant you the following IAM roles on your project:

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Note that by default,Cloud Build permissions include permissions to upload and download Artifact Registry artifacts.

Required roles for the trigger identity

  1. Make note of theCompute Enginedefault service account as you will you attach it to an Eventarc trigger to representthe identity of the trigger for testing purposes. This service account is automatically createdafter enabling or using a Google Cloud service that uses Compute Engine, and with thefollowing email format:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    ReplacePROJECT_NUMBER with your Google Cloudproject number. You can find your project number on theWelcomepage of the Google Cloud console or by running the following command:

    gcloudprojectsdescribePROJECT_ID--format='value(projectNumber)'

    For production environments, we strongly recommendcreating a new service accountand granting it one or more IAM roles that contain theminimum permissions requiredand follow the principle ofleast privilege.

    Note:

    Theiam.automaticIamGrantsForDefaultServiceAccounts organization policy constraint prevents the Editor role from being automatically granted to default service accounts. If you created your organization after May 3, 2024, this constraint is enforced by default.

    We strongly recommend that you enforce this constraint to disable the automatic role grant. If you disable the automatic role grant, you must decide which roles to grant to the default service accounts, and thengrant these roles yourself.

    If the default service account already has the Editor role, we recommend that you replace the Editor role with less permissive roles.To safely modify the service account's roles, usePolicy Simulator to see the impact of the change, and thengrant and revoke the appropriate roles.

  2. By default, Cloud Run services are only callable by ProjectOwners, Project Editors, and Cloud Run Admins and Invokers.You cancontrolaccess on a per-service basis; however, for testing purposes, grant theCloud RunInvoker role (run.invoker) on the Google Cloud project to theCompute Engine service account. This grants the role on allCloud Run services and jobs in a project.
    gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com\--role=roles/run.invoker

    Note that if you create a trigger for an authenticatedCloud Run service without granting the Cloud RunInvoker role, the trigger is created successfully and is active. However, thetrigger will not work as expected and a message similar to the following appearsin the logs:

    The request was not authenticated. Either allowunauthenticated invocations or set the proper Authorization header.
  3. Grant theEventarcEvent Receiver role (roles/eventarc.eventReceiver) on theproject to the Compute Engine default service account so thatthe Eventarc trigger can receive events from event providers.
    gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com\--role=roles/eventarc.eventReceiver

Optional role for the Pub/Sub service agent

  • If you enabled the Cloud Pub/Sub service agent on or before April8, 2021, to support authenticated Pub/Sub push requests, granttheServiceAccount Token Creator role (roles/iam.serviceAccountTokenCreator)to the service agent. Otherwise, this role is granted by default:
    gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com\--role=roles/iam.serviceAccountTokenCreator

Create a trigger for services

You can specify a trigger after you deploy a service.

Click the tab for instructions using the tool of your choice.

Console

  1. Deploy your Cloud Run service usingcontainers or fromsource.

  2. In the Google Cloud console, go toCloud Run:

    Go to Cloud Run

  3. From the list of services, click an existing service.

  4. On the Service details page, navigate to theTriggers tab.

  5. ClickAdd trigger, and selectPub/Sub trigger.

  6. In theEventarc trigger pane, modify thetrigger details as follows:

    1. In theTrigger name field, enter a name for the trigger, or usethe default name.

    2. Select aTrigger type from the list to specify one ofthe following trigger types:

      • Google Sources to specify triggers forPub/Sub, Cloud Storage, Firestore,and other Google event providers.

      • Third-party to integrate with non-Google providersthat offer an Eventarc source. For more information,seeThird-party events in Eventarc.

    3. SelectPub/Sub from theEvent provider list, to select a productthat provides the type of event for triggering your service. Forthe list of event providers, seeEvent providers and destinations.

    4. Selectgoogle.cloud.pubsub.topic.v1.messagePublished from theEvent type list. Yourtrigger configuration varies depending on the supported event type.For more information, seeEvent types.

    5. From theSelect a Cloud Pub/Sub topic topicfield, choose a topic for the trigger to monitor. Messages you publish to thistopic trigger calls to your function.

    6. If theRegion field is enabled, select alocationfor the Eventarctrigger. In general, the location of an Eventarctrigger should match the location of the Google Cloud resource thatyou want to monitor for events. In most scenarios, you should alsodeploy your service in the same region. SeeUnderstand Eventarc locationsfor more details about Eventarc trigger locations.

    7. In theService account field, select a service account.Eventarc triggers are linked to service accounts touse as an identity when invoking your service. YourEventarc trigger's service account must have the permissionto invoke your service. By default, Cloud Runuses theCompute Engine default service account.

    8. Optionally, specify theService URL path to send the incomingrequest to. This is the relative path on the destination service towhich the events for the trigger should be sent. For example:/,/route,route, androute/subroute.

    9. Once you've completed the required fields, clickSave trigger.

  7. After creating the trigger, verify its health by ensuring thatthere is a checkmark on theTriggers tab.

    Note: Although a trigger is created immediately, it can take up to twominutes for a trigger to propagate and filter events.

gcloud

  1. Deploy your Cloud Run service usingcontainers or fromsource.

  2. Run the following command to create a trigger that filters events:

    gcloud eventarc triggers createTRIGGER_NAME  \    --location=EVENTARC_TRIGGER_LOCATION \    --destination-run-service=SERVICE  \    --destination-run-region=REGION \    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \    --transport-topic=projects/PROJECT_ID/topics/TOPIC_ID \    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Replace:

    • TRIGGER_NAME with the name for your trigger.

    • EVENTARC_TRIGGER_LOCATION with the location forthe Eventarc trigger. In general, the location of anEventarc trigger should match the location of the Google Cloud resource that you want to monitor for events. In most scenarios, you should also deploy your service in the same region. For more information, seeEventarc locations.

    • SERVICE with the name of the service you aredeploying.

    • REGION with the Cloud Runregionof the service. For example,europe-west1.

    • PROJECT_NUMBER with your Google Cloud project number. Eventarc triggers are linked to service accounts to useas an identity when invoking your service. Your Eventarc trigger's service account must have the permission to invoke your service. Bydefault, Cloud Run uses the Default compute service account.

    Eachevent-filters flag specifies a type of event, with the functiontriggering only when an event meets all of the criteria specified in itsevent-filters flags. Each trigger must have anevent-filters flagspecifying a supportedevent type,such as a new document written to Firestore or a file uploadedto Cloud Storage. You can't change the event filter type after creation.To change the event filter type, you must create a new trigger anddelete the old one. Optionally, you can repeat the--event-filtersflag with a supported filter in the formATTRIBUTE=VALUE to add morefilters.

Terraform

To create an Eventarc trigger for a Cloud Run service, seeCreate a trigger using Terraform.

Create a trigger for functions

Click the tab for instructions using the tool of your choice.

Console

When you use the Google Cloud console to create a function, you can also add a triggerto your function. Follow these steps to create a trigger for your function:

  1. In the Google Cloud console, go to Cloud Run:

    Go to Cloud Run

  2. ClickWrite a function, and enter the function details. For moreinformation about configuring functions during deployment, seeDeploy functions.

  3. In theTrigger section, clickAdd trigger.

  4. SelectPub/Sub trigger.

  5. In theEventarc trigger pane, modify thetrigger details as follows:

    1. Enter a name for the trigger in theTrigger name field, or usethe default name.

    2. Select aTrigger type from the list:

      • Google Sources to specify triggers forPub/Sub, Cloud Storage, Firestore,and other Google event providers.

      • Third-party to integrate with non-Google providersthat offer an Eventarc source. For more information,seeThird-party events in Eventarc.

    3. SelectPub/Sub from theEvent provider list, to select a productthat provides the type of event for triggering your function. Forthe list of event providers, seeEvent providers and destinations.

    4. Selectgoogle.cloud.pubsub.topic.v1.messagePublished from theEvent type list. Yourtrigger configuration varies depending on the supported event type.For more information, seeEvent types.

    5. From theSelect a Cloud Pub/Sub topic topicfield, choose a topic for the trigger to monitor. Messages you publish to thistopic trigger calls to your function.

    6. If theRegion field is enabled, select alocationfor the Eventarctrigger. In general, the location of an Eventarctrigger should match the location of the Google Cloud resource thatyou want to monitor for events. In most scenarios, you should alsodeploy your function in the same region. SeeUnderstand Eventarc locationsfor more details about Eventarc trigger locations.

    7. In theService account field, select a service account.Eventarc triggers are linked to service accounts touse as an identity when invoking your function. YourEventarc trigger's service account must have the permissionto invoke your function. By default, Cloud Runuses theCompute Engine default service account.

    8. Optionally, specify theService URL path to send the incomingrequest to. This is the relative path on the destination service towhich the events for the trigger should be sent. For example:/,/route,route, androute/subroute.

  6. Once you've completed the required fields, clickSave trigger.

  7. ClickCreate.

  8. In theSource tab, edit the source code if needed, then selectSave and redeploy.

gcloud

When you create a function using the gcloud CLI, you must firstdeploy your function, and then create atrigger. Follow these steps to create a trigger for your function:

  1. Run the following command in the directory that contains the sample codeto deploy your function:

    gcloud run deployFUNCTION \        --source . \        --functionFUNCTION_ENTRYPOINT \        --base-imageBASE_IMAGE_ID \        --regionREGION

    Replace:

    • FUNCTION with the name of the function you aredeploying. You can omit this parameter entirely,but you will be prompted for the name if you omit it.

    • FUNCTION_ENTRYPOINT with the entry point to your function inyour source code. This is the code Cloud Run executes when yourfunction runs. The value of this flag must be a function name orfully-qualified class name that exists in your source code.

    • BASE_IMAGE_ID with the base image environment for yourfunction. For more details about base images and the packages includedin each image, seeRuntimes base images.

    • REGION with the Google Cloudregion where you want to deployyour function. For example,europe-west1.

  2. Run the following command to create a trigger that filters events:

    gcloud eventarc triggers createTRIGGER_NAME  \    --location=EVENTARC_TRIGGER_LOCATION \    --destination-run-service=FUNCTION  \    --destination-run-region=REGION \    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \    --transport-topic=projects/PROJECT_ID/topics/TOPIC_ID \    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Replace:

    • TRIGGER_NAME with the name for your trigger.

    • EVENTARC_TRIGGER_LOCATION with the location forthe Eventarc trigger. In general, the location of anEventarc trigger should match the location of the Google Cloud resource that you want to monitor for events. In most scenarios, you should also deploy your function in the same region. For more information, seeEventarc locations.

    • FUNCTION with the name of the function you aredeploying.

    • REGION with the Cloud Runregionof the function.

    • PROJECT_NUMBER with your Google Cloud project number. Eventarc triggers are linked to service accounts to useas an identity when invoking your function. Your Eventarc trigger's service account must have the permission to invoke your function. Bydefault, Cloud Run uses the Default compute service account.

    Eachevent-filters flag specifies a type of event, with the functiontriggering only when an event meets all of the criteria specified in itsevent-filters flags. Each trigger must have anevent-filters flagspecifying a supportedevent type,such as a new document written to Firestore or a file uploadedto Cloud Storage. You can't change the event filter type after creation.To change the event filter type, you must create a new trigger anddelete the old one. Optionally, you can repeat the--event-filtersflag with a supported filter in the formATTRIBUTE=VALUE to add morefilters.

Terraform

To create an Eventarc trigger for a Cloud Run function,seeCreate a trigger using Terraform.

Next steps

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.