Policy-Driven Hooks

Use action: hooks with on: operation to select hooks at component lifecycle events. Define the hooks in the policy document's spec.hooks map.

Require TFLint after a plan

policy.d/lint.yaml

apiVersion: atmos/v1
kind: Policy
metadata:
  name: platform
spec:
  hooks:
    lint:
      kind: command
      command: tflint
      args: [--recursive]
  policies:
    lint-plan:
      on: operation
      action: hooks
      rule: input.event == 'after.terraform.plan' && input.status == 'success'
      hooks:
        - ref: lint
          event: after.terraform.plan
          required: true
          require_success: true

Install TFLint on the runner or pin it through spec.tools. Run Atmos with the directory enabled:

export ATMOS_POLICY_DIR="$PWD/policy.d"
atmos terraform plan vpc -s dev

The hook runs after a successful plan, including a detailed exit code of 2. A failing TFLint process fails the command. --skip-hooks cannot skip this required hook.

Hook requirements

ref

Required string. Hook name in the same document, or qualified document-name/hook-name. Resolution uses governing spec.hooks, not workspace component hooks.

event

Required string. Must match the current lifecycle event after alias normalization. Selecting a different event is an error, not a request to schedule future work.

required

Optional boolean; default false. If true, skip flags cannot suppress execution.

require_success

Optional boolean; default false. If true, a hook failure blocks regardless of its on_failure setting. Otherwise, the hook's normal failure handling applies.

Set both booleans to true for a mandatory successful check. Neither flag allows a hook to override a separate policy denial.

Hook definitions

spec.hooks uses the existing hook kinds and fields: command arguments, tool configuration, outputs, on_failure, and kind: step / kind: steps execution. Use ordered steps and their retry settings when needed.

Setting	Policy hook behavior
when, events on the hook	Rejected; select the event and condition in the rule
Nested when, background, continue_on_error, on_failure inside with	Rejected
Go templates and YAML functions	Not rendered in governing definitions; use literal values
spec.tools	Governing version pins; component dependency overrides are not merged
Execution order	Document filename, rule name, then hook reference list order
Repeated references	Execute for each selected requirement; not deduplicated

HTTP callback after apply

policy.d/callback.yaml

apiVersion: atmos/v1
kind: Policy
metadata:
  name: notifications
spec:
  hooks:
    applied:
      kind: step
      type: http
      with:
        url: https://example.invalid/deployment-completed
        method: POST
  policies:
    notify-helm-apply:
      on: operation
      action: hooks
      rule: input.event == 'after.helm.apply' && input.status == 'success'
      hooks:
        - ref: applied
          event: after.helm.apply
          required: true
          require_success: true

Replace the example URL with your endpoint. See the HTTP step fields for request options; template examples on that page do not apply to static governing hook definitions.

Lifecycle and failure behavior

Condition	Behavior
Policy denial or evaluation error	Block authorization before selected hooks execute
Missing hook definition, unavailable kind, or required tool failure	Fail the command
Dry-run	Report selected hooks without executing them
Plan reevaluation before saved-plan apply	Does not replay after-plan hooks
Required-success post-apply hook fails	Command fails, but the completed apply is not rolled back
Repeated invocation	May execute the hook again; HTTP receivers must handle duplicates

Operation policies use the per-component Terraform, Helmfile, Helm, and Kubernetes lifecycle events, not scaffold or aggregate events. To select cleanup after a failed operation, match input.status == 'failure' at an after-event. See Examples for cleanup and production scanner rules.

Protect hook binaries, scanner configuration, tool registries, and credentials along with the policy documents. Policy selection does not change a tool or HTTP hook's credential requirements.