Skip to main content

Post hooks

Post hooks are an optional component of workflows. This document describes the features of post hooks and gives examples of their use.

Overview

A post hook is a task that can be set up to run at the end of a workflow, to perform various cleanup operations. Internally, a post hook runs in a container, just as a job does, though it runs under different conditions from a conventional job. A workflow can have at most two post hooks.

A post hook is defined under the field post-hooks in a config.yaml file. The definition of a post-hook is the same as a job with one exception. Unlike conventional jobs, post hooks cannot have user-defined dependencies, as the operation of the post hook at the end of a workflow will depend on the user-defined jobs included in that workflow.

Status

Post hooks may have a particular status:

StatusDescription
PassedPost hook has completed successfully
FailedPost hook has failed
PendingPost hook is in progress
IdlePost hook has not started

Configuration Example

This example defines a workflow called hello-world-workflow which contains two jobs, first-job and second-job. The workflow also contains two post hooks hello-world-pass-hook and hello-world-fail-hook. The post hooks have a when condition, which determines what would cause each of these two hooks to run. Acceptable values for the when condition are on-workflow-pass and on-workflow-fail. If all the jobs defined in the workflow pass, then any hook which has the on-workflow-pass condition will run, as the workflow is deemed to have passed. If any of the jobs defined in the workflow fail, then any hook which has the on-workflow-fail condition will run, as the workflow is deemed to have failed.

runners:
ubuntu-runner:
image: public.ecr.aws/y2s4f3y9/ubuntu-generic

# Define a job to be performed during a workflow
jobs:
first-job:
# Specify the runner used to perform this job
runner: ubuntu-runner

# Define one or more steps to execute commands as part of the job
steps:
- run:
name: Say Hello World
command: echo "Hello World"

second-job:
# Specify the runner used to perform this job
runner: ubuntu-runner
depends:
- hello-world:
when: on-completion

# Define one or more steps to execute commands as part of the job
steps:
- run:
name: Say Hello World
command: echo "Hello World"

post-hooks:
hello-world-pass-hook:
# Specify the runner used to perform this job
runner: ubuntu-runner

# Define one or more steps to execute commands as part of the job
steps:
- run:
name: Say Hello World
command: echo "Hello World"

hello-world-fail-hook:
# Specify the runner used to perform this job
runner: ubuntu-runner

# Define one or more steps to execute commands as part of the job
steps:
- run:
name: Say Hello World
command: echo "Hello World"

# Define a workflow to orchestrate a job
workflows:
hello-world-workflow:
jobs:
- first-job
- second-job
post-hooks:
- hello-world-pass-hook:
when: on-workflow-pass
- hello-world-fail-hook:
when: on-workflow-fail