From 56562ddf6ace6336b8df0ea82133bdb6aab40121 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 18 Dec 2023 14:06:39 -0500 Subject: [PATCH] Use new markdown syntax for alerts (#371) --- README.md | 65 +++++++++++++++++++++++++---------------- docs/EXAMPLES.md | 21 ++++++++----- docs/TROUBLESHOOTING.md | 26 +++++++++++------ 3 files changed, 70 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 6b630d2..780b0dd 100644 --- a/README.md +++ b/README.md @@ -62,9 +62,10 @@ jobs: 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][github-perms] for more -> information. +> [!NOTE] +> +> Changing the `permissions` block may remove some default permissions. See the +> [permissions documentation][github-perms] for more information. For more usage options, see the [examples](docs/EXAMPLES.md). @@ -73,9 +74,11 @@ For more usage options, see the [examples](docs/EXAMPLES.md). ### Inputs: Workload Identity Federation -> **⚠️ WARNING!** This option is [not supported by Firebase Admin -> SDK](https://github.com/firebase/firebase-admin-node/issues/1377). Use -> Service Account Key JSON authentication instead. +> [!WARNING] +> +> This option is [not supported by Firebase Admin +> SDK](https://github.com/firebase/firebase-admin-node/issues/1377). Use Service +> Account Key JSON authentication instead. The following inputs are for _authenticating_ to Google Cloud via Workload Identity Federation. @@ -108,8 +111,10 @@ Identity Federation. ### Inputs: Service Account Key JSON -> **⚠️ WARNING!** Service Account Key JSON credentials are long-lived -> credentials and must be treated like a password. +> [!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. @@ -319,10 +324,12 @@ This section describes the three configuration options: 1. [Workload Identity Federation through a Service Account](#indirect-wif) 1. [Service Account Key JSON](#sake) -> **⚠️ NOTE!** 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](docs/TROUBLESHOOTING.md) -> before opening an issue. +> [!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](docs/TROUBLESHOOTING.md) before opening +> an issue. @@ -337,8 +344,10 @@ information. [![Authenticate to Google Cloud from GitHub Actions with Direct Workload Identity Federation](docs/google-github-actions-auth-direct-workload-identity-federation.svg)](docs/google-github-actions-auth-direct-workload-identity-federation.svg) -> **⚠️ NOTE!** To generate OAuth 2.0 access tokens or ID tokens, you _must_ -> provide a service account email, and the Workload Identity Pool must have +> [!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. @@ -389,9 +398,10 @@ These instructions use the [gcloud][gcloud] command-line tool. the principal invoking the GitHub Action). These can be used to further restrict the authentication using `--attribute-condition` flags. - > **❗️ NOTE!** You must map any claims in the incoming token to attributes - > before you can assert on those attributes in a CEL expression or IAM - > policy!** + > [!IMPORTANT] + > + > You must map any claims in the incoming token to attributes before you can + > assert on those attributes in a CEL expression or IAM policy! 1. Extract the Workload Identity **Provider** resource name: @@ -413,10 +423,12 @@ These instructions use the [gcloud][gcloud] command-line tool. workload_identity_provider: '...' # "projects/123456789/locations/global/workloadIdentityPools/github/providers/my-repo" ``` - > **⚠️ NOTE!** The `project_id` input is optional, but may be required by - > downstream authentication systems such as the `gcloud` CLI. Unfortunately - > we cannot extract the project ID from the Workload Identity Provider, - > since it requires the project _number_. + > [!IMPORTANT] + > + > The `project_id` input is optional, but may be required by downstream + > authentication systems such as the `gcloud` CLI. Unfortunately we cannot + > extract the project ID from the Workload Identity Provider, since it + > requires the project _number_. > > It is technically possible to convert a project _number_ into a project > _ID_, but it requires permissions to call Cloud Resource Manager, and we @@ -512,9 +524,10 @@ These instructions use the [gcloud][gcloud] command-line tool. the principal invoking the GitHub Action). These can be used to further restrict the authentication using `--attribute-condition` flags. - > **❗️ NOTE!** You must map any claims in the incoming token to attributes - > before you can assert on those attributes in a CEL expression or IAM - > policy!** + > [!IMPORTANT] + > + > You must map any claims in the incoming token to attributes before you can + > assert on those attributes in a CEL expression or IAM policy!** 1. Allow authentications from the Workload Identity Pool to your Google Cloud Service Account. @@ -576,7 +589,9 @@ as a secret. [![Authenticate to Google Cloud from GitHub Actions with a Service Account Key](docs/google-github-actions-auth-service-account-key-export.svg)](docs/google-github-actions-auth-service-account-key-export.svg) -> **❗️ WARNING!** Google Cloud Service Account Key JSON files must be secured +> [!CAUTION] +> +> Google Cloud Service Account Key JSON files must be secured > and treated like a password. Anyone with acess 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 diff --git a/docs/EXAMPLES.md b/docs/EXAMPLES.md index 83726a8..145cb67 100644 --- a/docs/EXAMPLES.md +++ b/docs/EXAMPLES.md @@ -114,13 +114,16 @@ jobs: This example demonstrates using this GitHub Action to generate an OAuth 2.0 Access Token for authenticating to Google Cloud. -> **⚠️ NOTE!** The default lifetime is 1 hour, but you can request up to 12 -> hours if you set the -> [`constraints/iam.allowServiceAccountCredentialLifetimeExtension` organization -> policy][orgpolicy-creds-lifetime]. +> [!NOTE] +> +> The default lifetime is 1 hour, but you can request up to 12 hours if you set +> the [`constraints/iam.allowServiceAccountCredentialLifetimeExtension` +> organization policy][orgpolicy-creds-lifetime]. -> **⚠️ NOTE!** If you authenticate via `credentials_json`, the service account -> must have `roles/iam.serviceAccountTokenCreator` on itself. +> [!IMPORTANT] +> +> If you authenticate via `credentials_json`, the service account must have +> `roles/iam.serviceAccountTokenCreator` on itself. ```yaml jobs: @@ -154,8 +157,10 @@ This example demonstrates using this GitHub Action to generate a Google Cloud ID Token for authenticating to Google Cloud. This is commonly used when invoking a Cloud Run service. -> **⚠️ NOTE!** If you authenticate via `credentials_json`, the service account -> must have `roles/iam.serviceAccountTokenCreator` on itself. +> [!IMPORTANT] +> +> If you authenticate via `credentials_json`, the service account must have +> `roles/iam.serviceAccountTokenCreator` on itself. ```yaml jobs: diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 8f5e47c..27f022f 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -6,7 +6,9 @@ see exactly which step is failing. Ensure you are using the latest version of the GitHub Action. - > **❗️ WARNING!** Enabling debug logging increases the chances of a secret + > [!CAUTION] + > + > Enabling debug logging increases the chances of a secret > being accidentially logged. While GitHub Actions will scrub secrets, > please take extra caution when sharing these debug logs in publicly > accessible places like GitHub issues. @@ -62,9 +64,11 @@ GitHub OIDC token. You cannot grant permissions on an attribute unless you map that value from the incoming GitHub OIDC token. - > **📝 TIP!** Use the [GitHub Actions OIDC Debugger][oidc-debugger] to print - > the list of token claims and compare them to your Attribute Mappings and - > Attribute Conditions. + > [!TIP] + > + > Use the [GitHub Actions OIDC Debugger][oidc-debugger] to print the list of + > token claims and compare them to your Attribute Mappings and Attribute + > Conditions. 1. Ensure you have the correct character casing and capitalization. GitHub does not distinguish between "foobar" and "FooBar", but Google Cloud does. Ensure @@ -85,8 +89,10 @@ 1. Enable `Admin Read`, `Data Read`, and `Data Write` [Audit Logging][cal] for Identity and Access Management (IAM) in your Google Cloud project. - > **❗️ WARNING!** This will increase log volume which may increase costs. - > You can disable this audit logging after you have debugged the issue. + > [!WARNING] + > + > This will increase log volume which may increase costs. You can disable + > this audit logging after you have debugged the issue. Try to authenticate again, and then explore the logs for your Workload Identity Provider and Workload Identity Pool. Sometimes these error messages @@ -98,8 +104,8 @@ processing ADC correctly and using the latest versions of the Google client libraries. - > **⚠️ NOTE!** We do not have control over GitHub Actions outside of the - > `google-github-actions` GitHub organization. + **We do not have control over GitHub Actions outside of the + `google-github-actions` GitHub organization.** ## Subject exceeds the 127 byte limit @@ -232,7 +238,9 @@ cat credentials.json | jq -r tostring ## Organizational Policy Constraints -> **⚠️ NOTE!** Your Google Cloud organization administrator controls these +> [!NOTE] +> +> Your Google Cloud organization administrator controls these > policies. You must work with your internal IT department to resolve OrgPolicy > violations and constraints.