runOn.yaml

----
# 1. change execution graph i.e. onSuccess do something onFailure do something else: 
- name: task1
  taskRef: { name: "my-task" }

- name: runIfTask1Fails 
  runAfter: ["task1"]
  runOn: ["failure"]

- name: runIfTask1Succeeds
  runAfter: task1
  runOn: ["success"]

---
# 1. change execution graph i.e. onSuccess do something onFailure do something else: 
- name: task1
  conditions:
    conditionRef: "condition-that-sometime-fails"
  taskRef: { name: "my-task" }

- name: runIfTask1Fails 
  runAfter: task1
  runOn: ["failure"]

- name: runIfTask1Succeeds
  runAfter: task1
  runOn: ["success"]

- name: runIfTask1IsSkipped
  runAfter: task1
  runOn: ["skip"]

---
# shorthand for "success", "failure", "skip"
- name: integration-tests
- name: cleanup
  runAfter: ["integration-tests"]
  runOn: ["always"] # can also be runOn: ["success", "failure"]

---
# multiple tasks - e.g. results for sharded tests
- name: integration-tests-1
- name: integration-tests-2
- name: publish-test-results
  runAfter: ["integration-tests-1", "integration-tests-2"]
  runOn: ["always"] # can also be runOn: ["success", "failure"]

---
# multiple tasks - combination of success or skip
- name: conditional-task-1
- name: conditional-task-2

- name: task-3
  runAfter: ["conditional-task-1", "conditional-task-2"]
  runOn: ["success", "skip"] # task-3 is run if 1 and 2 are success but is not run if either of them is failure

---
# always do something - publish results, task level updates, cleanup etc.
- name: task1
- name: task2
  runAfter: task1
  runOn: ["always"]

--
# I only want this task to run if some complex conditions are true
- name: task1
- name: task2
- name: task-3
  conditions:
    conditionRef: "my-complex-condition" # e.g. if task1 fails but task2 does not. or if task1, task2 succeed and the moon is blue
  runAfter: ["task-1", "task-2"]
  runOn: ["always"]

and the moon is blue

:D

I initially thought when I read the design comment that the number of runOns match the number of runAfters. I.e. the following:

runAfter: ["task-1", "task-2"]
runOn: ["success", "failure"]

where this says "this task only runs if task-1 is in success state and task-2 is in failure state." But now I understand that the runOn is a filter for all of the tasks in the runAfter list. So this actually says "this task only runs if task-1 AND task-2 are in success or failure states". Then a condition can do the more complex work of figuring out exactly which tasks did or did not succeed and how that affects the branching. Am I reading this all right?

Ahh, yeah that might be confusing...but you are right it says run this task only if task-1 AND task-2 are in success or failure states.

-- 
# What should happen here?
- name: task-1 # task-1 fails

- name: task-2
  runAfter: ["task-1"]
  runOn: ["success"]

- name: task3
  runAfter: ["task-2"]
  runOn: ["success", "skip"]

:) looks little tricky with multiple strategies ("success" and "skip") and single runAfter, it is possible to see conflicting countless strategies inside of runOn if its not restricted, how about:

- name: task-1 # task-1 fails

- name: task-2
  runAfter: ["task-1"]
  runOn: ["success"]

- name: task3
  runAfter: ["task-2"]
  runOn: ["success"]

- name: task4
  runAfter: ["task-2"]
  runOn: ["skip"]

where task4 and task3 refer to the same task.

Yeah, the question is around what is the state of to task-2 if task-1 fails? It has a runOn: ["success"]. So, it is not run. Does it mean its state is skip? I guess another way of putting the question would be -- should tasks that are not run due to a condition failure as well as tasks that are not run due to other reasons (e.g. a parent's condition failed or a parent task outright failed) have the same skip state or is it worth differentiating between them?

Yeah, the question is around what is the state of to task-2 if task-1 fails? It has a runOn: ["success"]. So, it is not run. Does it mean its state is skip? I guess another way of putting the question would be -- should tasks that are not run due to a condition failure as well as tasks that are not run due to other reasons (e.g. a parent's condition failed or a parent task outright failed) have the same skip state or is it worth differentiating between them?

I think such tasks should be classified as having "skip" state and dont see any reason to differentiate them. When a task is not run due to condition failure should be marked as skipped.