Authenticate to Google Cloud from GitHub Actions

This GitHub Action authenticates to Google Cloud. It supports authentication via a Google Cloud Service Account Key JSON and authentication via [Workload Identity Federation][wif].

Workload Identity Federation is recommended over Service Account Keys as it obviates the need to export a long-lived credential and establishes a trust delegation relationship between a particular GitHub Actions workflow invocation and permissions on Google Cloud. There are three ways to set up this GitHub Action to authenticate to Google Cloud:

1. (Preferred) Direct Workload Identity Federation
2. Workload Identity Federation through a Service Account
3. Service Account Key JSON

[!IMPORTANT] The gsutil command will not use the credentials exported by this GitHub Action. Customers should use gcloud storage instead.

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.

Prerequisites

• Run the actions/checkout@v4 step before this action. Omitting the checkout step or putting it after auth will cause future steps to be unable to authenticate.

• To create binaries, containers, pull requests, or other releases, add the following to your .gitignore, .dockerignore and similar files to prevent accidentally committing credentials to your release artifact:

  # Ignore generated credentials from google-github-actions/auth
  gha-creds-*.json
  

• This action runs using Node 24. Use a runner version that supports this version of Node or newer.

Usage

jobs:
  job_id:
    # Any runner supporting Node 20 or newer
    runs-on: ubuntu-latest

    # Add "id-token" with the intended permissions.
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
    - uses: 'actions/checkout@v4'

    - uses: 'google-github-actions/auth@v3'
      with:
        project_id: 'my-project'
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'

[!NOTE]

Changing the permissions block may remove some default permissions. See the [permissions documentation][github-perms] for more information.

For more usage options, see the examples.

Inputs

Inputs: Workload Identity Federation

[!WARNING]

This option is not supported by Firebase Admin SDK. Use Service Account Key JSON authentication instead.

[!WARNING]

As of the time of this writing, the GitHub OIDC token expires in 5 minutes, which means any derived credentials also expire in 5 minutes.

The following inputs are for authenticating to Google Cloud via Workload Identity Federation.

• workload_identity_provider: (Required) The 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:

  projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider
  

• service_account: (Optional) Email address or unique identifier of the Google Cloud service account for which to impersonate and generate credentials. For example:

  my-service-account@my-project.iam.gserviceaccount.com
  

  Without this input, the GitHub Action will use Direct Workload Identity Federation. If this input is provided, the GitHub Action will use Workload Identity Federation through a Service Account.

• audience: (Optional) The value for the audience (aud) parameter in the generated GitHub Actions 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.

Inputs: Service Account Key JSON

[!CAUTION]

Service Account Key JSON credentials are long-lived credentials and must be treated like a password.

The following inputs are for authenticating to Google Cloud via a Service Account Key JSON.

• credentials_json: (Required) The Google Cloud Service Account Key JSON to use for authentication.

  We advise minifying your JSON into a single line string before storing it in a GitHub Secret. When a GitHub Secret is used in a GitHub Actions workflow, each line of the secret is masked in log output. This can lead to aggressive sanitization of benign characters like curly braces ({}) and brackets ([]).

  To generate access tokens or ID tokens using this service account, you must grant the underlying service account roles/iam.serviceAccountTokenCreator permissions on itself.

Inputs: Generating OAuth 2.0 access tokens

The following inputs are for generating OAuth 2.0 access tokens for authenticating to Google Cloud as an output for use in future steps in the workflow. These options only apply to access tokens generated by this action. By default, this action does not generate any tokens.

• service_account: (Required) Email address or unique identifier of the Google Cloud service account for which to generate the access token. For example:

  my-service-account@my-project.iam.gserviceaccount.com
  

• token_format: (Required) This value must be "access_token" to generate OAuth 2.0 access tokens.

• access_token_lifetime: (Optional) Desired lifetime duration of the access token, in seconds. This must be specified as the number of seconds with a trailing "s" (e.g. 30s). The default value is 1 hour (3600s). The maximum value is 1 hour, unless the constraints/iam.allowServiceAccountCredentialLifetimeExtension organization policy is enabled, in which case the maximum value is 12 hours.

• access_token_scopes: (Optional) List of OAuth 2.0 access scopes to be included in the generated token. This is only valid when "token_format" is "access_token". The default value is:

  https://www.googleapis.com/auth/cloud-platform
  

  This can be specified as a comma-separated or newline-separated list.

• access_token_subject: (Optional) Email address of a user to impersonate for [Domain-Wide Delegation][dwd]. Access tokens created for Domain-Wide Delegation cannot have a lifetime beyond 1 hour, even if the constraints/iam.allowServiceAccountCredentialLifetimeExtension organization policy is enabled.

  In order to support Domain-Wide Delegation via Workload Identity Federation, you must grant the external identity ("principalSet") roles/iam.serviceAccountTokenCreator in addition to roles/iam.workloadIdentityUser. The default Workload Identity setup will only grant the latter role. If you want to use this GitHub Action with Domain-Wide Delegation, you must manually add the "Service Account Token Creator" role onto the external identity.

  You will also need to customize the access_token_scopes value to correspond to the OAuth scopes required for the API(s) you will access.

Inputs: Generating ID tokens

The following inputs are for generating ID tokens for authenticating to Google Cloud as an output for use in future steps in the workflow. These options only apply to ID tokens generated by this action. By default, this action does not generate any tokens.

[!CAUTION]

ID Tokens have a maximum lifetime of 10 minutes. This value cannot be changed.

• service_account: (Required) Email address or unique identifier of the Google Cloud service account for which to generate the ID token. For example:

  my-service-account@my-project.iam.gserviceaccount.com
  

• token_format: This value must be "id_token" to generate ID tokens.

• id_token_audience: (Required) The audience for the generated ID Token.

• id_token_include_email: (Optional) Optional 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". The default value is false.

Inputs: Miscellaneous

The following inputs are for controlling the behavior of this GitHub Actions, regardless of the authentication mechanism.

• project_id: (Optional) Custom project ID to use for authentication and exporting into other steps. If unspecified, we will attempt to extract the project ID from the Workload Identity Provider, Service Account email, or the Service Account Key JSON. If this fails, you will need to specify the project ID manually.

• create_credentials_file: (Optional) If true, the action will securely generate a credentials file which can be used for authentication via gcloud and Google Cloud SDKs in other steps in the workflow. The default is true.

  The credentials file is exported into $GITHUB_WORKSPACE, which makes it available to all future steps and filesystems (including Docker-based GitHub Actions). The file is automatically removed at the end of the job via a post action. In order to use exported credentials, you must add the actions/checkout step before calling auth. This is due to how GitHub Actions creates $GITHUB_WORKSPACE:

  jobs:
   job_id:
     steps:
     - uses: 'actions/checkout@v4' # Must come first!
     - uses: 'google-github-actions/auth@v3'
  

• export_environment_variables: (Optional) If true, the action will export common environment