GHA job status check functions: wrong description of success()

[tobinus]

What article on docs.github.com is affected?

Context and expression syntax for GitHub Actions, under "Job status check functions".

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

The documentation of success() reads:

Returns true when none of the previous steps have failed or been canceled.

However, if your job needs another job which is skipped, success() returns false, even though none of the previous steps have failed or been canceled (they just succeded or were skipped).

This caused me a great deal of confusion, as my job kept being skipped even though I had set if: success(), which I thought would return true when none of the previous steps have failed or been canceled.

The documentation should be updated so that it describes success() accurately. A suggestion:

Returns true when all previous jobs have run successfully.

Or if we still wish to explain what we mean by "run successfully":

Returns true when none of the previous jobs were skipped, and none of the previous steps have failed or been canceled.

Additional information

To understand how success() actually behaves, I created a minimal workflow:

The job "runs-upon-success" was skipped, even though none of the previous steps have failed or been canceled.

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

[janiceilene]

@tobinus Thank so much for opening an issue and including a sample workflow to explain what you're seeing! I'll get this triaged for someone to take a look 👀

[lee-dohm]

This appears to be a duplicate of #4821. As was stated in that issue:

With regard to this issue, as a general rule we don't document bugs. Since the behavior in actions/runner#491 has been marked by the team maintaining actions/runner as a bug, we feel that creating official documentation of that behavior would unduly increase our maintenance burden. For this reason, I'm going to go ahead and close this issue.

Since that is still the case, I'm going to close this issue as a duplicate. Please let me know if I've misunderstood anything.

Thanks for reaching out and helping contribute to the GitHub Docs!

[tobinus]

This appears to be a duplicate of #4821. As was stated in that issue:

With regard to this issue, as a general rule we don't document bugs. Since the behavior in actions/runner#491 has been marked by the team maintaining actions/runner as a bug, we feel that creating official documentation of that behavior would unduly increase our maintenance burden. For this reason, I'm going to go ahead and close this issue.

Since that is still the case, I'm going to close this issue as a duplicate. Please let me know if I've misunderstood anything.

Thanks for reaching out and helping contribute to the GitHub Docs!

I disagree for three reasons:

1. The referred issue (Job-level "if" condition not evaluated correctly if job in "needs" property is skipped actions/runner#491) does not refer to the success() function directly, and is instead focused on the implied behaviour when none of the job status check functions are used. So the issue could be with either the implied behaviour, or the success() function (since the condition is modified to be success() && ... when no job status check function is present, as far as I can tell).
2. The referred issue presents two expected outcomes: Either a change to the behaviour, or a documentation update. When the team has marked the issue as a bug but not given any comment besides that, it is not clear to me whether they consider this a bug with the runner or an issue with the documentation.
3. The referred issue turned one year old today, with absolutely no progress or feedback. At this point, the burden the wrong documentation has put on GitHub's users must have far exceeded that of documenting the real version of Github Actions rather than some fictional version of it. A change/fix would probably need to announced widely as well, as it might break workflows that depend on the current (not documented) behaviour, so it might be unfeasible to change it in the end. This whole experience (including a support ticket and the frequent downtime) is leaving me with the impression that I was wrong to start using GitHub Actions, and I fear I'm not alone. I don't see how this is beneficial to GitHub.