DEVPROD-13627 Add debug tips for github generated tokens (evergreen-c…

…i#8575)

docs/FAQ.md

@@ -59,3 +59,14 @@ A few things may cause this issue:
 ##### How can I use a generated token for private go modules?
 
 After using the github.generate_token command to generate a token, you can then use it in a global git config with something like `git config --global url."https://x-access-token:${generated_token}@github.com/".insteadOf https://github.com/`. Evergreen will reset the global git config at the end of tasks (or for task groups, after the all the tasks in the task group tasks have finished).
+
+##### My generated token isn't working, how do I figure out why?
+
+Below is a recommended order for debugging steps:
+
+- [Check if GitHub is down](https://www.githubstatus.com).
+- If your current setup involves multiple steps or scripts, create a task that isolates the problem by only generating a token and immediately using it to do the operation you are trying to do. You can model it after the example [here](Project-Configuration/Project-Commands#githubgenerate_token). If it works in this isolated setting, debug efforts can be focused on yaml syntax and [token lifespan and scope](Project-Configuration/Project-Commands#token-lifespan).
+- Double check the app permissions on the [project settings](Github-Integrations#dynamic-github-access-tokens) page to make sure that what you are trying to do is not restricted.
+- Double check the permissions you specified in your project yaml when [generating the token](Project-Configuration/Project-Commands#githubgenerate_token) to make sure that what you are trying to do is not restricted.
+- Use a script like [shell.exec](Project-Configuration/Project-Commands/shellexec) to print the length of the generated token to make sure it's not 0. If it is, delete your github app in [project settings](Github-Integrations#dynamic-github-access-tokens) and save it again to make sure that it was saved correctly. Make sure that you are saving github app ID or the github app key and not the Client ID.
+- Test your app outside of Evergreen by generating a token and then using that token with the operation that doesn't work to make sure that a token generated by your app is powerful enough. While this is not officially supported by Evergreen, [Zack created a helpful script](https://github.com/10gen/employees/tree/master/home/zackary.santana/utils/github_dynamic_tokens) that can be used to generate a token on your machine. If you fail at this step, read the [github documentation](https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28) to figure out what permissions are needed for the thing you are trying to do and check in with the team that created the github app for you to double check that your app has those permissions. You can see all the available permissions [here](https://github.com/settings/apps/new). If your app has the right permissions but your token can't do the operation you expect on your machine, you may need to reach out to github for support.