From f80ec2b14713fdf232fd2679d93fa2fa918120ff Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Sun, 26 Dec 2021 16:17:49 -0500 Subject: [PATCH] docs: make it clearer that most auth inputs are deprecated (#459) --- README.md | 79 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 51 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index ca6e2697..40f5707f 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,3 @@ - - # `setup-gcloud` GitHub Action Configures the [Google Cloud SDK][sdk] in the GitHub Actions environment. The Google Cloud SDK includes both the [gcloud][gcloud] and @@ -19,7 +5,7 @@ Configures the [Google Cloud SDK][sdk] in the GitHub Actions environment. The Go Or integrate natively with other Google Cloud GitHub Actions: -* [Authenticate to Google Cloud](https://github.com/google-github-actions/auth) +* [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) @@ -33,7 +19,7 @@ Or integrate natively with other Google Cloud GitHub Actions: rename the branch to `main` in 2022 and this _will break_ existing workflows. See [Versioning](#versioning) for more information.** -- **Previously this repository contained the code for ALL of the GCP GithHub +- **Previously this repository contained the code for ALL of the GCP GitHub Actions. Now each action has it's own repo and this repo is only for `setup-gcloud`.** @@ -81,18 +67,52 @@ jobs: ## Inputs -| Name | Requirement | Default | Description | -| ------------- | ----------- | ------- | ----------- | -| `version` | _optional_ | `latest`| The version of the `gcloud` to be installed. Example: `290.0.1`| -| `project_id` | _optional_ | | ID of the Google Cloud Platform 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. | -| `service_account_email` | _optional_ | | Service account email address to use for authentication. This is required for legacy .p12 keys but can be omitted for JSON keys. This is usually of the format `@.iam.gserviceaccount.com`. | -| `export_default_credentials`| _optional_ |`false`| Exports the path to [Default Application Credentials][dac] as the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to be available in later steps. Google Cloud services automatically use this environment variable to find credentials. | -| `credentials_file_path` | _optional_ | (temporary file) | Only valid when `export_default_credentials` is `true`. Sets the path at which the credentials should be written. | -| `cleanup_credentials` | _optional_ | `true` | If true, the action will remove exported credentials from the filesystem upon completion. This only applies if `export_default_credentials` is true. | -| `service_account_key` | _optional_ | | (**Deprecated**) This input is deprecated. See [auth section](https://github.com/google-github-actions/setup-gcloud#authorization) for more details. The service account key which will be used for authentication credentials. This key should be [created](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) and stored as a [secret](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets). It can be encoded as a [Base64](https://en.wikipedia.org/wiki/Base64) string or as JSON. | +### Cloud SDK inputs + +- `version`: (Optional) A string representing the version of the Cloud SDK + (`gcloud`) to install (e.g. `"290.0.1"`). The default value is "latest", + which will install the latest available Cloud SDK version. + +- `project_id`: (Optional) Project ID (**not** project _number_) of the Google + Cloud project. If provided, this will configure the `gcloud` CLI to use that + project ID for commands. Individual commands can still override the project + with the `--project` flag. If unspecified, the action attempts to find the + "best" project ID by looking at other inputs and environment variables. + +### Authentication inputs + +**⚠️ Deprecated**: The following authentication inputs are deprecated and will +be removed in a future release. See [Authorization](#authorization) for more +information. + +- `service_account_key`: (**Deprecated**, optional) The Google Cloud service + account key JSON. This key should be created and stored as a GitHub secret. + It can be the raw JSON contents or a base64-encoded string of the raw JSON + contents. There is no default value. + +- `service_account_email`: (**Deprecated**, optional) Email address of the + service account to use for authentication. This is only required for p12 + service account keys, which are no longer recommended. This input is not + required if using a JSON service account key. There is no default value. + +- `export_default_credentials`: (**Deprecated**, optional) If true, the action + will write credentials to the filesystem and export the + `GOOGLE_APPLICATION_CREDENTIALS` environment variable for future steps to + consume [Application Default Credentials][adc]. The default value is false. + +- `credentials_file_path`: (**Deprecated**, optional) The path at which the + exported credentials should be written on disk. In order for the credentials + to be available for future steps, it must be in `$GITHUB_WORKSPACE` or + `$RUNNER_TEMP`. This is only valid when `export_default_credentials` is + true. The default value is a temporary file inside `$GITHUB_WORKSPACE`. + +- `cleanup_credentials`: (**Deprecated**, optional) If true, the action will + remove any generated credentials from the filesystem after all steps have + completed. This only applies if `export_default_credentials` is true. The + default value is true. -## Example Workflows +## Example workflows * [Google Kubernetes Engine](./example-workflows/gke/README.md): An example workflow that uses GitHub Actions to deploy a static website to an existing [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/) cluster. @@ -108,7 +128,9 @@ code to [App Engine](https://cloud.google.com/appengine), a fully managed server ## Authorization -This action installs the Cloud SDK (`gcloud`). To configure its authentication to Google Cloud, use the [google-github-actions/auth](https://github.com/google-github-actions/auth) action. You can authenticate via: +This action installs the Cloud SDK (`gcloud`). To configure its authentication +to Google Cloud, use the [google-github-actions/auth][auth] action. You can +authenticate via: ### Workload Identity Federation (preferred) @@ -201,7 +223,8 @@ See [LICENSE](LICENSE). [github-action]:https://help.github.com/en/categories/automating-your-workflow-with-github-actions -[dac]: https://cloud.google.com/docs/authentication/production +[auth]: https://github.com/google-github-actions/auth +[adc]: https://cloud.google.com/docs/authentication/production [sdk]: https://cloud.google.com/sdk/ [gcloud]: https://cloud.google.com/sdk/gcloud/ [gsutil]: https://cloud.google.com/storage/docs/gsutil