A GitHub Action for deploying services to Google Cloud Run.
The deploy-cloudrun
GitHub Action deploys to Google Cloud Run. It
can deploy a container image or from source, and the resulting service URL is
available as a GitHub Actions output for use in future steps.
This is not an officially supported Google product, and it is not covered by a Google Cloud support contract. To report bugs or request features in a Google Cloud product, please contact Google Cloud support.
This action requires Google Cloud credentials that are authorized to access the secrets being requested. See Authorization for more information.
This action runs using Node 20. If you are using self-hosted GitHub Actions runners, you must use a runner version that supports this version or newer.
jobs:
job_id:
# ...
permissions:
contents: 'read'
id-token: 'write'
steps:
- uses: 'actions/checkout@v4'
- uses: 'google-github-actions/auth@v2'
with:
workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
service_account: '[email protected]'
- id: 'deploy'
uses: 'google-github-actions/deploy-cloudrun@v2'
with:
service: 'hello-cloud-run'
image: 'gcr.io/cloudrun/hello'
- name: 'Use output'
run: 'curl "${{ steps.deploy.outputs.url }}"'
service
: (Required, unless providing metadata
or job
) ID of the
service or fully-qualified identifier of the service. Only one of service
or job
may be specified.
job
: (Required, unless providing metadata
or service
) ID of the job or
fully-qualified identifier of the job. Only one of service
or job
may be
specified.
image
: (Required, unless providing metadata
or source
) Fully-qualified
name of the container image to deploy. For example:
gcr.io/cloudrun/hello:latest
or
us-docker.pkg.dev/my-project/my-container/image:1.2.3
source
: (Required, unless providing metadata
, image
, or job
) Path to
source to deploy. If specified, this will deploy the Cloud Run service from
the code specified at the given source directory.
This requires the Artifact Registry API to be enabled.
Furthermore, the deploying service account must have the Cloud Build Service Account
role. The initial deployment will create an Artifact
Registry repository which requires the Artifact Registry Admin
role.
Learn more about Deploying from source code.
suffix
: (Optional) String suffix to append to the revision name. Revision
names always start with the service name automatically. For example,
specifying 'v1' for a service named 'helloworld', would lead to a revision
named 'helloworld-v1'. The default value is no suffix.
env_vars
: (Optional) List of key=value pairs to set as environment
variables. All existing environment variables will be retained. If both
env_vars
and env_vars_file
are specified, the keys in env_vars
will take
precendence over the keys in env_vars_files
.
with:
env_vars: |
FOO=bar
ZIP=zap
Entries are separated by commas (,
) and newline characters. Keys and
values are separated by =
. To use ,
, =
, or newline characters, escape
them with a backslash:
with:
env_vars: |
[email protected]\,[email protected]
env_vars_file
: (Optional) Path to a file on disk, relative to the
workspace, that defines environment variables. The file can be
newline-separated KEY=VALUE pairs, JSON, or YAML format. If both env_vars
and env_vars_file
are specified, the keys in env_vars will take
precendence over the keys in env_vars_files.
FOO=bar
ZIP=zap
or
{
"FOO": "bar",
"ZIP": "zap"
}
or
FOO: 'bar'
ZIP: 'zap'
When specified as KEY=VALUE pairs, the same escaping rules apply as
described in env_vars
. You do not have to escape YAML or JSON.
secrets
: (Optional) List of key=value pairs to use as secrets. These can
either be injected as environment variables or mounted as volumes. All
existing environment secrets and volume mounts will be retained.
with:
secrets: |-
# As an environment variable:
KEY1=secret-key-1:latest
# As a volume mount:
/secrets/api/key=secret-key-2:latest
The same rules apply for escaping entries as from env_vars
, but Cloud Run
is more restrictive with allowed keys and names for secrets.
labels
: (Optional) List of key=value pairs to set as labels on the Cloud
Run service. Existing labels will be overwritten.
with:
labels: |-
my-label=my-value
The same rules apply for escaping entries as from env_vars
, but labels
have strict naming and casing requirements. See Requirements for
labels
for more information.
skip_default_labels
: (Optional) Skip applying the special annotation
labels that indicate the deployment came from GitHub Actions. The GitHub
Action will automatically apply the following labels which Cloud Run uses to
enhance the user experience:
managed-by: github-actions
commit-sha: <sha>
Setting this to true
will skip adding these special labels. The default
value is false
.
tag
: (Optional) Traffic tag to assign to the newly-created revision.
timeout
: (Optional) Maximum request execution time, specified as a
duration like "10m5s" for ten minutes and 5 seconds.
flags
: (Optional) Space separate list of other Cloud Run flags. This can
be used to access features that are not exposed via this GitHub Action.
with:
flags: '--add-cloudsql-instances=...'
See the complete list of flags for more information.
Please note, this GitHub Action does not parse or validate the flags. You
are responsible for making sure the flags are available on the gcloud
version and subcommand. When using tag_traffic
or revision_traffic
, the
subcommand is gcloud run services update-traffic
. For all other values,
the subcommand is gcloud run deploy
.
no_traffic
: (Optional) If true, the newly deployed revision will not
receive traffic. The default value is false.
revision_traffic
: (Optional, mutually-exclusive with tag_traffic
)
Comma-separated list of revision traffic assignments.
with:
revision_traffic: 'my-revision=10' # percentage
To update traffic to the latest revision, use the special tag "LATEST":
with:
revision_traffic: 'LATEST=100'
tag_traffic
: (Optional, mutually-exclusive with revision_traffic
)
Comma-separated list of tag traffic assignments.
with:
tag_traffic: 'my-tag=10' # percentage
project_id
: (Optional) ID of the Google Cloud project in which to deploy
the service. The default value is computed from the environment.
region
: (Optional) Regions in which the Cloud Run services are deployed.
This can be a single region or a comma-separated list of regions. The
default value is us-central1
.
gcloud_version
: (Optional) Version of the gcloud
CLI to use. The default
value is latest
.
gcloud_component
: (Optional) Component of the gcloud
CLI to use. Valid
values are alpha
and beta
.
For advanced use cases, you can define a custom Cloud Run metadata file. This is a YAML description of the Cloud Run service. This allows you to customize your service configuration, such as memory limits, CPU allocation, max instances, and more.
⚠️ When using a custom metadata YAML file, all other inputs are ignored!
metadata
: (Optional) The path to a Cloud Run service metadata file.To deploying a new service to create a new YAML service definition:
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
name: SERVICE
spec:
template:
spec:
containers:
- image: IMAGE
To update a revision or to deploy a new revision of an existing service, download and modify the YAML service definition:
gcloud run services describe SERVICE --format yaml > service.yaml
A Cloud Run product recommendation is that CI/CD systems not set or change settings for allowing unauthenticated invocations. New deployments are automatically private services, while deploying a revision of a public (unauthenticated) service will preserve the IAM setting of public (unauthenticated). For more information, see Controlling access on an individual service.
url
: The URL of your Cloud Run service.There are a few ways to authenticate this action. The caller must have permissions to access the secrets being requested.
You will need to authenticate to Google Cloud as a service account with the following roles:
roles/run.admin
):
This service account needs to be a member of the Compute Engine default service account
,
([email protected])
, with role
Service Account User
. To grant a user permissions for a service account, use
one of the methods found in Configuring Ownership and access to a service account.
Use google-github-actions/auth to authenticate the action. You can use Workload Identity Federation or traditional Service Account Key JSON authentication.
jobs:
job_id:
permissions:
contents: 'read'
id-token: 'write'
steps:
# ...
- uses: 'google-github-actions/auth@v2'
with:
workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
service_account: '[email protected]'
- uses: 'google-github-actions/deploy-cloudrun@v2'
with:
image: 'gcr.io/cloudrun/hello'
service: 'hello-cloud-run'
If you are hosting your own runners, and those runners are on Google Cloud, you can leverage the Application Default Credentials of the instance. This will authenticate requests as the service account attached to the instance. This only works using a custom runner hosted on GCP.
jobs:
job_id:
steps:
# ...
- uses: 'google-github-actions/deploy-cloudrun@v2'
with:
image: 'gcr.io/cloudrun/hello'
service: 'hello-cloud-run'
The action will automatically detect and use the Application Default Credentials.