Hooks files¶

fab deploy publishes item definitions and nothing else. A hooks file holds the steps that do the rest, and allez deploy runs them before or after the dag node that names the file. Each hook's options, and how to write your own, are on the Hooks reference.

`<purpose>.hooks.yml`¶

A hooks file is one flat list of steps. When it runs is not in the file. The dag node that names it decides, by listing it under pre_deploy_hooks: or post_deploy_hooks::

fabric/<sub-folder>/.deploy/hooks/<purpose>.hooks.yml

version: 1

variables:                          # optional; each value may be an Override Map
  seed_rows: {default: 1000, feature: 100}

steps:
  - name: Run the ingestion notebook until it finishes
    action: run_notebook            # → a library hook (or .allez/hooks/run_notebook.py)
    item: <Name>.Notebook
    timeout_seconds: 900
    environments: [dev, feature]
    parameters: {seed_rows: "{{ variables.seed_rows }}"}
                                    # no on_error: a failed load stops the deploy here

  - name: Run the data checks
    action: run_notebook
    item: <Name>.Notebook
    on_error: continue              # a failed check is logged, the deploy goes on

A step stops the deploy when it fails, unless it says on_error: continue. Here a failed load stops everything after it, and a failed check is only reported.

fabric/allez.yml

dag:
  - config: data/config.yml
    post_deploy_hooks: [data/.deploy/hooks/ingest.hooks.yml]      # after a successful publish
  - config: reporting/config.yml
    depends_on: [data/config.yml]
    pre_deploy_hooks: [reporting/.deploy/hooks/takeover.hooks.yml] # before the publish

One file per purpose, at <sub-folder>/.deploy/hooks/<purpose>.hooks.yml. The loader enforces that path (Repo structure).

Steps¶

Key	Required	Meaning
`action`	yes	The hook to run (Python hooks).
`name`	no	Label in the output; defaults to the action.
`environments`	no	Inclusion Filter, written the same way as on roles, tags and dag nodes: the step runs only for these environments, and is otherwise skipped with a message saying so. Checked against the root `environments:` at load, like every other environment name.
`on_error`	no	`fail` (default) stops the deploy at this step; `continue` logs the failure and moves on.
anything else	per hook	Passed to the hook as keyword arguments.

Python hooks¶

An action names a hook: your own in .allez/hooks/ beside fabric/, else the one of that name shipped with allez (Where allez finds a hook).

Schedules are not a hook

An item's schedule travels in its .schedules file, so per-environment control is a parameter.yml rule.

A semantic model's refresh schedule lives in Power BI, so it is set by a fab_api step: the prod-only last step of the sample's reporting/.deploy/hooks/refresh.hooks.yml.

Placeholders¶

Resolved in every string before a hook runs:

Placeholder	Value
`{{ env }}`	the `--env`
`{{ workspace }}`, `{{ workspace_id }}`	the node's target workspace: the one `config.yml` names, or the branch workspace under `--branch-workspace`
`{{ variables.<key> }}`	from the file's `variables:`, resolved for the environment; an undeclared key is an error
`{{ items.<Name>.<Type>.id }}`	looked up in the target workspace at run time, so it works for items that exist only once deployed

There is no {{ parameters.* }}, because parameter.yml is a list of rules with no names. Named values live in variables:.

Substitution produces strings, even when a placeholder fills the whole value. In the example above, seed_rows reaches the notebook as a string. Use a literal YAML number or boolean when the run parameter needs that type (parameter types).

Name before type here

Hooks say items.<Name>.<Type>; fabric-cicd's $items.<Type>.<Name>.$id and allez's $allez.<sub-folder>.$items.<Type>.<Name>.$id say type first. Same lookup, opposite order.

When they run¶

post_deploy_hooks run only after a successful publish.
Across files on one node: declaration order within each key. pre_deploy_hooks: [a, b] runs a then b, the publish, then post_deploy_hooks: [c, d] runs c then d. Within a file: top to bottom, and a failing step stops there unless on_error: continue. Across nodes: dag order.
A hook must be safe to repeat (Hooks reference).