google-github-actions/auth

Authenticate to Google Cloud, ideally via keyless Workload Identity Federation.

Official actionCategory: Cloud Auth & DeployLatest v2View on GitHub

What it does

google-github-actions/auth authenticates to Google Cloud so the gcloud CLI and client libraries work in later steps.

The recommended mode is Workload Identity Federation, which exchanges the GitHub OIDC token for GCP credentials with no exported service-account key.

Usage

workflow (.yml)

permissions:
  id-token: write
  contents: read
steps:
  - uses: google-github-actions/auth@v2
    with:
      workload_identity_provider: projects/123/locations/global/workloadIdentityPools/gh/providers/gh
      service_account: ci@my-project.iam.gserviceaccount.com

Inputs

Input	Description	Default	Required
`workload_identity_provider`	Full WIF provider resource name.	-	No
`service_account`	Service account email to impersonate.	-	No
`project_id`	GCP project ID.	-	No
`credentials_json`	Service-account key JSON (avoid; prefer WIF).	-	No
`token_format`	Token to produce: access_token or id_token.	-	No

Outputs

Output	Description
`credentials_file_path`	Path to the exported credentials file.
`access_token`	A short-lived access token, if requested.

Notes

Workload Identity Federation needs permissions: id-token: write and a pool/provider that trusts your repo.

Common errors

Unable to acquire impersonated credentials usually means the service account has not granted the WIF principal the Workload Identity User role.
A missing id-token: write permission makes WIF fail before it starts.

Security and pinning

Use Workload Identity Federation instead of credentials_json. It avoids a long-lived key in your secrets.

Alternatives and related

google-github-actions/setup-gcloudInstall and configure the gcloud CLI on the runner.

Frequently asked questions

How do I use GCP without a service-account key file?

Set up Workload Identity Federation, then pass workload_identity_provider and service_account with permissions: id-token: write.

References

GitHub Actions documentation