Failure handlers¶
Overview¶
Failure handlers are very similar to container run
steps
. They will execute a set of commands in a container. The main difference is that they are used to execute code after a pipeline step fails. This allows you to add cleanup and notification actions to the pipeline.
Failure handlers are defined globally, and can be referenced on both global pipeline level and on step
level. Thanks to that, you can create a global error notification, but also add certain cleanup logic to specific steps.
Failure handlers are executed in order of appearance of the onFailure
section of the pipeline. Failure handlers for steps
are executed first, followed by failure handlers defined in the global
section.
Important
When multiple failure handlers are specified, and one of them fails, the other ones will continue to execute. The pipeline tries to run every failure handler ignoring statuses of the previous ones.
Important
Failure handlers don’t affect the status of the pipeline. If a step fails, but all failure handlers finish correctly, the pipeline will still be in failed status!
Examples¶
Single failure handler¶
Below is an example of running a failure handler after a failed step
. It also shows how environment variables are injected to every step
and failure handler in the pipeline.
steps:
- name: step-that-fails
containerRun:
image: busybox
script: "noSuchCommand"
onFailure:
- handlerName: failure-handler-1
failureHandlers:
- name: failure-handler-1
image: busybox
script: 'echo "step $ICECI_FAILED_STEP_NAME has failed"'
Global failure handlers¶
Below is an example of running a failure handlers
from both step
and pipeline level.
steps:
- name: step-that-fails
containerRun:
image: busybox
script: "noSuchCommand"
onFailure:
- handlerName: failure-handler-1
- handlerName: failure-handler-2
globals:
onFailure:
- handlerName: failure-handler-1
- handlerName: failure-handler-3
failureHandlers:
- name: failure-handler-1
image: busybox
script: 'echo "failure handler $ICECI_STEP_NAME"'
- name: failure-handler-2
image: busybox
script: 'echo "failure handler $ICECI_STEP_NAME"'
- name: failure-handler-3
image: busybox
script: 'echo "failure handler $ICECI_STEP_NAME"'
Note
Notice that failure-handler-1
will run twice because it’s declared in both the global section and in the step. Currently IceCI does not implement any deduplication mechanism for failure handlers.
Environment variables and files¶
Here’s an example of defining environment variables and files on failure handler
level.
steps:
- name: step-that-fails
containerRun:
image: busybox
script: "noSuchCommand"
onFailure:
- handlerName: failure-handler-1
failureHandlers:
- name: failure-handler-1
image: busybox
script: |
echo $ICECI_FH
cat /mnt/file
environment:
- name: ICECI_FH
value: failure-handler-env
files:
- path: /mnt/file
fromSecret: failure-secret