Skip to content

Commit

Permalink
Use new markdown syntax for alerts (#371)
Browse files Browse the repository at this point in the history
  • Loading branch information
@sethvargo
sethvargo committed Dec 18, 2023
1 parent 5f7afaa commit 56562dd
Show file tree
Hide file tree
Showing 3 changed files with 70 additions and 42 deletions.
65 changes: 40 additions & 25 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.


<a name="direct-wif" id="direct-wif"></a>
Expand All @@ -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.
Expand Down Expand Up @@ -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:

Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
21 changes: 13 additions & 8 deletions docs/EXAMPLES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
26 changes: 17 additions & 9 deletions docs/TROUBLESHOOTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.

Expand Down

0 comments on commit 56562dd

Please sign in to comment.