Promotion hooks inCodefreshGitOps are specialized workflows that run at keypoints duringa product release. A product release is created when a Promotion Flow is manually or automatically triggered.

Promotion hooks in GitOpsCloudare specialized workflows that run at keystages ofa product release. A product release is created when a Promotion Flow istriggered, eithermanually or automatically.

{% include

image.html

max-width="60%"

%}

Promotion hooksare implemented usingthe sameunderlyingmechanism as standard Promotion Workflows, but run with additional context and scope on releases and environments.

Unlike Pre- and Post-Action Promotion Workflows, whichrun in specific environments and target individual applications, promotion hooks runat the release or environment level. They are not tied to a specific deployment or application, making them reusable across multiple flows. Promotion hooks enable real-time alerts, custom logic, and actions—without requiring users to monitor the promotion directly in the UI. Teams can stay informed and respond instantly as promotions progress.

Promotion hooksusethe same mechanism as standard Promotion Workflows but run with additional context and scope on releases and environments.

Unlike Pre- and Post-Action Promotion Workflows, whichoperate on each application within environments, promotion hooks runonce per release or environment. They are not tied to a specific deployment or application, making them reusable across multiple flows. Promotion hooks enable real-time alerts, custom logic, and actions—without requiring users to monitor the promotion directly in the UI. Teams can stay informed and respond instantly as promotions progress.

Promotion hooks can run at different stages of a release:

Promotion hooks can run at different stages of aproductrelease:

***Release start**: When a release is initiated

***Release end**: When a release completes, whether**successful** or**failed**

***Per environment**: When a release transitions through specific environments:

* Auditing and visibility

Capture details on the entirepromotion release and take action

Capture details on the entireproduct release and take action.

* Notifications and reporting

Get timely alerts and notifications on success and failures alike through familiar channels. Send alerts to Slack, email, or monitoring tools based on release events to be always in the loop instead of having to constantly monitor the promotion release.

* Integration with external tools

Automate updates to ticketing systems such as Jira, or observability platforms.

For examples, check out[Codefresh Hub for Argo](https://codefresh.io/argohub/){:target="\_blank"}.

Explore examples in[Codefresh Hub for Argo](https://codefresh.io/argohub/){:target="\_blank"}.

Forpromotion hooks to work in Promotion Workflows, you need these resources:

To runpromotion hooks in Promotion Workflows, you need these resources:

***(Required) Service account, service account role and role binding**

A default service account, service account role, and role binding, are automatically added to all Workflow Templates when you install the GitOps Runtime. The provided default resources are sufficient to implement promotion hooks. To use your own resources, see[Service accounts & service account roles for promotion hooks](#service-accounts--service-account-roles-for-promotion-hooks).

|**Feature**|**Promotion Hooks**|**Promotion Workflows**|

|----------------|----------------------|-----------------------------------------------|

|**Purpose**| Provides information on the release| Provides information on promoted changes in applications within an environment|

|**Execution**| Runs at release start, end (success, failure), or per environment (start, success, failure)| Runs for each application in an environment before and after promotion|

|**Scope**| Runs on cluster at release or environment level| Runs per application in the environment|

|**Effect on promotion**| Notifies on promotion status| Blocks a promotion if conditions fail|

|**Purpose**| Provides information on the release.| Provides information on promoted changes in applications within an environment.|

|**Execution**| Runs at release start, end (success, failure), or per environment (start, success, failure).| Runs for each application in an environment before and after promotion.|

|**Scope**| Runs on cluster at release or environment (once for each environment) level.| Runs per application in the environment.|

|**Effect on promotion**| {::nomarkdown}<ul><li>If a hook fails, the product release fails as well.</li>If the release is terminated, On Fail and On Release Fail hooks are run.</li>If an On Start or On Success hook fails, the On Fail hook if defined, is run.</li></ul>{:/}| Blocks the promotion when a workflow fails.|

This ensures:

When the Promotion Flow is triggered and a product release is created, the promotion mechanism:

As the Flow progresses, the promotion mechanism:

Assign Promotion Workflows with promotion hooks in the Promotion Flow for the release or environments: