Documentation missing key point

This issue has been tracked since 2022-12-05.


IIUC self-hosted runners on some GCP compute environment most likely do not need to use workload identiy right? We use the standard setup-gcloud and then gcloud auth list and gcloud auth print-access-token WAI.

Expected behavior

If my understanding is correct can we add a critical sentence or two to this repo's

Observed behavior

No response

Action YAML

No yaml

Log output

No response

Additional information

No response

github-actions[bot] wrote this answer on 2023-01-02

Hi there @joshgc 👋!

Thank you for opening an issue. Our team will triage this as soon as we can. Please take a moment to review the troubleshooting steps which lists common error messages and their resolution steps.

sethvargo wrote this answer on 2023-01-02

Hi @joshgc

If you are running on compute environments* with self-hosted runners, you do not need this action at all. All the other google-github-actions will automatically detect and use the underlying service account identity for authentication. This is documented in the README's of those projects (e.g. setup-gcloud).

* If you are running on GKE, you will need to enable the Workload Identity feature (not to be confused with Workload Identity Federation), which allows you to map K8S service accounts to GCP service accounts.

joshgc wrote this answer on 2023-01-02

I appreciate your understanding of the docs Seth. But thats not how the google search results for "get gcloud on gha to work" understand the doc structure. This is a top hit, that both me and my SWE manager landed on. And we're both experienced GCP users and we both spent an hour trying to follow these instructions before we went "oh duh this is all not needed".

What does it cost to add a sentence that says "This approach probably is not needed if you're using self-hosted runners on a GCP environment". The doc as it stands comes across as definitive: "Workload Identity Federation is the recommended approach" lacks any conditionals and it lacks any references to the parent documentation that contains the caveat you mentioned in this issue before closing it.

sethvargo wrote this answer on 2023-01-02

Hi @joshgc - it's more nuanced than that. The reason it's documented in the associated READMEs is that not all things support Application Default Credentials discovery (and therefore do not detect the metadata server information when using self-hosted runners on GCP).

Furthermore, while you don't need to use this action for self-hosted runners, there are use cases where you might want to use it. For example, the default machine service account might have no permissions on GCP and then rely on WIF to elevate privilege based on workflow attributes. The self-hosted runners could be in a different GCP project with domain-restricted sharing or VPC service controls. The self-hosted runners could be on another cloud provider.

It's incorrect to say that this GitHub Action is mutually exclusive with self-hosted runners. The decision is extremely nuanced and requires information about the installation environment. Self-hosted runners represent an extremely small fraction of the customer base and also correspond to the most advanced use cases. I'm not supportive of putting references to these advanced use cases in a general-purpose README and risk losing or misleading readers down an unnecessary path. The cost is non-zero, and we don't want users to go on a 50 minute detour reading about self-hosted runners when they land on our README.

More Details About Repo
Owner Name google-github-actions
Repo Name auth
Full Name google-github-actions/auth
Language TypeScript
Created Date 2021-09-16
Updated Date 2023-03-24
Star Count 573
Watcher Count 16
Fork Count 116
Issue Count 3


Issue Title Created Date Updated Date