deploy-cloudrun GitHub Action

The deploy-cloudrun GitHub Action automates the deployment of container images or source code to Google Cloud Run. Once the deployment is complete, the resulting service URL is provided as a GitHub Actions output, allowing you to use it in subsequent workflow steps (e.g., for integration testing or notifications).

    - id: 'deploy'
      uses: 'google-github-actions/deploy-cloudrun@v3'
      with:
        service: 'hello-cloud-run'
        image: 'us-docker.pkg.dev/cloudrun/container/hello:latest'

    - name: 'Use output'
      run: 'curl "${{ steps.deploy.outputs.url }}"'

If you are using custom self-hosted runners located on Google Cloud, the action will automatically detect and use the Application Default Credentials (ADC) attached to the instance. No explicit authentication step is required in your workflow.

jobs:
  job_id:
    steps:
    - uses: 'google-github-actions/deploy-cloudrun@v3'
      with:
        image: 'us-docker.pkg.dev/cloudrun/container/hello:latest'
        service: 'hello-cloud-run'

To authorize the deployment, use the google-github-actions/auth action before the deploy-cloudrun step. This is typically done using Workload Identity Federation to avoid long-lived service account keys.

    - uses: 'google-github-actions/auth@v3'
      with:
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
        service_account: 'my-service-account@my-project.iam.gserviceaccount.com'

The recommended way to authenticate is using the google-github-actions/auth action. This supports Workload Identity Federation or Service Account Key JSON. Ensure your job has id-token: 'write' permissions if using Workload Identity Federation.

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
    - uses: 'google-github-actions/auth@v3'
      with:
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
        service_account: 'my-service-account@my-project.iam.gserviceaccount.com'

    - uses: 'google-github-actions/deploy-cloudrun@v3'
      with:
        image: 'us-docker.pkg.dev/cloudrun/container/hello:latest'
        service: 'hello-cloud-run'

Before using this action, ensure the following requirements are met:

1. Google Cloud Credentials: You must provide credentials authorized to access the Cloud Run resources. It is recommended to use google-github-actions/auth for authorization.
2. Node.js Runtime: This action runs on Node 24. If you are using self-hosted runners, ensure your runner environment supports Node 24 or newer.
3. Permissions: If using Workload Identity Federation, your job must have the following permissions:
   • contents: 'read'
   • id-token: 'write'

The service account used by the action must have the following permissions:

1. Cloud Run Admin (roles/run.admin): Required to create, update, and delete services, and to get/set IAM policies.
2. Service Account User (roles/iam.serviceAccountUser): The service account performing the deployment must be a member of the target service account (e.g., the Compute Engine default service account, PROJECT_NUMBER-compute@developer.gserviceaccount.com) with this role to allow it to act as that service account.

For advanced configurations (like memory limits, CPU allocation, or max instances), you can provide a path to a custom YAML service or job description using the metadata input.

⚠️ CRITICAL: When using the metadata input, all other inputs are ignored.

To create a new service definition, use a YAML structure following the Knative Service spec. To update an existing service, you can download the current configuration via gcloud and modify it:

gcloud run services describe SERVICE --format yaml > service.yaml

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    spec:
      containers:
      - image: IMAGE

The action allows you to control how traffic is distributed to Cloud Run revisions or tags after a deployment.

To use traffic management, you must provide a service name. You can use either revision_traffic or tag_traffic, but not both.

• revision_traffic: Directs traffic to a specific revision name (e.g., my-service-00001-abc).
• tag_traffic: Directs traffic to a specific tag (e.g., green).

If you want to deploy a new revision without routing traffic to it immediately, use the no_traffic input set to true (which applies the --no-traffic flag).

- name: Deploy and route traffic to a tag
  uses: google-github-actions/deploy-cloudrun@v2
  with:
    service: my-service
    image: gcr.io/my-project/my-image
    tag_traffic: green

Use the secrets input to inject secrets into your Cloud Run service. Provide KEY=VALUE pairs where the value is the secret identifier (e.g., secret-name:version).

Injection Methods:

• Environment Variables: Use standard KEY=VALUE syntax. The key becomes the environment variable name.
• Volume Mounts: Use a key starting with a forward slash / (e.g., /secrets/api/key=secret-name:latest). This mounts the secret as a file at the specified path.

Update Strategy: Use secrets_update_strategy to choose between merge (default) or overwrite (replaces all existing secrets). To remove all secrets, set the value to {}.

with:
  secrets: |-
    # As an environment variable:
    KEY1=secret-key-1:latest

    # As a volume mount:
    /secrets/api/key=secret-key-2:latest

You can control how traffic is distributed among revisions using one of two mutually-exclusive methods:

1. Revision Traffic (revision_traffic): Assign percentages to specific revision names or use the LATEST tag.
   • Example: my-revision=10 or LATEST=100.
2. Tag Traffic (tag_traffic): Assign percentages to specific traffic tags.
   • Example: my-tag=10.

If you use these inputs, you can also provide update_traffic_flags to pass extra arguments to the underlying update-traffic command.

with:
  revision_traffic: 'LATEST=100'

If the GitHub Action does not expose a specific Cloud Run feature, use the flags input to pass additional arguments directly to the gcloud run deploy or gcloud jobs deploy command.

Important Notes:

• The action does not validate these flags; you are responsible for ensuring they are valid for your gcloud version.
• If a flag contains other flags (e.g., --args), you must quote the entire outer flag value.

For traffic management, if you are using revision_traffic or tag_traffic, you can also use update_traffic_flags to pass additional arguments to the gcloud run services update-traffic command.

with:
  flags: '--add-cloudsql-instances=... "--args=-X=123"'