google-github-actions/setup-gcloud
1
0
Fork 0
mirror of https://github.com/google-github-actions/setup-gcloud.git synced 2026-08-20 17:24:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
setup-gcloud/README.md
gurusai-voleti 01af06c41d
chore: Migrate gsutil usage to gcloud storage (#733) 
Automated: Migrate {target_path} from gsutil to gcloud storage

This CL is part of the on going effort to migrate from the legacy
`gsutil` tool to the new and improved `gcloud storage` command-line
interface.
`gcloud storage` is the recommended and modern tool for interacting with
Google Cloud Storage, offering better performance, unified
authentication, and a more consistent command structure with other
`gcloud` components. 🚀

### Automation Details

This change was **generated automatically** by an agent that targets
users of `gsutil`.
The transformations applied are based on the [gsutil to gcloud storage
migration guide](http://go/gsutil-gcloud-storage-migration-guide).

### ⚠️ Action Required: Please Review and Test Carefully

While we have based the automation on the migration guide, every use
case is unique.
**It is crucial that you thoroughly test these changes in environments
appropriate to your use-case before merging.**
Be aware of potential differences between `gsutil` and `gcloud storage`
that could impact your workflows.
For instance, the structure of command output may have changed,
requiring updates to any scripts that parse it. Similarly, command
behavior can differ subtly; the `gcloud storage rsync` command has a
different file deletion logic than `gsutil rsync`, which could lead to
unintended file deletions.

Our migration guides can help guide you through a list of mappings and
some notable differences between the two tools.

Standard presubmit tests are run as part of this CL's workflow. **If you
need to target an additional test workflow or require assistance with
testing, please let us know.**

Please verify that all your Cloud Storage operations continue to work as
expected to avoid any potential disruptions in production.

### Support and Collaboration

The `GCS CLI` team is here to help! If you encounter any issues, have a
complex use case that this automated change doesn't cover, or face any
other blockers, please don't hesitate to reach out.
We are happy to work with you to test and adjust these changes as
needed.

**Contact:** `gcs-cli-hyd@google.com`

We appreciate your partnership in this important migration effort!

#gsutil-migration

Signed-off-by: gurusai-voleti <gvoleti@google.com>
2026-04-07 15:12:47 -04:00

264 lines
9.6 KiB
Markdown
Raw Permalink Blame History

# `setup-gcloud` GitHub Action
Configures the [Google Cloud SDK][sdk] in the GitHub Actions environment. The Google Cloud SDK includes the [gcloud][gcloud] binary.
Or integrate natively with other Google Cloud GitHub Actions:
* [Authenticate to Google Cloud][auth]
* [Deploy a Cloud Run service](https://github.com/google-github-actions/deploy-cloudrun)
* [Deploy an App Engine app](https://github.com/google-github-actions/deploy-appengine)
* [Deploy a Cloud Function](https://github.com/google-github-actions/deploy-cloud-functions)
* [Access Secret Manager secrets](https://github.com/google-github-actions/get-secretmanager-secrets)
* [Upload to Cloud Storage](https://github.com/google-github-actions/upload-cloud-storage)
* [Configure GKE credentials](https://github.com/google-github-actions/get-gke-credentials)
**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](https://cloud.google.com/support).**
## Prerequisites
- This action requires Google Cloud credentials to execute gcloud commands.
See [Authorization](#Authorization) for more details.
- This action runs using Node 24. If you are using self-hosted GitHub Actions
runners, you must use a [runner
version](https://github.com/actions/virtual-environments) that supports this
version or newer.
## Usage
```yaml
jobs:
job_id:
# Add "id-token" with the intended permissions.
permissions:
contents: 'read'
id-token: 'write'
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: 'my-service-account@my-project.iam.gserviceaccount.com'
- name: 'Set up Cloud SDK'
uses: 'google-github-actions/setup-gcloud@v3'
with:
version: '>= 363.0.0'
- name: 'Use gcloud CLI'
run: 'gcloud info'
```
## Inputs
<!-- BEGIN_AUTOGEN_INPUTS -->
- <a name="__input_version"></a><a href="#user-content-__input_version"><code>version</code></a>: _(Optional, default: `latest`)_ A string representing the version or version constraint of the Cloud SDK
(`gcloud`) to install (e.g. `"290.0.1"` or `">= 197.0.1"`). The default
value is `"latest"`, which will always download and install the latest
available Cloud SDK version.
- uses: 'google-github-actions/setup-gcloud@v3'
with:
version: '>= 416.0.0'
If there is no installed `gcloud` version that matches the given
constraint, this GitHub Action will download and install the latest
available version that still matches the constraint.
Authenticating via Workload Identity Federation requires version
[363.0.0](https://cloud.google.com/sdk/docs/release-notes#36300_2021-11-02)
or newer. If you need support for Workload Identity Federation, specify
your version constraint as such:
- uses: 'google-github-actions/setup-gcloud@v3'
with:
version: '>= 363.0.0'
You are responsible for ensuring the `gcloud` version matches the features
and components required.
- <a name="__input_project_id"></a><a href="#user-content-__input_project_id"><code>project_id</code></a>: _(Optional)_ ID of the Google Cloud project. If provided, this will configure gcloud to
use this project ID by default for commands. Individual commands can still
override the project using 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.
- <a name="__input_install_components"></a><a href="#user-content-__input_install_components"><code>install_components</code></a>: _(Optional)_ List of additional [gcloud
components](https://cloud.google.com/sdk/docs/components) to install,
specified as a comma-separated list of strings:
install_components: 'alpha,cloud-datastore-emulator'
- <a name="__input_skip_install"></a><a href="#user-content-__input_skip_install"><code>skip_install</code></a>: _(Optional)_ Skip installation of gcloud and use the [system-supplied
version](https://github.com/actions/runner-images) instead. If specified,
the `version` input is ignored.
⚠️ You will not be able to install additional gcloud components, because the
system installation is locked.
- <a name="__input_cache"></a><a href="#user-content-__input_cache"><code>cache</code></a>: _(Optional)_ Transfer the downloaded artifacts into the runner's tool cache. On
GitHub-managed runners, this have very little impact since runneres are
ephemeral. On self-hosted runners, this could improve future runs by
skipping future gcloud installations.
<!-- END_AUTOGEN_INPUTS -->
## Outputs
<!-- BEGIN_AUTOGEN_OUTPUTS -->
- <a name="__output_version"></a><a href="#user-content-__output_version"><code>version</code></a>: Version of gcloud that was installed.
<!-- END_AUTOGEN_OUTPUTS -->
## Authorization
The `setup-gcloud` action installs the Cloud SDK (`gcloud`). To configure its authentication
to Google Cloud, you must first use the [google-github-actions/auth][auth] action. The `auth`
action sets [Application Default Credentials][adc], then the `setup-gcloud` action references
these credentials to configure [gcloud credentials][gcloud-credentials] . You can
authenticate via the following options:
### Workload Identity Federation (preferred)
**⚠️ You must use the Cloud SDK version 390.0.0 or later to authenticate the
`bq` tool.**
```yaml
jobs:
job_id:
# Add "id-token" with the intended permissions.
permissions:
contents: 'read'
id-token: 'write'
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: 'my-service-account@my-project.iam.gserviceaccount.com'
- name: 'Set up Cloud SDK'
uses: 'google-github-actions/setup-gcloud@v3'
- name: 'Use gcloud CLI'
run: 'gcloud info'
```
### Service Account Key JSON
```yaml
jobs:
job_id:
steps:
- id: 'auth'
uses: 'google-github-actions/auth@v2'
with:
credentials_json: '${{ secrets.GCP_CREDENTIALS }}'
- name: 'Set up Cloud SDK'
uses: 'google-github-actions/setup-gcloud@v3'
- name: 'Use gcloud CLI'
run: 'gcloud info'
```
### Self-hosted runners on Google Cloud Platform
If you are using self-hosted runners that are hosted on Google Cloud Platform, credentials
are automatically obtained from the service account attached to the runner.
In this scenario, you do not need to run the [google-github-actions/auth][auth] action.
```yaml
jobs:
job_id:
steps:
- name: 'Set up Cloud SDK'
uses: 'google-github-actions/setup-gcloud@v3'
- name: 'Use gcloud CLI'
run: 'gcloud info'
```
### Multiple Service Accounts
To use multiple service accounts, a second auth step is required to update the credentials before using `setup-gcloud`:
```yaml
jobs:
job_id:
# Add "id-token" with the intended permissions.
permissions:
contents: 'read'
id-token: 'write'
steps:
- id: 'auth service account 1'
uses: 'google-github-actions/auth@v2'
with:
workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
service_account: 'service-account-1@my-project.iam.gserviceaccount.com'
- name: 'Set up Cloud SDK'
uses: 'google-github-actions/setup-gcloud@v3'
- name: 'Use gcloud CLI'
run: 'gcloud auth list --filter=status:ACTIVE --format="value(account)"'
# service-account-1@my-project.iam.gserviceaccount.com
- id: 'auth service account 2'
uses: 'google-github-actions/auth@v2'
with:
credentials_json: '${{ secrets.GCP_CREDENTIALS }}'
- name: 'Set up Cloud SDK'
uses: 'google-github-actions/setup-gcloud@v3'
- name: 'Use gcloud CLI'
run: 'gcloud auth list --filter=status:ACTIVE --format="value(account)"'
# service-account-2@my-project.iam.gserviceaccount.com
```
## Versioning
We recommend pinning to the latest available major version:
```yaml
- uses: 'google-github-actions/setup-gcloud@v3'
```
While this action attempts to follow semantic versioning, but we're ultimately
human and sometimes make mistakes. To prevent accidental breaking changes, you
can also pin to a specific version:
```yaml
- uses: 'google-github-actions/setup-gcloud@v3.0.0'
```
However, you will not get automatic security updates or new features without
explicitly updating your version number. Note that we only publish `MAJOR` and
`MAJOR.MINOR.PATCH` versions. There is **not** a floating alias for
`MAJOR.MINOR`.
[github-action]:https://help.github.com/en/categories/automating-your-workflow-with-github-actions
[auth]: https://github.com/google-github-actions/auth
[adc]: https://cloud.google.com/docs/authentication/application-default-credentials
[sdk]: https://cloud.google.com/sdk/
[gcloud]: https://cloud.google.com/sdk/gcloud/
[gcloud-credentials]: https://cloud.google.com/docs/authentication/gcloud#gcloud-credentials
[sa-iam-docs]: https://cloud.google.com/iam/docs/service-accounts
[sa]: https://cloud.google.com/iam/docs/creating-managing-service-accounts
[wif]: https://cloud.google.com/iam/docs/workload-identity-federation
[github-runners]: https://github.com/actions/runner-images
[gcloud-release-notes]: https://cloud.google.com/sdk/docs/release-notes
Reference in a new issue View git blame Copy permalink