From acd8a2b487aa5d70b49f4e2abf6d881cdbeafe2b Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 8 Aug 2022 11:46:38 -0400 Subject: [PATCH] Document how GitHub secrets work (#208) Fixes #207 --- README.md | 8 ++++++++ docs/TROUBLESHOOTING.md | 21 +++++++++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/README.md b/README.md index 0f691e51..bb9d10a1 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,14 @@ risk.** service account, you must grant the underlying service account `roles/iam.serviceAccountTokenCreator` permissions on itself. + Note: we strongly advise that you "compress" your JSON into a single line + string before storing it in a GitHub Secret. When a GitHub Secret is used in + a GitHub Actions workflow, _each line_ of the secret is masked in log + output. This can lead to aggressive sanitization of benign characters like + curly braces (`{}`) and brackets (`[]`). See + [Troubleshooting](docs/TROUBLESHOOTING.md#aggressive-replacement) for more + information. + ### Generating OAuth 2.0 access tokens The following inputs are for _generating_ OAuth 2.0 access tokens for diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 341aa249..49b46862 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -161,9 +161,30 @@ ways to fix this issue: 5. Push ``` + + +## Aggressive *** replacement in logs + +When you use a [GitHub Actions secret][github-secrets] inside a workflow, _each_ +line of the secret is masked in log output. This is controlled by GitHub, not +the `auth` action. We cannot change this behavior. + +This can be problematic if your secret is a multi-line JSON string, since it +means curly braces (`{}`) and brackets (`[]`) will likely be replaced as `***` +in the GitHub Actions log output. To avoid this, remove all unnecessary +whitespace from the JSON and save the secret as a single-line JSON string. You +can convert a multi-line JSON document to a single-line manually or by using a +tool like `jq`: + +```sh +cat credentials.json | jq -r tostring +``` + + [attribute-conditions]: https://cloud.google.com/iam/docs/workload-identity-federation#conditions [sa-impersonation]: https://cloud.google.com/iam/docs/workload-identity-federation#impersonation [debug-logs]: https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging [iam-feedback]: https://cloud.google.com/iam/docs/getting-support [wif-byte-limit]: https://cloud.google.com/iam/docs/configuring-workload-identity-federation [cal]: https://cloud.google.com/logging/docs/audit/configure-data-access +[github-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets