Command Hooks provide a way to execute custom shell scripts or commands at specific points during the Zephyr Release operation. This allows you to integrate your own logic - such as running tests, building artifacts, or sending notifications - seamlessly into the release process.
You can configure these hooks in your configuration file using the command-hooks option. During their execution, command hooks have access to a rich set of environment variables. You can learn more about these variables in the Export Variables and String Templates and Patterns documentation to understand what resources are available to your commands as environment variables.
The execution flow illustrates exactly when your scripts will run and how they fit into the broader Zephyr Release process. This helps you understand the operational context when each hook is triggered.
In review release flow, the operation is split into two distinct phases depending on the state of the release proposal. Below is the flow for each phase:
This phase runs when creating or updating a release proposal.
-
Bootstrap operation and export base operation variables.
-
Run
command-hooks.pre-runcommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
Parse commits.
-
Export pre-calculate-version operation variables.
-
Run
command-hooks.pre-calculate-versioncommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
Calculate the next version.
-
Export post-calculate-version operation variables.
-
Run
command-hooks.post-calculate-versioncommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
Generate changelog release content and prepare changes in working directory.
-
Export pre-commit operation variables.
-
Run
command-hooks.pre-commitcommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
Commit changes to the working branch.
-
Export post-commit operation variables.
-
Run
command-hooks.post-commitcommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
Create/update the proposal.
-
Export post-proposal operation variables.
-
Run
command-hooks.post-proposalcommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
Export final operation variables.
-
Run
command-hooks.post-runcommands.
This phase runs when merging a release proposal, triggering the actual release. Note that this phase will only execute if tag.create-tag is enabled.
-
Bootstrap operation and export base operation variables.
-
Run
command-hooks.pre-runcommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
Generate changelog release content and extract the next version.
-
Export pre-tag operation variables.
-
Run
command-hooks.pre-tagcommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
Create the Git tag.
-
(If
release.create-releaseis enabled) Export pre-release operation variables. -
(If
release.create-releaseis enabled) Runcommand-hooks.pre-releasecommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
(If
release.create-releaseis enabled) Create the platform release. -
(If
release.create-releaseis enabled) Attach release assets. -
Export post-release operation variables.
-
Run
command-hooks.post-releasecommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
Export final operation variables.
-
Run
command-hooks.post-runcommands.
In auto release flow, the operation executes both the prepare and publish steps sequentially in a single run.
-
Bootstrap operation and export base operation variables.
-
Run
command-hooks.pre-runcommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
Parse commits.
-
Export pre-calculate-version operation variables.
-
Run
command-hooks.pre-calculate-versioncommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
Calculate the next version.
-
Export post-calculate-version operation variables.
-
Run
command-hooks.post-calculate-versioncommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
Generate changelog release content and prepare changes in working directory.
-
Export pre-commit operation variables.
-
Run
command-hooks.pre-commitcommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
Commit changes directly to the target branch.
-
Export post-commit operation variables.
-
Run
command-hooks.post-commitcommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
(If
tag.create-tagis enabled) Export pre-tag operation variables. -
(If
tag.create-tagis enabled) Runcommand-hooks.pre-tagcommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
(If
tag.create-tagis enabled) Create the Git tag. -
(If
tag.create-tagandrelease.create-releaseare enabled) Export pre-release operation variables. -
(If
tag.create-tagandrelease.create-releaseare enabled) Runcommand-hooks.pre-releasecommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
(If
tag.create-tagandrelease.create-releaseare enabled) Create the platform release. -
(If
tag.create-tagandrelease.create-releaseare enabled) Attach release assets. -
(If
tag.create-tagis enabled) Export post-release operation variables. -
(If
tag.create-tagis enabled) Runcommand-hooks.post-releasecommands. (If a stdout config override is detected via marker delimiters, it applies moving forward). -
Export final operation variables.
-
Run
command-hooks.post-runcommands.
In monorepo mode, hooks are categorized as global or per-workspace. This determines which config's command-hooks definition is used and how many times the hook fires.
| Hook | Scope | Fires per... | Config source |
|---|---|---|---|
pre-run |
Global | Once | Root config only |
pre-calculate-version |
Per-workspace | Each workspace | Workspace config (merged with root) |
post-calculate-version |
Per-workspace | Each workspace | Workspace config (merged with root) |
pre-commit |
Global | Once | Root config only |
post-commit |
Global | Once | Root config only |
post-proposal |
Global | Once | Root config only |
pre-tag |
Per-workspace | Each workspace | Workspace config (merged with root) |
pre-release |
Per-workspace | Each workspace | Workspace config (merged with root) |
post-release |
Per-workspace | Each workspace | Workspace config (merged with root) |
post-run |
Global | Once | Root config only |
When a hook fires per-workspace:
-
Config inheritance: The workspace's
command-hooksis deeply merged with the root'scommand-hooks. If a workspace definespre-tag, it overrides the root'spre-tag. If it doesn't definepre-tag, the root'spre-tagis used. -
ZR_NAMEenv var: During per-workspace hook execution, theZR_NAMEenvironment variable is set to the current workspace name. -
Config override via stdout: Per-workspace hooks support the same stdout-based config override mechanism as single-repo mode. The override marker delimiters (
---zephyr-release-config-override-start---/---zephyr-release-config-override-end---) work the same way. Overrides apply to the current workspace's config only.
When a hook fires globally:
-
Config source: Always uses the root config's
command-hooksdefinition. Workspace-levelcommand-hooksfor global hooks are ignored. -
Context:
ZR_NAMEis not set (or empty). Global hooks operate on the aggregated state across all workspaces.
Note
If a workspace defines pre-commit, post-commit, or post-proposal in its command-hooks, those definitions are silently ignored in grouped proposal mode. Only the root config's definitions for these hooks are used.