google-github-actions/auth: Google Cloud Authentication for GitHub Actions

Why the action exists in a GitHub Actions workflow

This project solves a specific CI problem. A GitHub Actions workflow often needs to call Google Cloud APIs, upload artifacts, create resources, or perform another operation that requires an authenticated Google Cloud principal. The workflow has a GitHub identity, while Google Cloud needs a configured way to recognize that identity or a credential that it accepts. google-github-actions/auth provides the bridge between those two systems.

The intended users are engineers and platform teams that already run GitHub Actions and use Google Cloud. The action is not a general Google Cloud client. It produces an authenticated environment or token output for later workflow steps. Its documentation identifies three authentication arrangements: direct Workload Identity Federation, Workload Identity Federation through a Service Account, and Service Account Key JSON.

Workload Identity Federation is the preferred path. The README explains that it avoids exporting a long-lived credential and creates a trust delegation relationship between a particular GitHub Actions workflow invocation and permissions in Google Cloud. That distinction matters for CI because a workflow credential can be tied to a run rather than treated as a reusable password. The action itself is not an officially supported Google product and is not covered by a Google Cloud support contract, so an adoption decision must account for that boundary.

Direct federation, impersonation, and JSON credentials

Direct Workload Identity Federation starts from GitHub Actions OIDC. The workflow grants the runner permission to obtain an ID token, then passes a complete `workload_identity_provider` identifier to the action. The identifier includes the Google Cloud project number, location, pool, and provider. For example, the documented shape is `projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider`.

When `service_account` is omitted, the README identifies the mode as Direct Workload Identity Federation. When that input is present, the action uses indirect federation through a Service Account. The service account is identified by an email address or unique identifier and is the principal for which credentials are generated. The optional `audience` input controls the `aud` value in the generated GitHub Actions OIDC token. It defaults to the full workload identity provider value, which is also the default audience Google Cloud expects.

The JSON key route uses `credentials_json`. Its documentation calls Service Account Key JSON credentials long-lived credentials that must be treated like a password. The action does not generate tokens by default. To request an OAuth 2.0 access token, the workflow supplies `token_format: "access_token"` and a `service_account`. Optional controls include `access_token_lifetime`, `access_token_scopes`, and `access_token_subject`. The documented default scope is `https://www.googleapis.com/auth/cloud-platform`. The default lifetime is one hour, with a maximum of one hour unless the named organization policy allows extension. Domain-Wide Delegation access tokens remain limited to one hour even when that policy is enabled.

A first GitHub Actions workflow using direct federation

The README does not describe installing this project as an application or package. It is consumed as a GitHub Action from the workflow, so the first real use is an authentication step in a workflow file. The checkout step must come first because later steps depend on the repository contents and future steps depend on authentication.

This is the documented direct federation example:

jobs:
  job_id:
    runs-on: ubuntu-latest
    permissions:
      contents: 'read'
      id-token: 'write'
    steps:
    - uses: 'actions/checkout@v7'

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

The workflow should run on a runner that supports Node 24 or newer, according to the README and `package.json`. The `id-token: 'write'` permission allows the workflow to request the GitHub OIDC token needed by the federation path. The `contents: 'read'` permission supports the checkout operation in this example. After the auth step succeeds, later steps can use the authenticated environment. The README gives no additional command for invoking a Google Cloud API, so the exact follow-up operation depends on the API being used.

Runtime outputs and the five-minute OIDC boundary

The action can be used to generate an OAuth 2.0 access token for later workflow steps, but token generation is opt-in. The required `token_format` value is `"access_token"`, and `service_account` identifies the service account for which the token is generated. This is useful when a later step needs a token value rather than credentials exported into the environment.

The documentation gives `access_token_lifetime` as a duration in seconds with a trailing `s`, such as `30s`. It also permits `access_token_scopes` as a comma-separated or newline-separated list. `access_token_subject` supports Domain-Wide Delegation by naming the user to impersonate. The documentation also states that the service account needs `roles/iam.serviceAccountTokenCreator` on itself when access or ID tokens are generated with Service Account Key JSON authentication.

There is a sharp lifetime boundary for Workload Identity Federation. The README says that the GitHub OIDC token expires in five minutes, and any derived credentials also expire in five minutes. A workflow that assumes a cached credential remains valid for a long CI job can therefore fail. This action is designed around short-lived run credentials rather than a persistent session. The README does not document an automatic renewal procedure, so long-running workflows need an application design that obtains fresh credentials or keeps its work within the documented lifetime.

Limits that can make the action the wrong fit

The most explicit compatibility warning concerns Firebase Admin SDK. The README says that Workload Identity Federation is not supported by Firebase Admin SDK and directs users to Service Account Key JSON authentication instead. That restriction removes the preferred credential model for workflows whose real dependency is Firebase Admin SDK.

There is a second limitation around command-line tools. The README specifically warns that `gsutil` will not use credentials exported by this action. It directs customers to use `gcloud storage` instead. A workflow built around `gsutil` should not assume that placing `google-github-actions/auth` before it will be sufficient.

The OIDC five-minute expiry creates a different class of failure. Authentication can succeed initially and still become unavailable later in a job. The README does not promise refresh behavior, retry behavior, or persistence of derived credentials. It also warns that Firebase Admin SDK federation is unsupported and that changing the workflow `permissions` block can remove default permissions. In other words, a workflow can be syntactically valid yet fail because its token permission, IAM roles, external SDK support, or chosen command does not align with the authentication mode.

Maintenance, licensing, and implementation shape

The repository is not archived. Its last push was on 2026-07-29, so there is a recent development signal, but that fact alone does not establish a release policy or support commitment. The repository includes `CHANGELOG.md`, `package.json`, source files under `src/`, tests under `tests/`, and bundled output under `dist/`. Its package version is `3.0.0`, and recent release entries include `v3.0.0` on 2025-08-28 and `v2.1.13` on 2025-08-28.

The action is written primarily in TypeScript. `package.json` defines `dist/main/index.js` as the package main entry and includes a build command using `ncc` for the main and post entry points. It requires Node `>= 24.x` and npm `>= 11.x` for package development. Those are repository implementation details, not separate requirements stated for consumers of every GitHub-hosted runner, but the README does require a runner supporting Node 24 or newer.

The license is Apache-2.0. That is the repository license declared in `package.json`, and the repository contains a `LICENSE` file. The project also states that it is not an officially supported Google product. Consumers therefore need to read the repository's Apache-2.0 terms and the workflow security model themselves rather than treating the project as a Google Cloud support contract.

Editorial conclusion

Adopt google-github-actions/auth when a GitHub Actions workflow needs controlled Google Cloud access and can configure a Workload Identity Provider. Do not choose it for Firebase Admin SDK federation, gsutil workflows, or organizations unable to manage Google Cloud IAM. Verify the runner supports Node 24, the checkout step appears before auth, the provider identifier is complete, and the required IAM permissions are granted before treating the workflow as ready.

Frequently asked questions

Official sources

1. google-github-actions/auth on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases