Add a way (command or step) to early-exit the job and set check conclusion

[Jackenmen]

Select Topic Area

Product Feedback

Body

Currently, to skip the rest of the steps during a job, an if condition has to be added to all of the steps or steps have to be moved to another job.

It'd be nice to have a command or a step to early-exit (premature, prematurely, graceful, gracefully) (end, finish, terminate, termination, stop, halt, skip, cancel, discontinue, fail) the job during a step without failing the job:

::exit::

It'd also be nice to set the conclusion of the early-exited job:

::exit::failure

(equivalent to exit 1) or

::exit::neutral

(equivalent to exit 78 in Actions v1) and other check conclusions.

This would help save build time for both GitHub and customers.

Related StackOverflow and GitHub Community posts

• How to fail a job in Github Actions?
• How to force to exit in Github Actions step
• How to write a GitHub Action with a neutral Check Run status
• How to perform an early clean exit of a job ?
• Early successful termination of job
• Github Action Skip Steps/Fall Through Syntax

Related issues

• Has the setNeutral method been removed? toolkit#146
• veggiemonk/skip-commit

Same functionality in other CIs

• CircleCI: circleci-agent step halt
• Travis CI: travis_terminate
• AppVeyor: appveyor exit (Linux)
• Jenkins: currentBuild.result
• GitLab CI: exit 0

---

Originally posted by @ylemkimon in actions/runner#662 (comment)

This issue has received A LOT of upvotes (800+ at the time of writing) on the actions/runner repository but has since been closed with a request to redirect this feedback to this forum which is what this newly made discussion is meant to achieve:
actions/runner#662

[jpbochi]

Currently, https://github.com/actions/toolkit/tree/main/packages/core#exit-codes says:

Note that setNeutral is not yet implemented in actions V2 but equivalent functionality is being planned.

The docs at https://docs.github.com/en/actions/creating-actions/setting-exit-codes-for-actions only mentions success and failure.

---

One possible workaround would be to update the check run after it fails (See https://docs.github.com/en/rest/checks/runs#update-a-check-run). Unfortunately, that can't be done with a regular user token, only with GitHub Apps.

[jazanne]

This is something that has come for me a lot when working on workflows, would REALLY love to see it implemented

[punkbit]

If you're looking for a solution, at least to cancel:

gh run cancel ${{ github.run_id }}
exit 1

Results in:

✓ Request to cancel workflow XXXXXXX submitted.
Error: Process completed with exit code 1.

⚠️ The problem is that if you have concurrent builds, it'll cancel the whole job.

[Ferroin]

The second problem with this is that it only works if you don’t care about the result status for the job.

[vt89]

It is a must to avoid repetitive if conditions on all the following steps and improve readability!

[Steve-Glass]

👋 Chiming in from the Actions product team. I may roll this request up into a general backlog item for conditional operators. I think this is a similar ask. This is something that may be considered for this year. I will report back in October after planning to inform this group of the outcome.

[Steve-Glass]

@rmacklin My apologies, this was meant for another thread. Symptom of having many tabs open at once 😞 I plan on taking a look at this request in the next week or so, just focusing on other areas at the moment.

[rmacklin]

Gotcha, thanks for clarifying! Stoked to hear you'll be looking at this issue! :)

[owattley-rotageek]

Any update @Steve-Glass ?

[ubuntudroid]

It's been a half a year since your last comment, @Steve-Glass. Did this end up on the near term roadmap?

[pmaAXA]

Look taken @Steve-Glass?

[dwilches]

Has this feature been released? I can't find a way to avoid the "if" in each of the steps of a GHA to make the job exit as soon as a step determined there is nothing to do. Is there a planned release for this feature?

(Maybe @Steve-Glass)

[braboobssiere]

you can early exit with exit 1 but it will show as failure on status (if you don't care to differentiate between actual failure and failure from early exit then it's fine)

[meins111]

Also still waiting on this.
Current use-case:
Have a build-deploy workflow with manual dispatch. User input defines which component(s) are supposed to be build and deployed.
Implemented as a matrix action, and a first step to check whether the matrix combination is "selected" based on user input.
Doing an exit 1 will show (partial) failed result in the deploy action - no one wants that...

[Ferroin]

@meins111 For that specific use-case, had you considered dynamically generating the build matrix instead of skipping the parts you don’t need?

Something like:

jobs:
  matrix:
    name: Prepare build matrix
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - uses: actions/checkout@v4
      - id: set-matrix
        run: |
          matrix="$(./.github/scripts/generate-matrix.sh)"
          echo "${matrix}"
          echo "matrix=${matrix}" >> "${GITHUB_OUTPUT}"

  build:
    name: Build
    needs:
      - matrix
    strategy:
      matrix: ${{ fromJson(needs.matrix.outputs.matrix) }}

And just have .github/scripts/generate-matrix.sh produce a JSON representation of the build matrix on stdout when run.

Speaking from experience, this works very well provided you don’t need to make the jobs generated from the matrix required checks on a PR.

[pcharlan]

Speaking from experience, [building the matrix dynamically] works very well provided you don’t need to make the jobs generated from the matrix required checks on a PR.

You can make a do-nothing job named something like "Tests Complete", make it dependent on the matrix job, and add that job as a required PR check. It will pass if and only if all the Matrix jobs passed.

This may not work for every use case, but we use it to solve this problem and it works well.