google-github-actions/auth@v3

Authenticate to Google Cloud from GitHub Actions via Workload Identity Federation or service account keys.

At a glance

Latest major
v3
Repository
google-github-actions/auth
Inputs
17 (0 required)
Outputs
5
Runs using
node24
License
Apache-2.0
Last checked

Inputs and outputs come straight from the action's official action.yml. See our editorial standards.

Usage

- uses: google-github-actions/auth@v3

Inputs

NameRequiredDefaultDescription
project_idNononeID of the default project to use for future API calls and invocations. If unspecified, this action will attempt to extract the value from other inputs such as "service_account" or "credentials_json".
workload_identity_providerNononeThe full identifier of the Workload Identity Provider, including the project number, pool name, and provider name. If provided, this must be the full identifier which includes all parts, for example: "projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider". This is mutually exclusive with "credentials_json".
service_accountNononeEmail address or unique identifier of the Google Cloud service account for which to generate credentials. This is required if "workload_identity_provider" is specified.
audienceNononeThe value for the audience (aud) parameter in GitHub's generated OIDC token. This value defaults to the value of "workload_identity_provider", which is also the default value Google Cloud expects for the audience parameter on the token.
credentials_jsonNononeThe Google Cloud JSON service account key to use for authentication. This is mutually exclusive with "workload_identity_provider".
create_credentials_fileNotrueIf true, the action will securely generate a credentials file which can be used for authentication via gcloud and Google Cloud SDKs.
export_environment_variablesNotrueIf true, the action will export common environment variables which are known to be consumed by popular downstream libraries and tools, including: - CLOUDSDK_PROJECT - CLOUDSDK_CORE_PROJECT - GCP_PROJECT - GCLOUD_PROJECT - GOOGLE_CLOUD_PROJECT If "create_credentials_file" is true, additional environment variables are exported: - CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE - GOOGLE_APPLICATION_CREDENTIALS - GOOGLE_GHA_CREDS_PATH If false, the action will not export any environment variables, meaning future steps are unlikely to be automatically authenticated to Google Cloud.
token_formatNononeOutput format for the generated authentication token. For OAuth 2.0 access tokens, specify "access_token". For OIDC tokens, specify "id_token". To skip token generation, leave this value empty.
delegatesNononeList of additional service account emails or unique identities to use for impersonation in the chain.
universeNogoogleapis.comThe Google Cloud universe to use for constructing API endpoints. The default universe is "googleapis.com", which corresponds to https://cloud.google.com. Trusted Partner Cloud and Google Distributed Hosted Cloud should set this to their universe address.
request_reasonNononeAn optional Reason Request System Parameter for each API call made by the GitHub Action. This will inject the "X-Goog-Request-Reason" HTTP header, which will provide user-supplied information in Google Cloud audit logs.
cleanup_credentialsNotrueIf true, the action will remove any created credentials from the filesystem upon completion. This only applies if "create_credentials_file" is true.
access_token_lifetimeNo3600sDesired lifetime duration of the access token, in seconds. This must be specified as the number of seconds with a trailing "s" (e.g. 30s). This is only valid when "token_format" is "access_token".
access_token_scopesNohttps://www.googleapis.com/auth/cloud-platformList of OAuth 2.0 access scopes to be included in the generated token. This is only valid when "token_format" is "access_token".
access_token_subjectNononeEmail address of a user to impersonate for Domain-Wide Delegation Access tokens created for Domain-Wide Delegation cannot have a lifetime beyond 1 hour. This is only valid when "token_format" is "access_token".
id_token_audienceNononeThe audience (aud) for the generated Google Cloud ID Token. This is only valid when "token_format" is "id_token".
id_token_include_emailNofalseOptional parameter of whether to include the service account email in the generated token. If true, the token will contain "email" and "email_verified" claims. This is only valid when "token_format" is "id_token".

Outputs

NameDescription
project_idProvided or extracted value for the Google Cloud project ID.
credentials_file_pathPath on the local filesystem where the generated credentials file resides. This is only available if "create_credentials_file" was set to true.
auth_tokenThe intermediate authentication token, which could be used to call other Google Cloud APIs, depending on how you configured IAM.
access_tokenThe Google Cloud access token for calling other Google Cloud APIs. This is only available when "token_format" is "access_token".
id_tokenThe Google Cloud ID token. This is only available when "token_format" is "id_token".

Read an output with ${{ steps.<step-id>.outputs.<name> }}; the step needs an id.

Examples

Authenticate with Workload Identity Federation

Keyless auth to Google Cloud; replaces service-account JSON keys.

name: Example
on:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write

jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - name: Authenticate to Google Cloud
        uses: google-github-actions/auth@v3
        with:
          workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github/providers/my-repo
          service_account: [email protected]

Each example passed actionlint (syntax, expressions and the inputs it knows for this action). They were not run in a live repository, so replace placeholder values such as names, ARNs and paths with your own.

Something out of date or wrong? Report it on our Contact page. This page is rebuilt from the action's repository roughly once a week.