Don't hide Configuring GitHub authentication... section

google-github-actions / auth

A GitHub Action for authenticating to Google Cloud.

https://cloud.google.com/iam

Apache License 2.0

968 stars 207 forks source link

Don't hide Configuring GitHub authentication... section #377

Closed simonw closed 11 months ago

simonw commented 11 months ago

I've been scratching my head over this procedure for ages... and then today I finally spotted that the key information I needed was right here on this page, but because it was hid inside a <details><summary> collapsed element I'd never managed to find it before!

I suggest expanding this crucial information into a more visible section, so that people like me don't miss it in the future.

sethvargo commented 11 months ago

Hi @simonw - thank you for opening a PR. This was an intentional decision because:

There are three ways to configure authentication (Direct WIF, WIF via SA, and SAKE), and expanding each of those sections makes the README un-navigable. Your PR proposes expanding one section, but leaves the other two collapsed.
This project does not seek to be the authority on every possible configuration option for WIF on Google Cloud; the Google Cloud documentation. These sections are meant to provide a bare-bones example.
It used to be visible, but people complained because the README was too long and it was too easy to get lost among the different configuration options.

For these reasons, I won't be merging this PR. I'm open to emojis and font changes to make these drop-downs more obvious.

simonw commented 10 months ago

Maybe it's worth expanding this documentation to multiple pages, perhaps using GitHub Pages.

I'll be honest: I've been procrastinating on switching my GitHub actions workflows that deploy things to Cloud Run over to OIDC for over two years now, because I find the process of doing so too confusing!

I was pretty excited when I thought I might have finally found the missing clue hidden behind a "expand" link on this page!

sethvargo commented 10 months ago

Maybe it's worth expanding this documentation to multiple pages, perhaps using GitHub Pages.

As I said above, this GitHub repo does not seek to be the authority on how to configure WIF. The vast majority of the steps are not specific to GitHub Actions, which is why they are documented in the Google Cloud documentation.

The primary function of this repository is to provide the GitHub Action that exchanges a GitHub Actions OIDC token for a valid Google Cloud credential for use in future GitHub Actions workflow steps. If you have general feedback about the WIF process or documentation, it would be best to use the "Send feedback" button to direct it to the WIF team.

I was pretty excited when I thought I might have finally found the missing clue hidden behind a "expand" link on this page!

If you're still having trouble, our TROUBLESHOOTING guide might be able to help. If that doesn't, provide your GitHub Actions YAML file and debug logs, and we'll try to figure it out.