doc: add troubleshooting section (#127)

This commit is contained in:
Seth Vargo 2022-02-03 03:19:28 -05:00 committed by GitHub
parent 5d9db97c33
commit b6d69ec4d4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 110 additions and 1 deletions

View File

@ -66,7 +66,7 @@ jobs:
Note that changing the `permissions` block may remove some default permissions.
See the [permissions documentation][github-perms] for more information.
See [Examples](#examples) for more examples.
See [Examples](#examples) for more examples. For help debugging common errors, see [Troubleshooting](docs/TROUBLESHOOTING.md)
## Inputs
@ -530,6 +530,7 @@ Terraform module to automate your infrastructure provisioning. See [examples](ht
Note: It can take **up to 5 minutes** from when you configure the Workload
Identity Pool mapping until the permissions are available.
## GitHub Token Format
Below is a sample GitHub Token for reference for attribute mappings. For a list of all

108
docs/TROUBLESHOOTING.md Normal file
View File

@ -0,0 +1,108 @@
# Troubleshooting
- When troubleshooting "permission denied" errors from `auth` for Workload
Identity, the first step is to ask the `auth` plugin to generate an OAuth
access token. Do this by adding `token_format: 'access_token'` to your YAML:
```yaml
- uses: 'google-github-actions/auth@v0'
with:
# ...
token_format: 'access_token'
```
If your workflow _succeeds_ after adding the step to generate an access
token, it means Workload Identity Federation is configured correctly and the
issue is in subsequent actions. You can remove the `token_format` from your
YAML. To further debug:
1. Look at the [debug logs][debug-logs] to see exactly which step is
failing. Ensure you are using the latest version of that GitHub Action.
1. Make sure you use `actions/checkout@v2` **before** the `auth` action in
your workflow.
1. If the failing action is from `google-github-action/*`, please file an
issue in the corresponding repository.
1. If the failing action is from an external action, please file an issue
against that repository. The `auth` action exports Google Application
Default Credentials (ADC). Ask the action author to ensure they are
processing ADC correctly and using the latest versions of the Google
client libraries. Please note that we do not have control over actions
outside of `google-github-actions`.
If your workflow _fails_ after adding the the step to generate an access
token, it likely means there is a misconfiguration with Workload Identity.
Here are some common sources of errors:
1. Look at the [debug logs][debug-logs] to see exactly which step is
failing. Ensure you are using the latest version of that GitHub Action.
1. Ensure the value for `workload_identity_provider` is the full _Provider_
name, **not** the _Pool_ name:
```diff
- projects/NUMBER/locations/global/workloadIdentityPools/POOL
+ projects/NUMBER/locations/global/workloadIdentityPools/POOL/providers/PROVIDER
```
1. Ensure you have created an **Attribute Mapping** for any **Attribute
Conditions** or **Service Account Impersonation** principals. You cannot
create an Attribute Condition unless you map that value from the
incoming GitHub OIDC token. You cannot grant permissions to impersonate
a Service Account on an attribute unless you map that value from the
incoming GitHub OIDC token.
1. Ensure you have waited at least 5 minutes between making changes to the
Workload Identity Pool and Workload Identity Provider. Changes to these
resources are eventually consistent.
- "The size of mapped attribute exceeds the 127 bytes limit." This error
indicates that the GitHub OIDC token had a claim that exceeded the maximum
allowed value of 127 bytes. In general, 1 byte = 1 character. This most
common reason this occurs is due to long repo names or long branch names.
**This is a limit imposed by Google Cloud IAM.** We have no control over
this value. It is documented [here][wif-byte-limit]. Please [file feedback
with the Google Cloud IAM team][iam-feedback]. The only mitigation is to use
shorter repo names or shorter branch names.
- The credentials file was bundled into my binary, container, or pull request!
By default, the `auth` action exports credentials to the current workspace
so that the credentials are automatically available to future steps and
Docker-based actions. The credentials file is automatically removed when the
job finishes.
This means, after `auth` completes, the workspace is dirty and contains a
credentials file. This means creating a pull request, compiling a binary, or
building a Docker container, will include said credential file. There are a
few ways to fix this issue:
- Re-order your steps. In most cases, you can re-order your steps such
that `auth` comes _after_ the "compilation" step:
```text
1. Checkout
2. Compile (e.g. "docker build", "go build", "git add")
3. Auth
4. Push
```
This ensures that no authentication data is present during artifact
creation.
- In situations where `auth` must occur before compilation, you can use
the output to exclude the credential:
```text
1. Checkout
2. Auth
3. Inject "${{ steps.auth.outputs.credentials_file_path }}" into ignore file (e.g. .gitignore, .dockerignore)
4. Compile (e.g. "docker build", "go build", "git add")
5. Push
```
[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