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

[cfstras]

trafficstars

Code of Conduct

• [X] 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[bot]]

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 :sparkles: Our team will provide feedback regarding the best next steps for this issue - thanks for your patience! 💛

[github-actions[bot]]

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

[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.

[nguyenalex836]

@joshmgross Thank you very much for the review! ✨

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

@cfstras Thanks again for raising this issue! I've added the help wanted label so that you, or anyone else, can make the above update to the doc 💛

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.

We'll go ahead and leave this example intact 🙇

[Muhammadwaheed78]

jobs: example_matrix: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-latest] version: [12, 14, 16] include: - os: windows-latest version: 17

[jsoref]

I don't think the proposal is really correct. It's also harmful as demonstrated by this repository itself (see below).

What's missing from that document is a Using a reusable action section which should be referenced as an alternative.

That section in turn needs a warning:

[!WARNING] If you use uses: my-org/other-repo/.github/actions/shared-action@main (a reusable workflow) instead of an action then anyone who would trigger the workflow (especially in forks, but quite likely not limited to forks) and doesn't have access to your my-org/other-repo repository (which I believe is only constrained by a top level on: ... condition) then they will encounter an unfixable error of this form:

Invalid workflow file: .github/workflows/moda-ci.yaml#L86 error parsing called workflow ".github/workflows/moda-ci.yaml" -> "github/internal-actions/.github/workflows/docker_security.yml@main" : workflow was not found. See https://docs.github.com/actions/learn-github-actions/reusing-workflows#access-to-reusable-workflows for more information.

It might be possible to avoid this structure by using a combination of a workflow_call with a jobs: / if: condition that guards against the user from tripping on the problem e.g. ${{ github.repository == 'github/docs-internal' }} and then have the on: workflow_call on the internal side be responsible for using the reusable workflow.

[joshmgross]

👋 @jsoref while your issue is valid, I would not expect a section on the docs for using a private action to mention reusable workflows. While they both use the uses syntax, they are entirely separate features.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_iduses would be a better section to document some of the pitfalls of using private or internal reusable workflows in a public repo.

[jsoref]

Indeed adding an additional section to this document isn't right, I don't think there's a clear explanation of a proposed fix.

I think the fix is adding another paragraph after:

Alternatively, use a GitHub App instead of a personal access token in order to ensure your workflow continues to run even if the personal access token owner leaves. For more information, see Making authenticated API requests with a GitHub App in a GitHub Actions workflow.

of the form:

Alternatively, in some cases a reusable workflow may be appropriate.

[jsoref]

@subatoi