Deploy services from source code

This page describes how to deploy a new service or service revision to Cloud Run directly from source code using a single gcloud CLI command, gcloud run deploy with the --source flag. For an example walkthrough of deploying a Hello World service, see Deploy from source quickstarts.

There are two different ways to use this feature:

Note that source deployments use Artifact Registry to store built containers. If your project doesn't already have an Artifact Registry repository with the name cloud-run-source-deploy in the region you are deploying to, this feature automatically creates an Artifact Registry repository with the name cloud-run-source-deploy.

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

By default, security fixes are only applied when the Cloud Run service is deployed. When you enable automatic security updates for a service, that service receives patches automatically with zero downtime. Learn more about configuring security updates.

Before you begin

  • Make sure you have set up a new project for Cloud Run as described in the setup page.

  • If you are under a domain restriction organization policy restricting unauthenticated invocations for your project, you will need to access your deployed service as described under Testing private services.

  • 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 the serviceusage.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 is automatically created.

Required roles

To deploy from source, you or your administrator must grant the deployer 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 with Cloud Run, see Cloud Run IAM roles and Cloud Run IAM permissions. If your Cloud Run service interfaces with Google Cloud APIs, such as Cloud Client Libraries, see the service identity configuration guide. For more information about granting roles, see deployment permissions and manage access.

Supported languages

In addition to sources with a Dockerfile, deploying from source supports the following languages using Google Cloud's buildpacks:

Runtime Source deployment Buildpack configuration
Go Deploy a Go service Configure Go buildpacks
Node.js Deploy a Node.js service Configure Node.js buildpacks
Python Deploy a Python service Configure Python buildpacks
Java
(includes Kotlin, Groovy, Scala)		 Deploy a Java service Configure Java buildpacks
.NET Deploy a .NET service Configure .NET buildpacks
Ruby Deploy a Ruby service Configure Ruby buildpacks
PHP Deploy a PHP service Configure PHP buildpacks

Read more details about supported language versions.

Deploy from source with build

This section describes how to use Google Cloud's buildpacks and Cloud Build to automatically build container images from your source code without having to install Docker on your machine or set up buildpacks or Cloud Build.

Limitations

  • Deploy from source uses Artifact Registry and Cloud Build, so this feature is only available in regions supported by Artifact Registry and Cloud Build.
  • Deploying from source is a convenience feature, and does not allow full customization of the build. For more control, build the container image using Cloud Build, for example, using gcloud builds submit, and then deploy the container image using, for example, gcloud run deploy --image.
  • Deploying from source with Google Cloud's buildpacks sets the Last Modified Date of source files to Jan 1, 1980. This is the default behavior of buildpacks and is designed to support reproducible builds. Depending on your language framework, this can affect browser-side caching of static files. If your application is affected by this, Google recommends disabling etag and Last-Modified HTTP headers in your application.
  • Deploying from source with Google Cloud's buildpacks always uses gcr.io/buildpacks/builder:latest. If your preferred language or OS configuration is not available in latest, use a specific builder to create an application image using your preferred builder.

  • You can deploy your service from source using Kotlin and other JVM languages such as Java. The language you use must conform to the 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 in Before 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 the serviceusage.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 the Cloud Build service account the following IAM roles.

Click to view required roles for the Cloud Build service account

Cloud Build automatically uses the Compute 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 grant Cloud Run Builder (roles/run.builder) to the Compute Engine default service account on your project:

  gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
      --role=roles/run.builder

Replace PROJECT_NUMBER with your Google Cloud project number, and PROJECT_ID with your Google Cloud project ID. For detailed instructions on how to find your project ID, and project number, see Creating and managing projects.

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

For a list of IAM roles and permissions that are associated with Cloud Run, see Cloud Run IAM roles and Cloud Run IAM permissions. If your Cloud Run service interfaces with Google Cloud APIs, such as Cloud Client Libraries, see the service identity configuration guide. For more information about granting roles, see deployment permissions and manage access.

Deploy with build

To deploy from source code, click the tab for instructions on using the tool of your choice.

gcloud

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

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud 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 if present, although it's not required.

  3. Build and deploy your service:

    gcloud run deploy SERVICE --source .

    Replace SERVICE with the name you want for your service.

  4. Respond to any prompts to install required APIs by responding y when prompted. You only need to do this once for a project. Respond to other prompts by supplying the platform and region, if you haven't set defaults for these as described in the setup page.

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

After deployment, this service revision serves 100% of traffic.

Cloud Code

To deploy from source using Cloud Code, read the IntelliJ and Visual Studio Code guides.

Gemini CLI

Use the /deploy command in the Gemini CLI tool to deploy a Cloud Run service from source code.

To use the Gemini CLI with the Cloud Run extension, follow these steps:

  1. Install the latest version of the Gemini CLI in one of the following development environments:

    • Terminal
    • Cloud Shell
    • VS Code using Gemini Code Assist agent mode (see the "VS Code" tab)

  2. Install the Cloud Run extension:

    gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp

  3. Sign in to the Google Cloud CLI:

    gcloud auth login

  4. Set up Application Default Credentials:

    gcloud auth application-default login

  5. Change to your source code directory.

  6. Launch the Gemini CLI:

    gemini

  7. Build and deploy your service:

    /deploy
    • If you are prompted to provide the Google Cloud project, enter your project name.
    • If you are prompted to select a tool, select deploy_local_folder.

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

MCP

To deploy a Cloud Run service from source code from a Model Context Protocol (MCP) client, install the Cloud Run Model Context Protocol (MCP) server.

Installation instructions vary depending on the MCP client. Often, they require adding the following lines to the settings JSON file:

"mcpServers":{
  "cloud-run": {
    "command": "npx",
    "args": ["-y", "@google-cloud/cloud-run-mcp"]
  }
}

Compose

You can store your Compose Specification in a YAML file and then deploy it from source code as a Cloud Run service using a single gcloud command.

  1. Change to your source directory. The source directory uses a Dockerfile if present, although it's not required.

  2. In your project directory, create a compose.yaml file with your service definitions.

    services:
  web:
    build: .
    ports:
      - "8080:8080"

    You can also specify more configuration options such as environment variables, secrets, and volume mounts.

  3. To deploy the services, run the gcloud beta run compose up command:

    gcloud beta run compose up compose.yaml

  4. Respond y to any prompts to install required components or to enable APIs.

  5. Optional: Make your service public if you want to allow unauthenticated access to the service.

After deployment, the Cloud Run service URL is displayed. Copy this URL and paste it into your browser to view the running container. You can disable the default authentication from the Google Cloud console.

Deploy from source without build

You can deploy source artifacts directly to Cloud Run, bypassing the Cloud Build step. The way this works is that instead of building a container image from source, you can upload a pre-packaged archive of your application directly to a Cloud Storage bucket. Cloud Run then takes this archive and runs it directly on a base image. This approach results in dramatically faster deployment times.

Limitations

Deploy to source without build only supports the following:

  • Cloud Run services.
  • Supported runtimes (no Dockerfile support).
  • Source archive (.tar.gz) <= 250 MiB.
  • Binary (for example, go binary) or script (for example, python script) must be compatible with x86 architecture.
  • The source has to be self-contained, with all the dependencies packaged. The runtime base image only contains the minimum operating system and a few language libraries.

Before you deploy without build

To use the "deploy without build" feature:

  • Make sure you have followed the steps in Before you begin.

  • Enable the Cloud Run and Cloud Storage APIs:

    gcloud services enable run.googleapis.com \
  storage.googleapis.com

  • You must install the application dependencies locally before deploying, as they won't be installed (no build).

Deploy without build

This section describes how to deploy your artifact directly to Cloud Run without using build.

gcloud

To deploy a local source directory, use the --no-build flag to tell the deploy command to bypass the Cloud Build step:

gcloud beta run deploy SERVICE_NAME \
  --source APPLICATION_PATH \
  --no-build \
  --base-image=BASE_IMAGE \
  --command=COMMAND \
  --args=ARG

Replace the following:

  • SERVICE_NAME: the name of your Cloud Run service.
  • APPLICATION_PATH: the location of your application on the local file system.
  • BASE_IMAGE: the runtime base image you want to use for your application. For example, us-central1-docker.pkg.dev/serverless-runtimes/google-22-full/runtimes/nodejs22.
  • COMMAND: the command that the container starts up with.
  • ARG: an argument you send to the container command. If you use multiple arguments, specify each on its own line.

YAML

You can store your service specification in a YAML file and then deploy it using the gcloud CLI or the Google Cloud console service.yaml editor.

  1. Create a storage bucket to hold your application:

    gcloud storage buckets create gs://BUCKET_NAME --location=BUCKET_LOCATION

    Replace the following:

    • BUCKET_NAME: the name you want to give your bucket, subject to naming requirements. For example, my-bucket.
    • BUCKET_LOCATION: the location of your bucket. For example, US.

  2. Create an archive with your application source using either zip or tar, for example:

    tar -cvzf ARCHIVE_NAME APPLICATION_PATH

    Replace the following:

    • ARCHIVE_NAME: the name of the archive to create. For example, app.tar.gz.
    • APPLICATION_PATH: the location of your application on the local file system. For example, ~/my-application. To archive the current working directory, set this value to *.

  3. Upload your application archive to Cloud Storage:

    gcloud storage cp ARCHIVE_NAME gs://BUCKET_NAME

    Replace the following:

    • ARCHIVE_NAME: the local path to the archive you created previously. For example, app.tar.gz.
    • BUCKET_NAME: the name of the bucket you created previously. For example, my-bucket.

  4. Create a new service.yaml file with the following content:

    apiVersion: serving.knative.dev/v2
kind: Service
metadata:
 name: SERVICE_NAME
spec:
 template:
   metadata:
     annotations:
       run.googleapis.com/sources: '{"": "gs://BUCKET_NAME/ARCHIVE_NAME"}'
       run.googleapis.com/base-images: '{"": "BASE_IMAGE"}'
   spec:
     containers:
     - image: scratch
       command:
       - COMMAND
       args:
       - ARG1
       - ARG-N
     runtimeClassName: run.googleapis.com/linux-base-image-update

    Replace the following:

    • SERVICE_NAME: the name of your Cloud Run service. Service names must be 49 characters or less and must be unique per region and project.
    • BUCKET_NAME: the name of the bucket you created previously. For example, my-bucket.
    • ARCHIVE_NAME: the local path to the archive you created previously. For example, app.tar.gz.
    • BASE_IMAGE: the runtime base image you want to use for your application. For example, us-central1-docker.pkg.dev/serverless-runtimes/google-22-full/runtimes/nodejs22.
    • COMMAND: the command that the container is to start up with.
    • ARG1: the argument you are sending to the container command. If you use multiple arguments, specify each on its own line, for example, as shown, ARG-N.

  5. Deploy the new service:

    gcloud run services replace service.yaml

REST API

REST API:

curl -H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-d '{"template": {"containers": [{"command": ["npm"], "args": ["start"], "image": "scratch", "baseImageUri": "google-22/nodejs22", "sourceCode": {"cloudStorageSource": {"bucket": "'GCS_BUCKET_NAME", "object":"ARCHIVE"}}}]}}' \
https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services?serviceId=SERVICE_NAME

Examples of deploying from source without build

This section shows examples of how to deploy from source without using build.

Node.js

Create a Node.js service:

  1. Create a new directory named helloworld and change directory into it:

    mkdir helloworld
cd helloworld

  2. Create a package.json file with the following contents:

    {
  "name": "helloworld",
  "description": "Simple hello world sample in Node",
  "version": "1.0.0",
  "private": true,
  "main": "index.js",
  "type": "module",
  "scripts": {
    "start": "node index.js"
  },
  "engines": {
    "node": ">=16.0.0"
  },
  "author": "Google LLC",
  "license": "Apache-2.0",
  "dependencies": {
    "express": "^4.17.1"
  }
}

  3. In the same directory, create a index.js file, and copy the following lines into it:

    import express from 'express';
const app = express();

app.get('/', (req, res) => {
  const name = process.env.NAME || 'World';
  res.send(`Hello ${name}!`);
});

const port = parseInt(process.env.PORT) || 8080;
app.listen(port, () => {
  console.log(`helloworld: listening on port ${port}`);
});

    This code creates a basic web server that listens on the port defined by the PORT environment variable.

  4. In your helloworld directory, run the following command to install the service dependencies locally:

    npm install

  5. In your helloworld directory, deploy the service using the --no-build flag, which tells the deploy command to skip the Cloud Build step:

    gcloud beta run deploy helloworld \
 --source . \
 --region=REGION \
 --no-build \
 --base-image=nodejs22 \
 --command=node \
 --args=index.js

    Replace the following:

    • REGION: the region where your service is deployed.

Python

Create a Python service:

  1. Create a new directory named helloworld and change directory into it:

    mkdir helloworld
cd helloworld

  2. Create a file named main.py and paste the following code into it:

    import os

from flask import Flask

app = Flask(__name__)


@app.route("/")
def hello_world():
    """Example Hello World route."""
    name = os.environ.get("NAME", "World")
    return f"Hello {name}!"


if __name__ == "__main__":
    app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

    This code responds to requests with our "Hello World" greeting. HTTP handling is done by a Gunicorn web server in the container. When directly invoked for local use, this code creates a basic web server that listens on the port defined by the PORT environment variable.

  3. Create a file named requirements.txt and paste the following code into it:

    Flask==3.0.3
gunicorn==23.0.0
Werkzeug==3.0.3

    This code adds packages needed by the sample.

  4. Vendor the dependencies:

    pip3 install -r requirements.txt --target=./vendor

  5. Deploy the service using the gcloud CLI. The --no-build flag tells the deploy command to bypass the Cloud Build step:

    gcloud beta run deploy hello_world \
  --source . \
  --region=REGION \
  --no-build \
  --base-image=python313 \
  --command=python \
  --args=main.py [--set-env-vars PYTHONPATH=./vendor]

Replace the following:

  • PYTHONPATH: path to the location of the copied dependencies.
  • REGION: the region where your service is deployed.

Troubleshooting

This section gives some tips on troubleshooting deploy from source without using build.

Local development

Deploying from source without using build works similarly to mounting your code or executable to the base image.

For example:

  1. Make a copy of all the contents:

    cp -R python/hello-world/ workspace

  2. Run the base image as root user with the source mounted. You can optionally include -p 8080:8080 if you need to curl from a host machine.

    docker run -it -v "LOCAL_PATH" -u 0 us-central1-docker.pkg.dev/serverless-runtimes/google-22-full/runtimes/python313 /bin/bash`

    Replace LOCAL_PATH with the location of your local source files.

  3. Run the server:

    python main.py

Execution log

The execution log is useful for debugging deployment failure. In the Google Cloud console, go to Observability > Logs.

Permission denied on Cloud Storage access

If your Cloud Run service is encountering "Permission denied" errors when trying to access Cloud Storage objects, you must grant the roles/storage.objectViewer role to your Cloud Run service account:

gcloud projects add-iam-policy-binding PROJECT \
  --member="SERVICE_ACCOUNT" \
  --role="roles/storage.objectViewer"

Replace the following:

  • PROJECT: your Google Cloud project ID.
  • SERVICE_ACCOUNT: your Cloud Run service account. For example, service-123@serverless-robot-staging.iam.gserviceaccount.com.

Automating building from source

As a best practice for avoiding unversioned changes in local source, Google recommends that you automatically deploy when changes are pushed to your Git repository. To make this easier, you can connect and configure continuous deployment to your Cloud Run service. By connecting your GitHub repositories to Cloud Run, you can configure builds and deploy your repositories without writing Dockerfiles or build files.

To configure automated builds, set up automation as described in the continuous builds page, making sure you choose the option for building source with buildpacks.

What's next

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

Learn about the source deploy configurations:

You can automate the builds and deployments of your Cloud Run services using Cloud Build triggers: