Misleading section "Example: Using an action inside a different private repository than the workflow" in "Workflow Syntax"

[cfstras]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#example-using-an-action-inside-a-different-private-repository-than-the-workflow

What part(s) of the article would you like to see updated?

The current example explains you must checkout the private repository and reference the action locally, which also necessitates setting up private access tokens as secrets.

However, after following Allowing access to components in an internal repository, the regular uses: {owner}/{repo}/{path}@{ref} seems to work just fine.
This is misleading and should be added as an example, or explained why this easier approach should not be used.

Additional information

No response

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[nguyenalex836]

@cfstras Thank you for raising this issue! I'll get this triaged for review ✨ Our team will provide feedback regarding the best next steps for this issue - thanks for your patience! 💛

[github-actions]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

[janbrasna]

Just a note — the article in question is about dotcom/FPT private repos, while the linked solution is GHE internal repo — which is not the same. Just in case it makes a difference in OP's case.

[cfstras]

Hi Jan, thanks for the clarification!
I had assumed we were still on a Pro/private plan, but you're right we have switched to GHE/internal repos.
It seems though that the same misleading section is present in the Enterprise Cloud variant of the docs page, and it doesn't make the distinction between private and internal repos:
https://docs.github.com/en/enterprise-cloud@latest/actions/writing-workflows/workflow-syntax-for-github-actions#example-using-an-action-inside-a-different-private-repository-than-the-workflow

Might be a good note to add, I wasn't aware that the difference between internal and private repos are of relevance here.

[janbrasna]

(Disclaimer: I'm not familiar with the particular rules for API/token access across internal repos inside the same org per se — I'm only leaving notes for the subject matter expert in triage to point to the slight difference of the OP description compared to the real issue.)

@cfstras Even for GHE version, the linked content is still right;) The real issue is that the distinction between private and internal repos is not pointed out there.

"Using an action inside a different private repository than the workflow" should be read as "Using an action from a different private repository" — i.e. only if the repository containing the intended action is private (!=internal). If the reusable action is in public, or internal (=visible to all in the org), then it doesn't matter what's the visibility of the repo referencing it.

publicA action can be used in publicB, privateX or internalN (save for some org policy allowing action sources etc.); internalA action can be used by all internalX or privateY from the same org (not sure about public repos from the same org tho) — only private (and perhaps internal when referenced from outside the org) need the explicit access mentioned in the article.

[janbrasna]

@cfstras Nope, sorry, now I see what you refer to. Indeed the "manual checkout" description is only useful when the private repository you need to reference is outside of your org/enterprise. For repos under the same owner, there's just the preference as you point out.

So basically for GHE, the FPT-centric wording is not enough — and should be expanded to cover the difference between same-owner (i.e. this config only needed) and out-of-enterprise private repos.

[cfstras]

Right, sorry, I'm coming completely from the "internal open-source" mindset here.

For our setup, the docs essentially sent me on a wild goose chase setting up PATs and using actions/checkout twice, when I should have just tried uses: my-org/other-repo/.github/actions/shared-action@main.

[joshmgross]

👋 Hello from Actions Engineering,

I agree this example in the docs is misleading, as it implies that it's the only way to use an action in a different private repository. This docs example predates Actions supporting private and internal actions as built-in feature.

We should update this section to point to the corresponding docs on using private and internal actions.

I see some value in keeping this example though - for example you can't use a private action from an internal or public repository, nor can you use it from a repository in a separate Enterprise account.