Promotion hooks in GitOps Cloud are specialized Promotion Workflows that run at key stages of a product release. A product release is created when a Promotion Flow is triggered, either manually or automatically.

Promotion hooks in GitOps Cloud are specialized Promotion Workflows that run at key stages of a product release to provide information on the release and its environments. A product release is created when a Promotion Flow is triggered, either manually or automatically.

{% include

image.html

***On success**: When the promotion completes successfully in an environment

***On failure**: When the promotion fails in an environment

See[Assigning promotion hooks in Promotion Flows](#assigning-promotion-hooks-in-promotion-flows).

See[Assigning promotion hooks in Promotion Flows](#assigning-promotion-hooks-in-promotion-flows). For the YAML specifications of promotion hooks when assigned, see[Promotion Flow YAML]({{site.baseurl}}/docs/promotions/yaml/promotion-flow-crd/).

* Auditing and visibility

* Integration with external tools

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

* Approvals from external systems

Handle approvals required from external systems such as ServiceNow by pausing the promotion through a promotion hook when a PR pause is not feasible.

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

The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.

|**Feature**|**Promotion Hooks in Workflows**|**Pre- and Post-Action Workflows**|

||**Promotion Workflows**|

|**Feature**|**Promotion Hook Workflows**|**Pre- and Post-Action Workflows**|

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

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

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

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

Assign Promotion Workflows with promotion hooksto the Promotion Flow for the release or for one or more environments:

If you need aservicerole with additional permissions or a new service account, do one of the following:

If you need a role with additional permissions or a new service account, do one of the following:

***Use a custom role**

Create a new service role with the required permissions, and bind it to the default service account,`cf-default-promotion-workflows-sa`.

***Use a custom service account**

Use your own service account, and bind it to the default service role,`cf-default-promotion-workflows-role`.

apiVersion:v1

Codefresh provides two options for defining manifests for promotion entities:Form mode and YAML mode.

Codefresh provides two options for defining manifests for promotion entities:[Chart mode]({{site.baseurl}}/docs/promotions/promotion-flow/) and YAML mode.

If you prefer working with YAML, create the manifest using the example Promotion Flow YAML below, and the table with field descriptions.

metadata:

name:global-parallel-flow

spec:

properties:

triggerEnvironment:dev# name of the initial environment that triggers promotion flow

steps:# one or more environments across which to promote product

-environment:qa# target environment

dependsOn:# environment to successfully promote before triggering promotion for target

-dev

triggerEnvironment:dev

steps:

-environment:staging

dependsOn:

-qa

-dev

policy:

preAction:pre-action# optional; the promotion workflow to run before the promotion action

postAction:post-action# optional; the promotion workflow to run after the promotion action

action:commit# required; the promotion action to execute

action:commit

hooks:

onStart:slack-start-hook

onSuccess:simple-fail

onFail:jira-open-bug

-environment:production

dependsOn:

-staging

policy:

action:commit

hooks:

onStart:slack-start-hook

onSuccess:success-hook-test

onFail:slack-fail-hook

|`spec.steps`| The step in the Promotion Flow that defines the list of target environments and their dependencies. <br>At least one target environment and dependency must be defined.| array| Required|

|`spec.steps.environment`| The name of the specific target environment for which to trigger the promotion.| string| Required|

|`spec.steps.environment.dependsOn`| One or more environments that must be successfully promoted before promotion can be triggered in the succeeding environments.| array| Required|

| `spec.steps.policy.action` | The action that should trigger the promotion in the target environment for this Promotion Policy.<br>Can be one of the following:{::nomarkdown}<ul><li><code class="highlighter-rouge">commit</code>:Executes a commit operation on the target application.</li><li><code class="highlighter-rouge">pr</code>: Executes a commit and opens a pull request for the target application.<br>Useful when you need manual approval before commit.</li><li><code class="highlighter-rouge">none</code>: Does not execute any action on the target application.<br>In this case, the Post-Action workflow must include a step that is equivalent </li></ul>{:/}| string | Required |

|`spec.steps.environment.policy`| The Pre-Action Workflow, Action, and Post-Action Workflow to implement for the Promotion Policy through the`action`,`preAction`, and`postAction` attributes. <br>The Action attribute is required.<br>An`policy` attribute defined here overrides global Policies that match the product/environment. See[Promotion Policy implementation logic]({{site.baseurl}}/docs/promotions/promotion-policy/#promotion-policy-implementation-logic) for information on how they are applied.| object| Optional|

|`spec.steps.environment.policy.preAction`| The name of the Promotion Workflow to execute_before_`spec.steps.policy.action`.| string| Optional|

|`spec.steps..environment.policy.postAction`| The name of the Promotion Workflow to execute_after_`spec.steps.policy.action`.| string| Optional|

|`spec.steps.environment.policy.action`| The action that should trigger the promotion in the target environment for this Promotion Policy.<br>Can be one of the following:{::nomarkdown}<ul><li><codeclass="highlighter-rouge">commit</code>: Executes a commit operation on the target application.</li><li><codeclass="highlighter-rouge">pr</code>: Executes a commit and opens a pull request for the target application.<br>Useful when you need manual approval before commit.</li><li><codeclass="highlighter-rouge">none</code>: Does not execute any action on the target application.<br>In this case, the Post-Action workflow must include a step that is equivalent </li></ul>{:/}| string| Required|

|`spec.steps.environment.hooks`| The promotion hooks to run for the_environment_, and can be any of the following:{::nomarkdown}<ul><li><codeclass="highlighter-rouge">onStart</code>: The promotion hook to run when the promotion reaches the environment.</li><li><codeclass="highlighter-rouge">onSuccess</code>: The promotion hook to run when the promotion completes successfully in the environment.</li><li><codeclass="highlighter-rouge">onFail</code>: The promotion hook to run when the promotion fails in the environment.</li></ul>{:/}| string| Optional|

|`spec.hooks`| The promotion hooks to run for the_product release_, and can be any of the following:{::nomarkdown}<ul><li><codeclass="highlighter-rouge">onStart</code>: The promotion hook to run when the release is initiated.</li><li><codeclass="highlighter-rouge">onSuccess</code>: The promotion hook to run when the release completes successfully.</li><li><codeclass="highlighter-rouge">onFail</code>: The promotion hook to run when the release fails.</li></ul>{:/}| string| Optional|

[Configure Promotion Flows]({{site.baseurl}}/docs/promotions/promotion-flow/)

[Configure hooks in Promotion Workflows]({{site.baseurl}}/docs/promotions/promotion-hooks/)

[Product YAML]({{site.baseurl}}/docs/promotions/yaml/product-crd/)

[Promotion Policy YAML]({{site.baseurl}}/docs/promotions/yaml/promotion-policy-crd/)

[Promotion Template YAML]({{site.baseurl}}/docs/promotions/yaml/promotion-template-crd/)