setup-gcloud can constrain the gcloud version you install

The version constraint is the real interface, not the boolean flags

This action's most consequential input is a version constraint, and the way it behaves is worth understanding before you add it to a workflow.

The `version` input is optional and defaults to `latest`, a string representing a version or version constraint of the Cloud SDK to install, with examples given as `"290.0.1"` or `">= 197.0.1"`. The documented behaviour: if there is no installed `gcloud` version that matches the given constraint, the action downloads and installs the latest available version that still matches the constraint.

Read that carefully, because it is a two-step decision. The action first looks at what is already installed. Only if nothing matches does it download. So on a runner image where a suitable SDK is already present, pinning a constraint costs nothing, and on one where it is not, you get a download rather than a silent mismatch.

Two version floors then follow from features rather than from preference. Authenticating via Workload Identity Federation requires version 363.0.0 or newer. And there is a separate warning attached specifically to BigQuery: you must use Cloud SDK version 390.0.0 or later to authenticate the `bq` tool.

This is a separate requirement for workflows that need to authenticate the `bq` tool.

The README closes the input description by saying you are responsible for ensuring the `gcloud` version matches the features and components required. That is an explicit handover of responsibility, not a courtesy.

Authentication is a separate action, and the ordering is the contract

setup-gcloud installs the Cloud SDK. It does not authenticate to Google Cloud, and the README is explicit about how the two halves fit.

To configure authentication you must first use the google-github-actions/auth action. The auth action sets Application Default Credentials, and then setup-gcloud references those credentials to configure gcloud credentials.

In the documented authentication workflows, auth comes before setup-gcloud:

steps:
- id: 'auth'
  uses: 'google-github-actions/auth@v2'
  with:
    workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
    service_account: '[email protected]'

- name: 'Set up Cloud SDK'
  uses: 'google-github-actions/setup-gcloud@v3'
  with:
    version: '>= 363.0.0'

The `permissions` block matters as much as the steps, because the job needs the id-token permission to mint a token:

permissions:
  contents: 'read'
  id-token: 'write'

Two of the three documented authentication routes are visible in full. Workload Identity Federation is marked preferred, and uses a workload identity provider and a service account. Service Account Key JSON passes `credentials_json` from a secret. And for self-hosted runners hosted on Google Cloud Platform, credentials are obtained automatically from the service account attached to the runner, so in that case you do not need to run the auth action at all.

That last case is a genuine convenience and the reason to consider self-hosted runners on GCP at all: no key material and no token plumbing in the workflow.

Four optional inputs, and skip_install takes away the component manager

Beyond `version`, there are four optional inputs, and two of them have consequences that are not obvious from their names.

`project_id` configures gcloud to use that project by default for commands. Individual commands can still override it with the `--project` flag, which takes precedence. If unspecified, the action attempts to find the best project ID by looking at other inputs and environment variables, which is a heuristic and worth pinning explicitly if you care about determinism.

`install_components` takes a comma-separated list of additional gcloud components:

install_components: 'alpha,cloud-datastore-emulator'

`skip_install` uses the system-supplied version from the runner image instead, and the `version` input is then ignored. The warning attached to it is the important part: you will not be able to install additional gcloud components, because the system installation is locked.

That couples the two inputs. If you set `skip_install` you have also forfeited `install_components`, whether or not you set it.

`cache` transfers the downloaded artefacts into the runner's tool cache. The README is refreshingly specific about when that helps: on GitHub-managed runners it has very little impact since runners are ephemeral, while on self-hosted runners it could improve future runs by skipping future gcloud installations.

So `cache` is the input whose value depends entirely on your runner type. If you are on GitHub-hosted runners it is close to a no-op; if you run self-hosted, it converts a per-run download into a one-time download.

The single output is `version`, the version of gcloud that was installed, which is what you read in a later step if you need to assert on it.

Node 24 and the self-hosted runner floor

The prerequisites section is short and one line of it has a hard consequence.

The action requires Google Cloud credentials to execute gcloud commands, which points back at the auth action. Then it states that this action runs using Node 24, and that if you are using self-hosted GitHub Actions runners you must use a runner version that supports this version or newer.

That is the constraint to check first if you have self-hosted runners.

The `package.json` confirms the floor from the other direction. The engines block requires Node `>= 24.x` and npm `>= 11.x`, and the development dependencies include `@types/node` at `^24.3.0`.

The runtime matters because a JavaScript GitHub Action runs inside the runner's Node process rather than in a container, so the runner provides the runtime. That also explains the `dist/` directory at the repository root and the build script.

The build is `ncc build -m src/main.ts`, using `@vercel/ncc`. The `dist/` directory being committed rather than generated in CI is the standard pattern for JavaScript actions, because GitHub runs the checked-in bundle rather than building anything.

Autogenerated documentation and a family of sibling actions

Two details about how this repository is maintained are visible from the file layout.

The first is that the inputs and outputs sections of the README are generated. They sit between `BEGIN_AUTOGEN_INPUTS` and `END_AUTOGEN_INPUTS` markers, with the same pattern for outputs, and every generated entry carries an anchor name and a user-content link. The `package.json` has a `docs` script that runs `actions-gen-readme` from `node_modules/.bin`, so the README is regenerated rather than hand-edited. That is why the formatting of those sections is uniform to the point of being mechanical.

The second is that this action is one node in a set. The README lists siblings for authenticating to Google Cloud, deploying a Cloud Run service, deploying an App Engine app, deploying a Cloud Function, accessing Secret Manager secrets, uploading to Cloud Storage and configuring GKE credentials. Those links all point into the same `google-github-actions` organisation.

The README presents these actions as related options for authentication, deployment, secrets, storage and GKE credentials.

The repository layout matches a maintained Google project: `src/` for TypeScript source, `dist/` for the committed bundle, `tests/` split into `setup-gcloud.test.ts` and `integration.test.ts`, `eslint.config.mjs` for linting with ESLint 9 flat config, `CODEOWNERS`, and a `CHANGELOG.md`.

What it is not, and the support boundary Google draws

The README opens with a disclaimer that belongs in your risk assessment rather than at the bottom of a document.

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, you are directed to contact Google Cloud support.

That is a narrower commitment than the code quality suggests. The repository is maintained by GoogleCloudPlatform as the package author, follows the conventions of a well-run open source project, and is under Apache-2.0 with a LICENSE file at the root. None of that changes the support boundary: if the SDK changes under you or the action breaks in a way that blocks a release, you file an issue on GitHub, not a Google Cloud support case.

There is a second, smaller boundary about what the action does not decide. It installs a CLI and configures credentials. It does not decide what your workflow should do, and the README's inputs documentation says outright that you are responsible for ensuring the `gcloud` version matches the features and components required. If your job needs a component you forgot to install, or a version that does not support it, the failure is yours to trace.

Where this sits on maintenance: the last push was on 2026-04-07, and the three most recent release tags are v3.0.1 and v3 on 2025-08-28 and v3.0.0 on 2025-08-25. So the v3 major and its patches are settled, and the reference to `google-github-actions/setup-gcloud@v3` in the usage examples is the line you should track.

Editorial conclusion

Adopt setup-gcloud if your workflows need the gcloud CLI and you want the SDK version chosen by constraint rather than by whatever the runner image happens to ship. Do not adopt it expecting Google Cloud support, since the README states plainly that this is not an officially supported Google product and is not covered by a support contract. Verify first that your version constraint is at least 363.0.0 if you authenticate with Workload Identity Federation, 390.0.0 if you use the `bq` tool, and that your self-hosted runners support Node 24, since that is the runtime the action needs.

Frequently asked questions

Official sources

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