`runs.pre` should mention that it doesn't work from local actions or when called from other actions called from local actions

[jsoref]

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://github.com/github/docs/blob/main/content/actions/creating-actions/metadata-syntax-for-github-actions.md#runspre

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

runs.pre should include a paragraph explaining availability caveats.

It should mention:

1. pre doesn't work from local actions
2. If you create an action that will be used by other actions that might in turn be used by local actions, you'll trigger warnings in all workflows that use that action.
3. that better practice involves creating a secondary action containing the pre phase so it can optionally be used at the discretion of consumer actions/workflows.

Additional information

• @zijchen opened an issue in https://github.com/actions/typescript-action/issues/564 and referenced this documentation.
• @ncalteen struggled to explain the problem to the various people who complained about the confusing behavior.

Documentation here would have helped since at least @zijchen would have known that it wasn't going to work.

Documentation here might have also discouraged people from adding pre to actions.

Instead, the right behavior which should be recommended in resolving this ticket is to provide a second action in the same repository responsible for the pre behavior.

Thus, instead of @MoChilia in https://github.com/Azure/login/pull/384 changing azure/login to have a pre thing which triggers warnings as noted in https://github.com/actions/runner/issues/3397, @MoChilia could have created azure/login/clear-credentials which does the work that's currently included in pre. Then users could do:

• uses: azure/login/clear-credentials@...
• uses: azure/login@...
• uses: azure/login@...

And groups like microsoft/playwright could uses: azure/login@... without triggering dozens of warnings.

Fwiw. I'm pretty sure I've run across other repositories causing similar headaches in the past. It's really frustrating, and given that it appears some actions authors really do refer to documentation, documentation is the right place to put advice to avoid this problem.

[nguyenalex836]

@jsoref Thanks for opening an issue - I'll get this triaged for review ✨

[Bamag235]

Hi I’m new on this application how to use it thank you so much

[github-actions[bot]]

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

[sunbrye]

Can the SME confirm whether points 1, 2, and 3 are caveats that should be documented?

[github-actions[bot]]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[nguyenalex836]

@jsoref Thank you very much for your patience while our team reviewed! They responded with the following -

pre doesn't work from local actions Its worth noting this on pre, a notice such as pre is not supported for local actions, would be sufficient there.

As for the other two bullet points, those feel really specific to what the user is trying to do. They are technically correct, but I wouldn't recommend documenting them. The first notice should be sufficient, and users can work around that if needed. Local actions are a very niche use case compared to pre

I've added the help wanted label so that you, or anyone else, can add the pre is not supported for local actions note to the docs ✨

CC @sunbrye just for visibility 💛

[SuperSaleng]

[maintainer edit for spammy content]

[jsoref]

@nguyenalex836