Comment in Creating dependent jobs section is vague and confusing

[gsrohde]

What article on docs.github.com is affected?

https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/managing-complex-workflows#creating-dependent-jobs and/or https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds

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

In https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/managing-complex-workflows#creating-dependent-jobs, the possibility of constraining jobs to run sequentially without the failure of earlier jobs in the sequence preventing the later jobs from running: If one of the jobs fails, all dependent jobs are skipped; however, if you need the jobs to continue, you can define this using the if conditional statement.

I had expected, thus, to see an example of how to do this, either directly here or in one of the two linked-to articles (either https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#jobsjob_idif or https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds).

It is not clear what sort of "if" statement is called for, nor whether it should supplement or replace the "needs" directive. The https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds article reiterates the possibility of constraining jobs to run in sequence without failing jobs preventing later jobs from running: If a job fails, all jobs that need it are skipped unless the jobs use a conditional statement that causes the job to continue. This at least suggests that the "if" statement supplements the "needs" directive, but again, there is no example given of how to do this.

Since the Creating dependent jobs article occurs in the Learn GitHub Actions section of the documentation, it would probably be better to just omit the comment about allowing dependent jobs to run when their precursors fail, or at least to provide or link to an example the clarifies how to set this up.

Additional information

Content Plan

Linked here

[janiceilene]

Thanks so much for opening an issue @gsrohde! I'll get this triaged for review.

[skedwards88]

Thanks for pointing this out @gsrohde !

Here is an example of a job continuing based on a conditional even though it needs a job that failed:

name: need-fail-continue

on: [push, workflow_dispatch]

jobs:
  job1:
    runs-on: ubuntu-latest
    steps: 
      - run: exit 1 # This will cause job1 to fail
  
  job2:
    needs: [job1]
    if: ${{ always() }} # This makes job2 run even if job1 fails
    runs-on: ubuntu-latest
    steps: 
      - run: echo '...'
  

I agree with your assessment in the OP of where this example should be added. You or anyone is welcome to open a PR to address this issue!

[tonyhallett]

It should also be made clear, with examples, that the (Job status check functions)[https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#job-status-check-functions] apply to jobs as well as steps.

[The1onlyit]

A job should be fully explained I don't know what to figure out how to get it all done and will be trying new things in the internet to get it done 👍

[felicitymay]

As far as I can tell, this issue has been fixed by the many updates to the Actions docs since this was originally raised.

• jobs.<job_id>.needs now includes a clear example showing how to ensure that a job continues even if jobs that it depends on failed: Example: Not requiring successful dependent jobs
• Creating dependent jobs links to the section Defining prerequisite jobs which also gives clear examples.

[KINGTV1]

#764

[KINGTV1]

---