This GitHub Action authenticates to Google Cloud. It supports authentication via a Google Cloud Service Account Key JSON and authentication via Workload Identity Federation.
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:
[!IMPORTANT] The
gsutil
command will not use the credentials exported by this GitHub Action. Customers should usegcloud 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.
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 20. Use a runner version that supports this version of Node or newer.
jobs:
job_id:
# Add "id-token" with the intended permissions.
permissions:
contents: 'read'
id-token: 'write'
steps:
- uses: 'actions/checkout@v4'
- uses: 'google-github-actions/auth@v2'
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 for more information.
For more usage options, see the examples.
[!WARNING]
This option is not supported by Firebase Admin SDK. Use Service Account Key JSON authentication instead.
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.
[!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.
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. 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.
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.
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@v2'
export_environment_variables
: (Optional) If 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. The default value is true.
delegates
: (Optional) List of additional service account emails or unique
identities to use for impersonation in the chain. By default there are no
delegates. This can be specified as a comma-separated or newline-separated
list.
universe
: (Optional) The 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.
You can also override individual API endpoints by setting the environment
variable GHA_ENDPOINT_OVERRIDE_<endpoint>
where endpoint is the API
endpoint to override. This only applies to the auth
action and does not
persist to other steps. For example:
env:
GHA_ENDPOINT_OVERRIDE_oauth2: 'https://oauth2.myapi.endpoint/v1'
request_reason
: (Optional) An 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_credentials
: (Optional) If true, the action will remove any
created credentials from the filesystem upon completion. This only applies
if "create_credentials_file" is true. The default is true.
project_id
: Provided or extracted value for the Google Cloud project ID.
credentials_file_path
: Path on the local filesystem where the generated
credentials file resides. This is only available if
"create_credentials_file" was set to true.
auth_token
: The Google Cloud federated token (for Workload Identity
Federation) or self-signed JWT (for a Service Account Key JSON). This output
is always available.
access_token
: The Google Cloud access token for calling other Google Cloud
APIs. This is only available when "token_format" is "access_token".
id_token
: The Google Cloud ID token. This is only available when
"token_format" is "id_token".
This section describes the three configuration options:
[!IMPORTANT]
It can take up to 5 minutes for Workload Identity Pools, Workload Identity Providers, and IAM permissions to propagate. Please wait at least five minutes and follow all Troubleshooting steps before opening an issue.
In this setup, the Workload Identity Pool has direct IAM permissions on Google
Cloud resources; there are no intermediate service accounts or keys. This is
preferred since it directly authenticates GitHub Actions to Google Cloud without
a proxy resource. However, not all Google Cloud resources support principalSet
identities, and the resulting token has a maximum lifetime of 10 minutes. Please
see the documentation for your Google Cloud service for more information.
[!IMPORTANT]
To generate OAuth 2.0 access tokens or ID tokens, you must provide a service account email, and the Workload Identity Pool must have
roles/iam.workloadIdentityUser
permissions on the target Google Cloud Service Account. Follow the steps for Workload Identity Federation through a Service Account instead.
In this setup, the Workload Identity Pool impersonates a Google Cloud Service Account which has IAM permissions on Google Cloud resources. This exchanges the GitHub Actions OIDC token with a Google Cloud OAuth 2.0 access token by granting GitHub Actions permissions to mint tokens for the given Service Account. Thus GitHub Actions inherits that Service Account's permissions by proxy.
In this setup, a Service Account has direct IAM permissions on Google Cloud resources. You download a Service Account Key JSON file and upload it to GitHub as a secret.
[!CAUTION]
Google Cloud Service Account Key JSON files must be secured and treated like a password. Anyone with access to the JSON key can authenticate to Google Cloud as the underlying Service Account. By default, these credentials never expire, which is why the former authentication options are much preferred.