Skip to main content

Hook Types

Pipelines currently supports two types of hooks, each declared with its own block inside the repository block: after hooks and error hooks.

After hooks​

After hooks run after Pipelines completes a plan or apply. They are configured with after_hook blocks. Each block declares which commands it runs after and the command to execute. You can define multiple after hooks, and they run in the order they are defined.

repository {
  after_hook "on_success" {
    commands = ["plan"]
    execute  = [".gruntwork/hooks/success.sh"]
  }
}

Required fields​

  • commands: the Pipelines commands this hook runs after. One or both of plan and apply.
  • execute: the command to run, given as a list of the program followed by its arguments.

The block label (on_success in the example above) is also required and must be unique within the repository block.

Optional fields​

  • name: a human-readable display name for the hook.
  • source: a URL to fetch before the hook runs, so execute can run scripts that live outside the repository. See Remote script sources. Hooks Gruntwork provides do not need a source; see Gruntwork Provided Hooks.
  • env: environment variables to set for the execute command.
  • run_on_error: whether the hook runs when a preceding command or hook failed. Defaults to false.
  • timeout_seconds: how long the hook may run before it is terminated. Defaults to 300.
  • authentication: cloud credentials and secrets for the hook. See Authentication & Secrets.
  • filter: scopes the hook to a subset of the run's affected units by path, environment, and/or label. See Scoping a hook to specific units.

See the after_hook block attributes reference for full details.

Error hooks​

Error hooks run when a plan or apply fails with an error that matches one of their patterns. They are configured with error_hook blocks. Each block declares which commands it handles failures of, the error patterns to match in on_errors, and the command to execute. You can define multiple error hooks, and they run in the order they are defined.

repository {
  error_hook "on_failure" {
    commands  = ["plan", "apply"]
    on_errors = [".*"]
    execute   = [".gruntwork/hooks/failed.sh"]
  }
}

Required fields​

  • commands: the Pipelines commands whose failures this hook handles. One or both of plan and apply.
  • on_errors: a list of regular expressions matched against the output of the failed command. See Matching errors.
  • execute: the command to run, given as a list of the program followed by its arguments.

The block label (on_failure in the example above) is also required and must be unique among the error_hook blocks in the repository block.

Optional fields​

  • name: a human-readable display name for the hook.
  • source: a URL to fetch before the hook runs, so execute can run scripts that live outside the repository. See Remote script sources.
  • env: environment variables to set for the execute command.
  • timeout_seconds: how long the hook may run before it is terminated. Defaults to 300.
  • authentication: cloud credentials and secrets for the hook. See Authentication & Secrets.
  • filter: scopes the hook to failures in a subset of the run's affected units by path, environment, and/or label. See Scoping a hook to specific units.

Error hooks have no run_on_error field, because running on error is a non-configurable setting for them.

See the error_hook block attributes reference for full details.

Next steps​