document some of the pitfalls of using private or internal reusable workflows in a public repo

[jsoref]

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#jobsjob_iduses

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

Add a warning

Warning

If you use uses: my-org/other-repo/.github/actions/shared-action@main then anyone who would trigger the workflow (as determined by on: ... conditions) especially in forks, but quite likely not limited to forks and doesn't have access to your my-org/other-repo repository 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's possible to avoid this 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.

Additional information

• Misleading section "Example: Using an action inside a different private repository than the workflow" in "Workflow Syntax" #34562 (comment)
• Misleading section "Example: Using an action inside a different private repository than the workflow" in "Workflow Syntax" #34562 (comment)
• moda-ci.yaml triggers an error in forks for anyone who doesn't have access to github/docs-internal #35731

[nguyenalex836]

@jsoref 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! 💛

[playb33]

waiting for review
waiting for review Issue/PR is waiting for a writer's review

[github-actions]

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

[joshmgross]

If you use uses: my-org/other-repo/.github/actions/shared-action@main then anyone who would trigger the workflow (as determined by on: ... conditions) especially in forks, but quite likely not limited to forks and doesn't have access to your my-org/other-repo repository will encounter an unfixable error of this form:

This would only apply to forks of private and internal repositories right?

If the upstream repository is public, it wouldn't be able to use private or internal reusable workflows in the first replace - regardless of how access is configured.

Additionally, the if statements would not prevent this error as all reusable workflows are resolved when a run is queued which is before job-level if statements are evaluated.

[jsoref]

It happens to me for this repository on a regular basis:
https://github.com/jsoref/github-docs/actions/runs/12816687823

I naively assumed that the workflow works for githubers otherwise, why would they ship it?

In retrospect, that was naïve. There are 11 pages of runs of this specific workflow failing 💯% of the time:
https://github.com/github/docs/actions/workflows/moda-ci.yaml

And apparently, someone at GitHub got tired of the ❌ and manually disabled it.

@joshmgross if you're on the GitHub actions team, then maybe you can take the specific workflow as input to provide a way for githubers and everyone else to avoid this situation. It didn't occur to me that there was no way for this to work.

My understanding is that this repository is actually synced to another disconnected fork that's either private or internal. There are other ways to manage a disconnected fork where things like this aren't carried over to the public repositories, and there would be ways for a syncing tool to add a commit to delete the file if one didn't want to do something else. But... a way for public repositories in this position to not cause problems for downstream forks would be good. And, again, advice to people who do things like this to think about forks in public repositories.