Clarify expressions and provide examples for workflows with skipped jobs

[Ubersmake]

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/using-workflows/workflow-syntax-for-github-actions#jobsjob_idif
https://docs.github.com/en/actions/learn-github-actions/expressions#status-check-functions

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

There is potential confusion when jobs are skipped in workflows with multiple jobs and with status checks.

If a run contains a series of jobs that need each other, a failure or skip applies to all jobs in the dependency chain from the point of failure or skip onwards.

This is from

docs/data/reusables/actions/jobs/section-using-jobs-in-a-workflow-needs.md

Line 1 in ce6be8e

Use `jobs.<job_id>.needs` to identify any jobs that must complete successfully before this job will run. It can be a string or array of strings. If a job fails or is skipped, all jobs that need it are skipped unless the jobs use a conditional expression that causes the job to continue. If a run contains a series of jobs that need each other, a failure or skip applies to all jobs in the dependency chain from the point of failure or skip onwards.

This takes precedence over https://docs.github.com/en/actions/learn-github-actions/expressions#success. While this isn't wrong, it should be called out.

needs.<job_id>.result is particularly interesting because it can be used in job.<job_id>.if. However, needs.<job_id>.result == 'skipped' will not matter because "a failure or skip applies to all jobs in the dependency chain from the point of failure or skip onwards."

There's additional nuance needed with https://docs.github.com/en/actions/learn-github-actions/expressions#always. While always() always runs, it's needed to check conditionals on jobs in a dependency chain that contain a skipped job.

Additional information

Multiple scenarios were set up and tested in https://github.com/Ubersmake/try-github-actions/actions/runs/6355991752 to try running jobs when a previous job was skipped.

Maintainer note / Docs plan

To update the docs for this issue, we need to do the following.

1. In https://docs.github.com/en/actions/learn-github-actions/expressions#success, update the description to say:

   Returns `true` when all previous steps have succeeded.
   

2. In this reusable, add a sentence at the end of line 1 that says something similar to:

   If you would like a job to run even if a job it is dependent on did not succeed, use the `always()` conditional expression in `jobs.<job_id>.if`.
   

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

[cmwilson21]

@Ubersmake Thanks for opening an issue! We really appreciate all the details and added information ✨

I'll get this triaged for review! ⚡

[Ubersmake]

I edited the original issue. There's some nuance to always(). As far as I've seen, always() always runs. The nuance is that it's needed to check conditionals for jobs that have skipped and jobs that run after a dependent job has skipped.

[SiaraMist]

Thank you for for raising this issue, @Ubersmake. I really appreciate your demo workflow with all of the clearly named jobs. It was so helpful in working to understand this functionality and how we can update the docs in a way that's helpful to users. 💖

Question

For the nuance to always() that you pointed out, I was wondering if this example describes what you are noticing? https://docs.github.com/en/actions/using-jobs/using-jobs-in-a-workflow#example-not-requiring-successful-dependent-jobs

Docs updates

I agree that we should update the success() description. Here is what I'd propose:

In https://docs.github.com/en/actions/learn-github-actions/expressions#success, update the description to say:

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

[Ubersmake]

For the nuance to always() that you pointed out, I was wondering if this example describes what you are noticing? https://docs.github.com/en/actions/using-jobs/using-jobs-in-a-workflow#example-not-requiring-successful-dependent-jobs

Mostly. What that example also needs is:

job4:
  if: ${{ always() }}
  needs: [job3]

The nuance is that job3 will run regardless of the results of job1 and job2. job1 and job2 just need to finish. But now that that particular dependency chain can be in a non-success state, every subsequent job on that chain needs if: ${{ always() }}. This is doubly true if it's going start checking for specific states of needs.<job_id>.result.

I'll be honest, I got confused trying to keep track of everything. I vaguely remember checking for the "skipped" status for a different repo, the context being a build-and-deploy workflow where the "build" part can be skipped if an artifact is provided. So I made another example which is marginally easier to track? Maybe? https://github.com/Ubersmake/try-github-actions/actions/runs/6412603150

In https://docs.github.com/en/actions/learn-github-actions/expressions#success, update the description to say:

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

Makes perfect sense to me. I don't know if it would be clearer if that was instead:

Returns `true` when all previous steps have succeeded.

Regardless, that would also address this year-old thread on Stack Overflow: https://stackoverflow.com/questions/74386773/github-actions-job-is-skipped-although-all-needs-succeeded/74529413#74529413. Although I didn't see any related open issues here, which is why I opened one up to begin with.

[SiaraMist]

I like your suggestion to say "when all previous steps have succeeded". 👍

For the example that uses always(), I'm not completely following the reasoning for needing a fourth job to demonstrate the concept. Although, I'm not writing workflows frequently so I definitely could be missing something and welcome your feedback. 🙂 Would updating the text that explains the examples to something similar to the following make sense, and negate the need for a job4?

Example: Requiring successful dependent jobs

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

In this example, job1 must complete successfully before job2 begins, and job3 waits for both job1 and job2 to complete.

The jobs in this example run sequentially:

1. job1
2. job2
3. job3

If job1 does not complete successfully, then both job2 and job3 will be skipped, because they are down the dependency chain from job1 and rely on its successful completion before they can start.

Example: Not requiring successful dependent jobs

jobs:
  job1:
  job2:
    needs: job1
  job3:
    if: ${{ always() }}
    needs: [job1, job2]

In this example, job1 must complete successfully before job2 begins. While job3 is dependent on the completion of job1 and job2 before it can start, the use of the always() conditional expression enables it to always run after the previous jobs complete, regardless of the success status of the jobs it is dependent on. For more information, see "AUTOTITLE."

[Ubersmake]

For the example that uses always(), I'm not completely following the reasoning for needing a fourth job to demonstrate the concept.

It's definitely an edge case. It's most applicable to

docs/data/reusables/actions/jobs/section-using-jobs-in-a-workflow-needs.md

Line 1 in ed3e998

Use `jobs.<job_id>.needs` to identify any jobs that must complete successfully before this job will run. It can be a string or array of strings. If a job fails or is skipped, all jobs that need it are skipped unless the jobs use a conditional expression that causes the job to continue. If a run contains a series of jobs that need each other, a failure or skip applies to all jobs in the dependency chain from the point of failure or skip onwards.

If a run contains a series of jobs that need each other, a failure or skip applies to all jobs in the dependency chain from the point of failure or skip onwards.

Maybe just a reminder of that will be enough. This example isn't necessarily for always(), but for what happens after a failure or skip in a dependency chain:

jobs:
  job1:
    if: false # Skips job1
  job2:
  job3:
    if: ${{ always() }} # Always run
    needs: [job1, job2]
  job4:
    if: ${{ always() }} # Needed if job1 skips. job3 succeeding is not enough.
    needs: job3

This is similar to https://github.com/Ubersmake/try-github-actions/actions/runs/6412603150/workflow#L73. In the above example, job3 will always run after job1 and job2. job4 needs if: ${{ always() }} to run if job1 did not succeed. job4 running is not only based on job3 suceeding, but the entire dependency chain.

Maybe this is actually a bug? Again, it is an edge case. A decision had to be made on whether "always" or "dependency chain from the point of failure or skip onwards" took precedence. Calling out that precedence is what would be most helpful in the docs.