Deploy to Google Cloud Run from GitHub Actions with Workload Identity Federation
Deploy to Cloud Run from GitHub Actions without service account keys: set up a Workload Identity pool, bind IAM roles, write the workflow.
At a glance
- Last reviewed
- Versions referenced
actions/checkout@v7google-github-actions/auth@v3google-github-actions/deploy-cloudrun@v3- Reading time
- 4 min read
Code samples are not run in a live repository. See our editorial standards.
On this page
To deploy to Cloud Run from GitHub Actions without a JSON key, create a Workload Identity pool and an OIDC provider for https://token.actions.githubusercontent.com, let your repository impersonate a service account through roles/iam.workloadIdentityUser, and run google-github-actions/auth with id-token: write before the deploy step. Most failures come from a mismatch between the claims in the GitHub token and the provider’s attribute condition or the service account binding. For a related walkthrough, see How to Choose a Hosting Provider for GitHub Actions Deploys.
Create the pool and provider
Run these commands once per project. They enable the required APIs, create the pool, and create an OIDC provider restricted to one repository.
PROJECT_ID="my-gcp-project-id"
POOL_NAME="github-pool"
PROVIDER_NAME="github-provider"
GITHUB_REPO="my-org/my-repo"
gcloud services enable \
iam.googleapis.com \
iamcredentials.googleapis.com \
sts.googleapis.com \
--project="${PROJECT_ID}"
gcloud iam workload-identity-pools create "${POOL_NAME}" \
--project="${PROJECT_ID}" \
--location="global" \
--display-name="GitHub Actions Pool"
gcloud iam workload-identity-pools providers create-oidc "${PROVIDER_NAME}" \
--project="${PROJECT_ID}" \
--location="global" \
--workload-identity-pool="${POOL_NAME}" \
--display-name="GitHub Actions Provider" \
--issuer-uri="https://token.actions.githubusercontent.com" \
--attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository" \
--attribute-condition="assertion.repository == '${GITHUB_REPO}'"
The issuer URI must be exactly https://token.actions.githubusercontent.com. The mapping google.subject=assertion.sub is required, and attribute.repository lets IAM bindings match on the repository name.
The --attribute-condition rejects tokens from any other repository at the provider. Without it, a workflow in any GitHub repository could present a token to your provider, so IAM bindings become your only protection.
Verify the provider
Print the full resource name. You need it in the workflow.
gcloud iam workload-identity-pools providers describe "${PROVIDER_NAME}" \
--project="${PROJECT_ID}" \
--location="global" \
--workload-identity-pool="${POOL_NAME}" \
--format="value(name)"
The value has this shape, with your numeric project number in place of the placeholder:
projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/github-pool/providers/github-provider
Create the service account and grant roles
The deployer service account needs roles/run.admin on the project and must be impersonable by your repository. Create it first.
export PROJECT_ID="my-gcp-project-id"
export SA_NAME="github-actions-cloud-run"
export SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"
export POOL_NAME="github-pool"
export REPO="my-org/my-repo"
gcloud iam service-accounts create "${SA_NAME}" \
--project="${PROJECT_ID}" \
--display-name="${SA_NAME}"
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
--member="serviceAccount:${SA_EMAIL}" \
--role="roles/run.admin"
If the Cloud Run service runs as a different (runtime) service account, the deployer must be allowed to act as it. Grant roles/iam.serviceAccountUser on the runtime account, not on the deployer:
gcloud iam service-accounts add-iam-policy-binding \
"runtime-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
--project="${PROJECT_ID}" \
--member="serviceAccount:${SA_EMAIL}" \
--role="roles/iam.serviceAccountUser"
If the service uses the default Compute Engine service account, grant the role on that account instead.
Allow the repository to impersonate the account
Bind roles/iam.workloadIdentityUser on the service account to the principal set for your repository.
export PROJECT_NUMBER=$(gcloud projects describe "${PROJECT_ID}" --format="value(projectNumber)")
gcloud iam service-accounts add-iam-policy-binding "${SA_EMAIL}" \
--project="${PROJECT_ID}" \
--role="roles/iam.workloadIdentityUser" \
--member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_NAME}/attribute.repository/${REPO}"
Do not use the pool-wide member .../workloadIdentityPools/${POOL_NAME}/* in production. It lets every identity the pool accepts impersonate the account, which is only as safe as your attribute condition.
Verify the bindings
gcloud iam service-accounts get-iam-policy "${SA_EMAIL}" \
--project="${PROJECT_ID}" \
--format="json"
The output must list roles/iam.workloadIdentityUser with your principalSet:// member under bindings.
gcloud projects get-iam-policy "${PROJECT_ID}" \
--flatten="bindings[].members" \
--filter="bindings.members:serviceAccount:${SA_EMAIL}" \
--format="table(bindings.role)"
This must list roles/run.admin.
Write the workflow
Grant id-token: write so the runner can request a GitHub OIDC token, then authenticate and deploy. Save this as .github/workflows/deploy.yml:
name: Deploy to Cloud Run
on:
push:
branches:
- main
permissions:
contents: read
id-token: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v7
- name: Authenticate to Google Cloud
uses: google-github-actions/auth@v3
with:
workload_identity_provider: projects/123456789012/locations/global/workloadIdentityPools/github-pool/providers/github-provider
service_account: github-actions-cloud-run@my-gcp-project-id.iam.gserviceaccount.com
- name: Deploy to Cloud Run
id: deploy
uses: google-github-actions/deploy-cloudrun@v3
with:
service: sample-app
region: us-central1
image: us-central1-docker.pkg.dev/my-gcp-project-id/sample-repo/sample-app:latest
- name: Print service URL
run: echo "${{ steps.deploy.outputs.url }}"
workload_identity_provider takes the full provider resource name with the numeric project number, not the project ID. service_account is the email of the account you bound above. The deploy action picks up the credentials that the auth step exports, so no key file is involved.
The image must already exist in Artifact Registry. This workflow deploys an existing image and does not build one.
Verify the deployment
Push to main and open the run in the Actions tab. The auth step must pass, and the last step prints the service URL. Then confirm from your machine:
gcloud run services describe sample-app \
--project="my-gcp-project-id" \
--region="us-central1" \
--format="value(status.url)"
Troubleshoot common failures
Permission ‘iam.serviceAccounts.getAccessToken’ denied
The auth step fails with Permission 'iam.serviceAccounts.getAccessToken' denied on resource (or it may not exist). Either the federated identity has no roles/iam.workloadIdentityUser on the service account, or the service_account email in the workflow is wrong.
Check these in order:
- The
service_accountvalue matches an existing account exactly. - The binding exists on the service account itself, not only at the project level. Re-run the
get-iam-policycommand above. - The
principalSetuses the project number, the right pool name, and the repository inowner/repoform that matches the token’srepositoryclaim. - The
iamcredentials.googleapis.comAPI is enabled.
After fixing the binding, re-run the workflow. IAM changes can take a short time to propagate.
The auth step cannot find the provider or token is rejected
A malformed workload_identity_provider is the usual cause. Use the numeric project number, the correct pool and provider names, and no leading //iam.googleapis.com/. Compare your value to the output of the providers describe command above.
Get the project number with:
gcloud projects describe my-gcp-project-id --format="value(projectNumber)"
The attribute condition rejects the token
If the provider has a condition, the token must satisfy it. Print it:
gcloud iam workload-identity-pools providers describe github-provider \
--project="my-gcp-project-id" \
--workload-identity-pool="github-pool" \
--location="global" \
--format="value(attributeCondition)"
The output for the provider created above is:
assertion.repository == 'my-org/my-repo'
A mismatch usually means a typo in the repository name, a case difference, or a fork or renamed repository. If you add assertion.ref == 'refs/heads/main' to the condition, pull request and tag runs will fail by design. Change it with gcloud iam workload-identity-pools providers update-oidc.
The auth step fails with a missing OIDC token error
If the workflow lacks permissions: id-token: write at the workflow or job level, the runner cannot request a token. Note that setting permissions at all removes the default for unlisted scopes, so keep contents: read for checkout. For a related walkthrough, see Fix ‘Resource not accessible by integration’ (403) in GitHub Actions.
Authentication works but the deploy fails with PERMISSION_DENIED
If the deploy step reports a missing permission such as run.services.create, the deployer account lacks Cloud Run rights. Re-check the roles/run.admin binding with the project-level verification command. If the error mentions acting as another service account, add roles/iam.serviceAccountUser on the runtime account as shown earlier.
Re-run the workflow and confirm the deploy step finishes and the printed URL responds.
Spotted an error? Report it on our Contact page and see our editorial standards for how we correct articles.