Hooks API

Pipelines communicates with a hook entirely through environment variables. There are three namespaces:

• PIPELINES_HOOK_CTX_*: context values about the run, set directly as the variable's value.
• PIPELINES_HOOK_IN_*: paths to input files the hook reads.
• PIPELINES_HOOK_OUT_*: paths to output files the hook writes.

The hook's execute command reads from the first two namespaces and writes to the third.

API version

Latest version: v1.2.0.

The Hooks API follows semantic versioning, starting at v1.0.0. The minor version is incremented when backwards incompatible changes (new inputs or fields) are added. The patch version will be incremented when bugs are fixed.

A hook can compare PIPELINES_HOOK_CTX_API_VERSION against the minimum version it requires.

Context inputs (PIPELINES_HOOK_CTX_*)

Scalar facts about the run, set directly as the variable's value.

A context variable that does not apply to the run is left unset, rather than set to an empty string. A hook can therefore tell "not applicable" apart from "set but blank", for example with [ -z "${PIPELINES_HOOK_CTX_ACTION+x}" ] in bash.

Always set

Variable	Description
PIPELINES_HOOK_CTX_API_VERSION	The current version of the Hooks API.
PIPELINES_HOOK_CTX_CI_PLATFORM	The CI platform running the hook: github or gitlab.
PIPELINES_HOOK_CTX_ORGANIZATION	The organization (GitHub) or group (GitLab) that owns the repository.
PIPELINES_HOOK_CTX_REPOSITORY	The repository name.
PIPELINES_HOOK_CTX_ACTOR	The user that triggered the run.
PIPELINES_HOOK_CTX_GIT_REF	The git ref that triggered the run.
PIPELINES_HOOK_CTX_GIT_HASH	The commit SHA the run is operating on.

Set when applicable

Variable	Description
PIPELINES_HOOK_CTX_ACTION	The command the hook ran after: plan or apply. A destroy is reported as apply.
PIPELINES_HOOK_CTX_ACTION_STATUS	The outcome of that command: succeeded or failed.
PIPELINES_HOOK_CTX_CHANGE_REQUEST_NUMBER	The pull/merge request number.
PIPELINES_HOOK_CTX_CHANGE_REQUEST_URL	The pull/merge request URL.
PIPELINES_HOOK_CTX_CHANGE_REQUEST_BRANCH	The source branch of the pull/merge request.
PIPELINES_HOOK_CTX_SOURCE_DIR	The directory the hook's source was fetched into. Set only for hooks that declare a source.

The three CHANGE_REQUEST variables are set or absent together: they are set when the run is associated with a pull/merge request, and absent for a push to a deploy branch.

File inputs (PIPELINES_HOOK_IN_*)

Paths to files the hook reads. The plans directory and units file are always set.

Variable	Description
PIPELINES_HOOK_IN_PLAN_JSON_DIR	Directory containing the decrypted plan JSON for the run's units.
PIPELINES_HOOK_IN_UNITS_JSON_FILE	Path to a JSON file describing the units in the run.
PIPELINES_HOOK_IN_ERRORS_FILE	Path to a plain text file holding the combined output of the run's failed Terragrunt executions, with ANSI color codes removed. Set only for error hooks. Since v1.2.0.

Plans JSON directory

Within PIPELINES_HOOK_IN_PLAN_JSON_DIR, each unit's plan is stored at <unit-path>/tfplan.json, where <unit-path> is the unit's path relative to the repository root. Only units that produced a plan have a file, so the directory may not contain an entry for every unit in the run.

The file is the JSON form of the OpenTofu/Terraform plan (terraform show -json).

Units JSON file

PIPELINES_HOOK_IN_UNITS_JSON_FILE points to a JSON array describing each unit the hook applies to:

[
  {
    "path": "dev/us-east-1/vpc",
    "plan_json_file": "/abs/path/to/dev/us-east-1/vpc/tfplan.json",
    "result": "succeeded"
  },
  {
    "path": "dev/us-east-1/database",
    "result": "failed",
    "reason": "run error"
  }
]

Field	Description
path	The unit's path relative to the repository root.
plan_json_file	Absolute path to the unit's decrypted plan JSON, the same file addressed under the plans directory above. Omitted when the unit produced no plan.
result	The unit's result from the Terragrunt run report: succeeded, failed, or early exit. Omitted when the run report has no entry for the unit. Since v1.2.0.
reason	The reason from the run report, when it gives one. Since v1.2.0.
cause	The cause from the run report, when it gives one. Since v1.2.0.

Outputs (PIPELINES_HOOK_OUT_*)

Paths to files the hook may write. Each is set from the API version that introduced it. Pipelines reads the result, summary and comment back only when the hook process exits 0, and reads the error summary and error comment only when it exits non-zero.

Variable	Description
PIPELINES_HOOK_OUT_RESULT_FILE	Write the hook's result: pass, warn, or deny.
PIPELINES_HOOK_OUT_SUMMARY_FILE	Write a short summary of the hook's outcome.
PIPELINES_HOOK_OUT_COMMENT_FILE	Write a comment body to surface on the pull/merge request.
PIPELINES_HOOK_OUT_ERROR_SUMMARY_FILE	Write a short summary of why the hook failed, shown next to the title when it exits non-zero. Since v1.1.0.
PIPELINES_HOOK_OUT_ERROR_COMMENT_FILE	Write the body to show on the pull/merge request when the hook exits non-zero. Since v1.1.0.

Writing to these files is optional. A hook that exits 0 and writes nothing reports a pass with no summary or comment. A hook that exits non-zero and writes nothing shows its exit code.

Results

The result written to PIPELINES_HOOK_OUT_RESULT_FILE is one of:

Result	Meaning
pass	The default result.
warn	Advisory warning.
deny	Rejection. Fails the pipeline run.

The result is a severity surfaced in the pull/merge request comment. deny fails the pipeline run and blocks the pull/merge request from merging; warn is advisory and does not affect the run; pass produces no failure. An empty or unrecognized value is treated as pass.

For how the result, summary, and comment appear on the pull/merge request, see How results and comments appear.