Overview:
Sometimes it becomes very important to retry a failed step instead of re-running a complete job (obviously to save time and money). In this article, we will see how to retry a step when it is failed using the "when" attribute with the help of a simple example.
First of all, let's see what are the different parameters of the when
attribute.
when: on_success
This is the default option and means that the step will run only if all of the previous steps have been successful (returned exit code 0).when: always
This means that the step will run regardless of the exit status of previous steps.when: on_fail
This means that the step will run only if one of the preceding steps has failed (returns a non-zero exit code)
Note: CircleCI does not support automatic retries of failed steps, jobs & workflows. If you are looking for that feature, please vote for it here.
Retrying a Failed Step
By default, CircleCI will execute job steps one at a time, in the order that they are defined in config.yml
, until a step fails (returns a non-zero exit code). After a command fails, no further job steps will be executed.
Adding the when
attribute to a job step allows you to override this default behavior, and selectively run or skip steps depending on the status of the job.
Now, let's understand this through a working example that how you can use when: on_fail
to retry a failed step.
Below is the sample config.yml file where the step "Run on fail status" will trigger as the output of the previous step is a failure (exit 1).
version: 2.1 workflows: version: 2 build_deploy: jobs: - build jobs: build: docker: - image: circleci/python:3.7.5 steps: - checkout - run: name: Run commands command: | echo "I will exit fail status" exit 1 - run: name: Run on fail status command: | echo "I am result of above failed job" when: on_fail
Note: You can use the same command in the next step (with when attribute), to retry it or any other command. Users can also use API endpoints to retry a build. The above is just an example to show the working of when
attribute.
The below screenshot shows the triggering of the step containing when
attribute when the previous step fails.
Note: The state of the workflow, in this case, will be FAILED.
Below is the sample config.yml file where the step "Run on fail status" will not trigger as the output of the previous step is a success (exit 0):
version: 2.1 workflows: version: 2 build_deploy: jobs: - build jobs: build: docker: - image: circleci/python:3.7.5 steps: - checkout - run: name: Run commands command: | echo "I will exit success status" exit 0 - run: name: Run on fail status command: | echo "I am result of above failed job" when: on_fail
Comments
Article is closed for comments.