Lifecycle hooks

Hooks run your own commands at points in the edit-mode lifecycle. Typical uses are installing local dependencies, or fetching a value from the cluster, such as a database password, so a local process can connect to it.

Events

Where to put them

Hooks go on a repository, or inside a mirror reloader:

repositories:
  myapp:
    repository: https://example.com/myapp.git
    directory: ./myapp/
    lifecycle_hooks:
      - type: edit_mode_prepare
        script: make deps
      - type: edit_mode_start
        script: sh -c 'kubectl get secret myapp-db -o jsonpath={.data.password} | base64 -d > .env.db'

Each hook has a type and one of script, mirror_script, or job.

How a script runs

Xianyun splits script into words, honouring single and double quotes, and runs the result directly in the repository’s directory. There’s no shell. $HOME, pipes, redirects, and ; mean nothing to Xianyun, so wrap the command in sh -c '...' when you want them, as the second hook above does. An unterminated quote stops Xianyun before it runs anything.

Variables of the form ${NAME} in a config value are expanded when the config loads, before the script is split. $(...) and backticks are never evaluated by Xianyun; they pass through to whatever shell you invoke. Escape a dollar sign with a backslash to keep Xianyun from expanding it. See Variables.

Environment

A hook gets your whole process environment plus the predefined variables (XIANYUN_CLUSTER_NAME and the rest). When the cluster is available it also gets KUBECONFIG, pointing at a temporary kubeconfig for the project’s cluster, and KUBECACHEDIR, so kubectl and helm inside the hook reach the right cluster. edit_mode_prepare hooks run before the cluster is available, so they run without those two.

Security

A hook is a command that runs as you, with your environment, and it can arrive through extends: fragments or a xianyun-project.yaml in a repository you cloned. Read Security before you run a config you didn’t write. Over MCP, xianyun_up, xianyun_deploy, and xianyun_update can trigger hooks without a confirmation prompt.