Deploy worker pools from source code

Preview — Cloud Run worker pools

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

This page describes how to deploy a new worker pool or worker pool revision toCloud Run directly from source code using a singlegcloud CLI command,gcloud beta run worker-pools deploy with the--source flag.Note: The deploy command defaults to source deployment if you don't supply--image or--source flags.Behind the scenes, this command usesGoogle Cloud's buildpacksand Cloud Build to automatically build container images from your sourcecode without having to install Docker on your machine or set up buildpacks orCloud Build. By default, Cloud Run uses thedefault machine type provided by Cloud Build.Runninggcloud beta run worker-pools deployeliminates the need to also run thegcloud builds submit command.

Note that source deployments useArtifact Registry tostore built containers. If your project doesn't already have an Artifact Registryrepository with the namecloud-run-source-deploy in the region you aredeploying to, this feature automatically creates an Artifact Registry repositorywith the namecloud-run-source-deploy.

If a Dockerfile is present in the source code directory, the uploaded sourcecode is built using that Dockerfile. If no Dockerfile is present in the sourcecode directory, Google Cloud's buildpacks automatically detects the language youare using and fetches the dependencies of the code to make a production-readycontainer image, using a secure base image managed by Google.

Before you begin

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

  • Enable the Cloud Run Admin API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

    Enable the API

    After the Cloud Run Admin API is enabled, the Compute Engine default service account isautomatically created.

Required roles

To deploy from source, you or your administrator must grant thedeployer account the following IAM roles.

Click to view required roles for the deployer account

To get the permissions that you need to build and deploy from source, ask your administrator to grant you the following IAM roles:

For a list of IAM roles and permissions that are associated withCloud Run, seeCloud Run IAM rolesandCloud Run IAM permissions.If your Cloud Run worker pool interfaces withGoogle Cloud APIs, such as Cloud Client Libraries, see theservice identity configuration guide.For more information about granting roles, seedeployment permissionsandmanage access.

Supported languages

In addition to sources with a Dockerfile, deploying from sourcesupports the following languages usingGoogle Cloud's buildpacks:

  • Go
  • Node.js
  • Python
  • Java
  • Kotlin
  • Groovy
  • Scala
  • .NET
  • Ruby
  • PHP

Read more details aboutsupported language versions.

Deploy from source with build

This section describes how to useGoogle Cloud's buildpacksand Cloud Build to automatically build container images from your sourcecode without having to install Docker on your machine or set up buildpacks orCloud Build.

Limitations

  • Deploy from source uses Artifact Registry and Cloud Build, so this feature is only available inregions supported by Artifact Registry andCloud Build.
  • Deploying from source is a conveniencefeature, and does not allow full customization of the build. For morecontrol, build the container image using Cloud Build, for example,usinggcloud builds submit, and thendeploy the container image using, for example,gcloud beta run worker-pools deploy --image.
  • Deploying from source with Google Cloud's buildpacks sets the Last Modified Dateof source files to Jan 1, 1980. This is the default behavior of buildpacks and is designed to supportreproducible builds. Depending on yourlanguage framework, this can affect browser-side caching of static files. Ifyour application is affected by this, Google recommends disablingetag andLast-Modified HTTP headers in your application.
  • Deploying from source with Google Cloud's buildpacks always usesgcr.io/buildpacks/builder:latest.If your preferred language or OS configuration is not available inlatest,use a specific builder tocreate an application image using your preferred builder.

  • You can deploy your worker pool from source using Kotlin and other JVM languagessuch asJava. The language you use must conform tothe following rules:

    • You can build the application using Maven or Gradle.
    • The build file contains all the plugins required to product classes.

Before you deploy with build

Before you deploy from source with build:

  • Follow the steps inBefore you begin.

  • Enable the Cloud Build API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

    Enable the API

Required roles

To deploy from source with build, you or your administrator must grant theCloud Build service account the following IAM roles.

Click to view required roles for the Cloud Build service account

Cloud Build automatically uses theCompute Engine default service account as the default Cloud Build service account to build your source code and Cloud Run resource, unless you override this behavior. For Cloud Build to build your sources, ask your administrator to grantCloud Run Builder (roles/run.builder) to the Compute Engine default service account on your project:

gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com\--role=roles/run.builder

ReplacePROJECT_NUMBER with your Google Cloud project number, andPROJECT_ID with your Google Cloud project ID. For detailed instructions on how to find your project ID, and project number, seeCreating and managing projects.

Granting the Cloud Run builder role to the Compute Engine default service account takes a couple of minutes topropagate.

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.

For a list of IAM roles and permissions that are associated withCloud Run, seeCloud Run IAM rolesandCloud Run IAM permissions.If your Cloud Run worker pool interfaces withGoogle Cloud APIs, such as Cloud Client Libraries, see theservice identity configuration guide.For more information about granting roles, seedeployment permissionsandmanage access.

Deploy with build

To deploy from source code:

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, aCloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Change to your source directory. The source directory uses a Dockerfile ifpresent, although it's not required.

  3. Build and deploy your worker pool:

    gcloudbetarunworker-poolsdeployWORKERPOOL--source.
     ReplaceWORKERPOOL with the name you want for your worker pool.

  4. Respond to any prompts to install required APIs by respondingy whenprompted. You only need to do this once for a project. Respond to otherprompts by supplying the platform and region, if you haven't set defaultsfor these as described in thesetup page.

  5. Wait for the build and deploy to complete. When finished,Cloud Run displays a success message.

Automating building from source

As a best practice for avoiding unversioned changes in local source, Googlerecommends that you automatically deploy when changes are pushed to your Gitrepository. To make this easier, you can connect and configure continuousdeployment to your Cloud Run worker pool. By connecting your GitHub repositories toCloud Run, you can configure builds and deploy your repositorieswithout writing Dockerfiles or build files.

What's next

After you deploy a Cloud Run worker pool, you can do the following:

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 2025-12-17 UTC.