Gitops promotion hooks (#1277)

* Update promotion-flow.md

* Update promotion-flow.md

* Add promotion hooks

* Rename and update promotion hooks

* Update promotion-hooks.md

* Add promotion hooks to nav yamls

* Add sym link for promotion hooks to _gitops  collection

* Update promotion-hooks.md

* Update promotion-hooks.md

Edits after feedback from Dev

* Update content

Added draft diagram for promotion context behavior and content updates

* Update promotion-hooks.md

* Remove entities from mapping file

* Update

* Update diagram

* Update promotion-hooks.md

* Add new articles fro service accounts and promotion contexts

* Updates

* Update content for promotion contexts

Added walkthrough example for promotion context

* Update promotion-context-promotion-workflows.md

* Update hook-slack-notification-example.png

* Update promotion-context-promotion-workflows.md

* Add promotion context example

Added example template to define promotion context and use in  promotion hook

* Update overview title

* Update promotion-context-promotion-workflows.md

* Add feedback from review

Implemented feedback from Francisco's review

* Update product-releases.md

* Add note on early access

Added note on early access availability for publish

Author: NimRegev

_data/argohub-nav.yml

@@ -255,11 +255,17 @@
     - title: Promotion setup guidelines
       url: "/create-promotion-sequence"
     - title: Promotion Flows
-      url: "/promotion-flow"     
+      url: "/promotion-flow"
     - title: Promotion Policies
       url: "/promotion-policy"  
     - title: Promotion Workflows
-      url: "/promotion-workflow"  
+      url: "/promotion-workflow"
+    - title: Service accounts for Promotion Workflows
+      url: "/service-accounts-promotion-workflows"      
+    - title: Promotion hooks
+      url: "/promotion-hooks"          
+    - title: Promotion contexts in promotion hooks
+      url: "/promotion-context-promotion-workflows"     
     - title: Product promotion settings
       url: "/product-promotion-props"          
     - title: Promotion entity YAMLs 

_data/nav.yml

@@ -434,11 +434,17 @@
     - title: Promotion setup guidelines
       url: "/create-promotion-sequence"
     - title: Promotion Flows
-      url: "/promotion-flow"     
+      url: "/promotion-flow"  
     - title: Promotion Policies
       url: "/promotion-policy"  
     - title: Promotion Workflows
       url: "/promotion-workflow"  
+    - title: Service accounts for Promotion Workflows
+      url: "/service-accounts-promotion-workflows"      
+    - title: Promotion hooks
+      url: "/promotion-hooks"          
+    - title: Promotion contexts in promotion hooks
+      url: "/promotion-context-promotion-workflows"       
     - title: Product promotion settings
       url: "/product-promotion-props"          
     - title: Promotion entity YAMLs 

_docs/promotions/create-promotion-sequence.md

@@ -14,7 +14,7 @@ Promotions are a critical part of continuous delivery, enabling you to move chan
 
 ## Prerequisites
 1. [Configuration Runtime]({{site.baseurl}}/docs/installation/gitops/configuration-runtime/)  
-   The Configuration Runtime is a GitOps Runtime that stores promotion-related entities.  
+   The Configuration Runtime is a GitOps Runtime that stores configuration for GitOps promotion entities.  
     * Designate at least one GitOps Runtime as the Configuration Runtime.  
     * If no GitOps Runtime has been designated as such, Codefresh assigns one of the existing Runtimes.
 
@@ -24,10 +24,12 @@ Promotions are a critical part of continuous delivery, enabling you to move chan
 1. [User permissions]({{site.baseurl}}/docs/administration/account-user-management/gitops-abac/)  
   Users need permissions to create Promotion Workflows, configure promotion settings for products, and trigger promotions.
 
+
+## Setup tasks
 1. [Create environments]({{site.baseurl}}/docs/environments/create-manage-environments/#create-environments)  
   Environments define the starting point and destination of promotions.   
   A promotion requires at least two environments:
-    * Trigger environment, the source of the changes being promoted
+    * Trigger Environment, the source of the changes being promoted
     * Target environment, to which to promote the changes
 
 1. [Create applications]({{site.baseurl}}/docs/deployments/gitops/create-application/#create-an-argo-cd-application)  
@@ -43,26 +45,39 @@ Promotions are a critical part of continuous delivery, enabling you to move chan
 
 1. [Create Promotion Workflows]({{site.baseurl}}/docs/promotions/promotion-workflow/)  
   Promotion Workflows (Argo Workflows) automate environment-specific tests and validations before and after promotion.
-    * Create and use Promotion Workflows to run smoke tests, database validation, and other requirements to verify readiness.
+    * Create Promotion Workflows to run smoke tests, database validation, and any other requirements to verify readiness of each application in an environment.
+
+1. [Create Promotion Workflows with hooks]({{site.baseurl}}/docs/promotions/promotion-hooks/)
+  Promotion hooks provide promotion status and custom information for releases and environments during the Promotion Flow.
+    * Create hooks in Promotion Workflows to implement actions such as Slack notifications
+    * Define and export promotion contexts in hooks to expose and pass custom parameters such as Jira ID 
+
 
 1. [Define Promotion Policies]({{site.baseurl}}/docs/promotions/promotion-policy/)    
   Promotion Policies govern promotion behavior for environments enforcing rules, checks, and validations.
     * Define policies that combine Promotion Workflows with promotion actions such as commits, pull requests
     * The policy mechanism merges relevant settings from global policies according to priority, enforcing automated governance
 
+
 1. [Create Promotion Flows]({{site.baseurl}}/docs/promotions/promotion-flow/)  
   Promotion Flows orchestrate the sequence of actions required to move and deploy changes through multiple environments.    
     * Automatically integrate environments, products, Promotion Workflows, and Promotion Policies into a structured promotion process
+    * Assign promotion hooks to track release and environment statuses for product releases
     * Reuse Promotion Flows across products for consistent and reliable promotions
+
+
 
 1. [Customize promotions for products]({{site.baseurl}}/docs/promotions/product-promotion-props/) 
   After setting up promotion entities, configure additional promotion settings at the product level.  
     * Promotion Templates to define attributes to be promoted across the product's applications
     * Promotion Flows valid for the product and trigger conditions for each flow
 
+## Trigger and monitor promotions
+
 1. [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/)  
   Trigger the promotion manually or automatically.  
-  
+
+
 1. [Monitor promotion releases for products]({{site.baseurl}}/docs/promotions/product-releases/)  
   Monitor deployment progress as applications move through the promotion sequence.   
   * Use the Releases feature for products to monitor deployments

_docs/promotions/product-releases.md

@@ -7,12 +7,11 @@ toc: true
 
 
 
-
+## Releases for promotions in GitOps
 Releases in Codefresh GitOps offer a consolidated view of the deployment lifecycle for a product as it progresses through environments during a promotion. They enable you to track, visualize, and analyze changes from the initial trigger to the final deployment, providing comprehensive insights for all stakeholders.
 
 A release is automatically created whenever a promotion is triggered for a product, either manually or through an automated flow. This ensures every change is documented and linked to its promotion lifecycle, giving teams complete visibility into their deployment processes.
 
-## Releases in GitOps
 In the context of GitOps, a release captures the progression of a product as it is promoted through environments. The release reflects the collective state of all environments and workflows involved in deploying a change, from the initial trigger to the final target environment, whether production or another specified target.
 
 
@@ -28,7 +27,7 @@ max-width="60%"
 %}
 
 ### Why Releases matter
-Whether you are a product manager or an application developer, Releases offer:
+Whether you are a product manager or an application developer, releases offer:
 * Lifecycle visualization: Clearly track the deployment lifecycle of a product
 * Integrated change list: Access a unified list of changes leading to a deployment
 * Deployment status: Monitor ongoing deployments and quickly identify issues
@@ -64,7 +63,7 @@ There are two key aspects of tracking deployments for a product through releases
 
 ##### Release promotion flow 
 Track the release visually to monitor its progression through each phase of the promotion lifecycle across environments.  
-Specific Release views centralizes all information, allowing you to:  
+Release views centralizes all information, allowing you to:  
 * Identify and resolve deployment issues without switching between tools
 * Access everything you need to troubleshoot errors in one place.
 
@@ -82,7 +81,7 @@ Release notes compile changes from various sources into a single view, enabling
 See [Analyze change history in Release Notes](#analyze-change-history-in-release-notes).
 
 
-## View Releases for products
+## View releases for products
 
 The Releases tab for a product displays the releases for that product, whether successful or failed.
 
@@ -145,7 +144,7 @@ max-width="60%"
 The header in the Releases page summarizes the change that triggered the promotion, the overall status of the release, and the count of failed, successful, running, and pending environments.
 
 >**NOTE:**  
-The commit details are always for the trigger environment that initiated the promotion.
+The commit details are always for the Trigger Environment that initiated the promotion.
 
 {% include 
 image.html 
@@ -186,8 +185,8 @@ max-width="60%"
 
 ## Environments in product releases
 
-The graphical view of the different environments defined in the Promotion Flo allows you to:
-* Understand the interconnections between the environments, whether sequential or parallel.
+The graphical view of the different environments defined in the Promotion Flow allows you to:
+* Understand the interconnections between the environments, whether sequential or parallel
 * Visualize the dependencies between environments to see how changes propagate through the deployment process
 
 Each environment is color-coded to indicate the overall status of the promotion for that environment. 
@@ -253,8 +252,9 @@ If there is an update that triggers a Pre- or Post-Action Workflow within an env
 For example, if an update in the `staging` environment triggers the `echo-pre-action` Pre-Action Workflow, and a later update in the same environment also triggers the same `echo-pre-action` Pre-Action Workflow, the earlier instance is terminated, and the later instance continues to run. 
 
 
+## Promotion Hooks in product release
+The **Show/Hide Hooks** toggle button in the Release view displays/hides the [promotion hooks]({{site.baseurl}}/docs/promotions/promotion-hooks/) assigned to the Promotion Flow.
 
-<!--- NIMA: how will it be shown in the releases tab? -->
 
 ## Promotion Workflows in product releases
 

_docs/promotions/promotion-components.md

@@ -98,12 +98,18 @@ These entities provide additional control and automation, enabling advanced mult
     <td>Users with ABAC permissions</td>
     <td><a href="https://codefresh.io/docs/docs/products/configure-product-settings/">Promotion settings for products</a></td>
   </tr>
-    <tr>
+  <tr>
     <td><strong>Promotion Workflow</strong></td>
-    <td>An Argo Workflow which runs tests and validations during promotion for each environment. Promotion Workflows can include smoke tests, rollback mechanisms, database validation checks, performance checks, and more.</td>
+    <td>An Argo Workflow which runs tests and validations during promotion for each application within an environment. Promotion Workflows can include smoke tests, rollback mechanisms, database validation checks, performance checks, and more.</td>
     <td>Users with ABAC permissions</td>
     <td><a href="https://codefresh.io/docs/docs/promotions/promotion-workflow/">Promotion Workflows</a></td>
   </tr>
+  <tr>
+    <td><strong>Promotion hooks</strong></td>
+    <td>Promotion hooks are configured in Promotion Workflows to run at the start or end of a product release, or at the start or end of promotions in environments. Promotion hooks can include notifications and actions such as sending Slack messages or custom issue-tracking information based on the status of the promotion for release or environment.</td>
+    <td>Users with ABAC permissions</td>
+    <td><a href="https://codefresh.io/docs/docs/promotions/promotion-hooks/">Promotion Workflows</a></td>
+  </tr>
   <tr>
     <td><strong>Promotion Policy</strong></td>
     <td>Defines promotion behavior for environments by combining Promotion Workflows (tests and validations), with the promotion action such as commits or pull requests.</td>

_docs/promotions/promotion-context-promotion-workflows.md

@@ -140,6 +140,7 @@ To ensure a successful promotion, the product must include an application in eac
 #### Application sync and health status 
 Applications must be **Synced** and **Healthy** for a promotion to succeed.
 
+
 #### Multiple applications in a target environment
 If a target environment includes multiple applications for the same product—segmented for example by region, tenant, or other criteria—each application in that environment is updated with changes from the source environment. 
 
@@ -149,12 +150,28 @@ Although this behavior may seem intuitive, it’s crucial to recognize that each
 
 Adding or deleting files from applications in target environments does not affect the Promotion Flow. The promotion mechanism simply retains the added/deleted files as they are in the target environments.
 
+### Hooks in Promotion Flows
+Promotion hooks provide promotion status and custom information for releases and environments during the Promotion Flow.
+* Hooks are configured in Promotion Workflows and assigned to start/end of the release or specific environments in the Promotion Flow.
+* All hooks receive a default set of arguments to configure actions or notifications based on success or failure.
+* Promotion contexts within hooks when exported, expose custom parameters not natively available to the hooks. For example, you can link a Jira issue by creating a promotion context with the Jira ID and exporting it.
+
 
 ### Promotion Policy settings
 
-For each environment, you can explicitly set the Promotion Policy that defines governs promotion behavior for the environment through the Promotion Action (required), and  Pre- and Post-Action Workflows.  
+For each environment, you can explicitly set the Promotion Policy that defines governs promotion behavior for the environment through the Promotion Action (required), and Pre- and Post-Action Workflows.  
 You can also preview Policy settings by product before the flow is triggered. 
 
+{% include 
+image.html 
+lightbox="true" 
+file="/images/gitops-promotions/hooks/promotion-hooks-in-flow.png" 
+url="/images/gitops-promotions/hooks/promotion-hooks-in-flow.png"
+alt="Promotion hooks in Promotion Flow" 
+caption="Promotion hooks in Promotion Flow"
+max-width="60%"
+%}
+
 #### Inline vs. global Promotion Policy settings
 
 When you create or edit a Promotion Flow, the Flow Builder displays the Pre- and Post-Action Workflows, and the Promotion Action available for selection. 
@@ -229,7 +246,7 @@ Visually design and create the flow by selecting environments, Promotion Actions
     * **Flow Timeout**: The maximum duration allowed for the Promotion Flow to complete execution after being triggered, before it is automatically terminated. If not specified, the default timeout is 1 day (24 hours).
     * **Version**: (Optional) The version of the Promotion Flow. This is manually defined and manually updated, and is useful to indicate changes in the same flow.  
 1. In **Select Trigger Environment**, click {::nomarkdown}<img src="/images/icons/plus-icon.png" display=inline-block>{:/} to see the list of available environments:
-    * Select an existing environment, select it and click **Add**. 
+    * Select an existing environment and click **Add**. 
     * To create a new environment, click **Add New Environment**. 
 
 {% include 
@@ -243,7 +260,7 @@ max-width="50%"
 %}
 
 {:start="5"}
-1. Optional. To add a trigger workflow to validate the trigger environment after the change and commit action, mouse over the left of the environment node, and click {::nomarkdown}<img src="../../../../images/icons/flow-builder-add-workflow.png" display=inline-block>{:/}, and select a Workflow.
+1. Optional. To assign a workflow to validate the trigger environment after the change and commit action, mouse over the left of the environment node, and click {::nomarkdown}<img src="../../../../images/icons/flow-builder-add-workflow.png" display=inline-block>{:/}, and select a Workflow.
     * To apply a trigger workflow from global Promotion Policy settings, click **Account-level Promotion Policy**.  
     * To add a new Promotion Workflow as the trigger workflow, click **Add New Workflow**. 
 
@@ -260,7 +277,6 @@ max-width="50%"
 {:start="6"}
 1. To add a target environment to promote to, either sequentially or in parallel, mouse over the right of the environment to add to, click {::nomarkdown}<img src="../../../../images/icons/plus-icon.png" display=inline-block>{:/} and then select the environment or environments.
   The example below shows two environments, `qa` and `staging` as parallel environments to `dev`.
-  <!--- To add parallel environments, click {::nomarkdown}<img src="../../../../images/icons/plus-icon.png" display=inline-block>{:/} on the right of the previous environment. For example, to add `qa` and `staging` as parallel environments to `dev`, you would click {::nomarkdown}<img src="../../../../images/icons/plus-icon.png" display=inline-block>{:/} on the `dev` environment.  -->
 
 {% include 
 image.html 
@@ -319,7 +335,9 @@ caption="Add Pre-/Post-Action Workflows"
 max-width="60%"
 %}
 
-{:start="10"}
+1. To assign promotion hooks to the start or release or to an environment do 
+
+{:start="11"}
 1. Click **Save Promotion Flow** on the top-right.
   The Name and Description are populated from the Settings. The flow's YAML version on the right lists the environment sequence.
 1. To confirm, click **Save**. 
@@ -400,6 +418,7 @@ TBD
 -->
 
 ## Related articles
+[Hooks in Promotion Flows]({{site.baseurl}}/docs/promotions/promotion-hooks/)  
 [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/)   
 [Tracking product promotions through releases]({{site.baseurl}}/docs/promotions/product-releases/)  
 [Promotions: Setup & configuration guidelines]({{site.baseurl}}/docs/promotions/create-promotion-sequence/)  

_docs/promotions/promotion-flow.md

@@ -341,6 +341,7 @@ For more information, see [Promotion Workflows in Product Releases]({{site.baseu
 ## Related articles
 [Configure Promotion Flows]({{site.baseurl}}/docs/promotions/promotion-flow/)  
 [Configure Promotion Workflows]({{site.baseurl}}/docs/promotions/promotion-workflow/)  
+[Hooks in Promotion Flows]({{site.baseurl}}/docs/promotions/promotion-hooks/)  
 [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/)   
 [Tracking product releases]({{site.baseurl}}/docs/promotions/product-releases/)  
 [Promotions: Setup & configuration guidelines]({{site.baseurl}}/docs/promotions/create-promotion-sequence/)  

_docs/promotions/promotion-hooks.md

@@ -45,12 +45,14 @@ You can run Promotion Workflows at different stages of the promotion:
 See [Creating Promotion Workflows](#create-promotion-workflows) and [Promotion Workflow examples](#promotion-workflow-examples). 
 
 
-
 ##### Arguments in Pre-Action and Post-Action Workflows
 Codefresh passes arguments retrieved during the promotion process to both Pre- and Post-Action Workflows. You can use these arguments to dynamically adjust requirements throughout the promotion lifecycle.  
 
 See [Parameters in Pre-Action and Post-Action Workflows](#parameters-in-pre-action-and-post-action-workflows).
 
+
+
+
 ## Using Promotion Workflows in promotions
 After creating Promotion Workflows, depending on the level of control and scalability you need, you can use them through:
 
@@ -75,7 +77,11 @@ See [Annotation attribute for Promotion Workflows](#annotation-attribute-for-pro
 ## Promotion Workflow YAML
 Once configured and committed, Promotion Workflow settings are saved as a CRD (Custom Resource Definition) within the Shared Configuration Repository in the GitOps Runtime selected as the Configuration Runtime.  
 The path in the Shared Configuration Repo is `<gitops-runtime>/<shared-configuration-repo>/resources/control-planes/promotion-workflows/`.  
-See [Shared Configuration Repository]({{site.baseurl}}/docs/installation/gitops/shared-configuration/) and [Designating Configuration Runtimes]({{site.baseurl}}/docs/installation/gitops/configuration-runtime/).   
+See [Shared Configuration Repository]({{site.baseurl}}/docs/installation/gitops/shared-configuration/) and [Designating Configuration Runtimes]({{site.baseurl}}/docs/installation/gitops/configuration-runtime/). 
+
+## Service accounts for Promotion Workflow
+
+Every Promotion Workflow requires a service account to run. The service account grants the necessary permissions for actions in the target cluster. For details, see [Service accounts for Promotion Workflows]({{site.baseurl}}/docs/promotions/service-accounts-promotion-workflows/).
 
 ## Annotation attribute for Promotion Workflows
 An Argo Workflow or Workflow Template is classified as a Promotion Workflow when it includes the following annotation:  
@@ -777,85 +783,65 @@ caption="Workflow execution instances"
 max-width="60%"
 %}
 
+## Promotion hooks in Promotion Workflows 
+Promotion hooks are special steps you can configure within Promotion Workflows to expose promotion status and trigger custom actions during a Promotion Flow. Compared to Pre- and Post-Action Promotion Workflows that run on applications within environments, hooks provide tailored information about the success or failure of a release or environment, and can send notifications, execute external logic, or update external systems.
 
+Promotion hooks run at specific stages when a Promotion Flow is triggered manually or automatically. They can be reused across releases and environments to standardize processes and improve visibility across your GitOps workflows.
 
+Hooks have access to a default set of promotion arguments, such as the product, release ID, and commit SHA. You can also pass custom information, such as Jira ticket IDs, Slack channels, or release notes, by creating and exporting a promotion context within the workflow.
 
-<!--- ### View/analyze Workflow instances
-
-
-
-1. In the Codefresh UI, from the sidebar, select **Promotion Workflows**.
-1. Click a Promotion Workflow, and then click the **Workflows** tab to see its instances.
-1. If needed, filter by Status, Target Environment, Product, or Application.
-1. To visualize steps and view detailed information, click **View Workflow Details**.
-
-{% include 
-image.html 
-lightbox="true" 
-file="/images/gitops-promotions/workflows/workflow-instance-details.png" 
-url="/images/gitops-promotions/workflows/workflow-instance-details.png"
-alt="Detailed view of workflow execution instance" 
-caption="Detailed view of workflow execution instance"
-max-width="60%"
-%}
-
-
-
-### Workflow summary
-
-SCREENSHOT
-
-The table highlights key information you can find in the Summary tab for a workflow.
-
-{: .table .table-bordered .table-hover}
-|  Workflow Summary    | Description                   | 
-| --------------       | ------------------------------|  
-| **Errors**               | Displayed when the Workflow instance has at least one failed step.   |  
-| **Summary**              | Namespace, memory and CPU resource usage, and execution context of the workflow.<br>If triggered by a parent workflow, displays the link to that workflow.|  
-| **Manifests**            | The version of the manifest used for the specific Workflow execution. This may not be the same version currently displayed in the Manifest tab. Useful to troubleshoot failed steps and errors in the execution instance. |  
-| **Labels**            | Labels assigned to the workflow. Useful to filter, search, organize workflow executions. <br>Examples:<br>`codefresh.io/app-name: trioapp-qa`, `codefresh.io/app-namespace: gitops`.| 
-| **Parameters**            | The inputs set/modified for the specific execution. <br>Examples:<br>`Threshold: 50`, `Nb: 100`.| 
-| **Artifacts**            | The outputs if any generated by a workflow step, and can be logs, test-reports, binaries or any other type of file. Each artifact is associated with a specific step in the workflow. For example: `main-logs: smoketests-k9ss6`.| 
-
-
-
-###  Workflow actions
-Depending on the status of the workflow instance, you can do the following: 
-
-
-
-SCREENSHOT 
-Remove unused or legacy workflow instances. Deleting a workflow instance removes it from the list of executions. The Promotion Workflow itself is not changed. 
-
-### Workflow steps
-Visualize the steps in the Workflow. For additional information on the step, click the step to open the pull-out panel.
-
-{% include 
-image.html 
-lightbox="true" 
-file="/images/gitops-promotions/workflows/workflow-step-details.png" 
-url="/images/gitops-promotions/workflows/workflow-step-details.png"
-alt="Workflow instance step detailed view" 
-caption="Workflow instance step detailed view"
-max-width="60%"
-%}
-
-
-
-### Workflow logs
-
+The following example shows an on-start hook in a Promotion Workflow that sends a Slack notification at the start of a product release or environment promotion. 
 
 
-{% include 
-image.html 
-lightbox="true" 
-file="/images/gitops-promotions/workflows/workflow-logs.png" 
-url="/images/gitops-promotions/workflows/workflow-logs.png"
-alt="Workflow instance logs" 
-caption="Workflow instance logs"
-max-width="60%"
-%}
--->
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: WorkflowTemplate
+metadata:
+  name: on-start-hook
+  annotations:
+    codefresh.io/workflow-origin: promotion
+    version: 0.0.1
+spec:
+  arguments:
+    parameters:
+      - name: RELEASE_URL
+      - name: PRODUCT_NAME
+      - name: COMMIT_SHA
+      - name: PROMOTION_FLOW_NAME
+      - name: RELEASE_ID
+  serviceAccountName: hook
+  entrypoint: send-message
+  templates:
+    # Send-message template
+    - name: send-message
+      retryStrategy:
+        limit: "1"
+        retryPolicy: "Always"
+        backoff:
+          duration: "5s"
+      inputs:
+        parameters:
+          - name: MODE
+            value: "simple"
+          - name: SLACK_HOOK_URL
+            value: <put here your webhook url>
+          - name: SLACK_TEXT
+            value: Successfully started a release flow {{workflow.parameters.RELEASE_URL}}!  
+      container:
+        name: main
+        imagePullPolicy: Always
+        image: quay.io/codefreshplugins/argo-hub-slack-send-message:0.0.2-main
+        command:
+          - node
+          - /usr/src/app/index.js
+        env:
+          - name: MODE
+            value: '{{ inputs.parameters.MODE }}'
+          - name: SLACK_HOOK_URL
+            value: '{{ inputs.parameters.SLACK_HOOK_URL }}'
+          - name: SLACK_TEXT
+            value: '{{ inputs.parameters.SLACK_TEXT }}'
+```
 
 
 ## Promotion Workflows in product release views

_docs/promotions/promotion-policy.md

@@ -0,0 +1,107 @@
+---
+title: "Service account for Promotion Workflows"
+description: "Understand the service account and role requirements for Promotion Workflows"
+group: promotions
+toc: true
+---
+
+{{site.data.callout.callout_tip}}
+Available as part of the early access program.
+{{site.data.callout.end}}
+
+## Service accounts & service account roles for Promotion Workflows
+Service accounts are essential for all types of Promotion Workflows in GitOps Cloud. These accounts provide the necessary permissions for workflows to interact with clusters and other resources during the promotion process, including when hooks are used. 
+
+When a GitOps Runtime is installed, GitOps Cloud automatically creates the required service account, service account role, and binding to support Promotion Workflows. 
+
+
+## Default service account and service role 
+
+* **Service account**  
+  `cf-default-promotion-workflows-sa` with the required role and role binding.  
+    * Workflow template manifests reference this service account. 
+    * When you create a Promotion Workflow from the UI, the service account is added automatically to the YAML. 
+    * If you're creating the Promotion Workflow in Git, you must add the service account manually.
+
+* **Service account role**  
+  `cf-default-promotion-workflows-role`, the default role for promotion hooks, automatically bound to the service account `cf-default-promotion-workflows-sa`.  
+
+* **RBAC permissions for service account role**   
+  The following Role-Based Access Control (RBAC) permissions are required to allow hooks to retrieve and update release and promotion details securely:    
+    * `GET`  
+    * `WATCH`  
+    * `PATCH`  
+
+
+## Custom options for service account and role
+
+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`.
+
+## Example of a service account and role
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: hook
+  annotations:
+    argo-hub/version: '0.0.2'
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: hook
+  annotations:
+    argo-hub/version: '0.0.2'
+rules:
+  - apiGroups:
+      - ""
+    resources:
+      - pods
+    verbs:
+      - get
+      - watch
+      - patch
+  - apiGroups:
+      - ""
+    resources:
+      - pods/log
+    verbs:
+      - get
+      - watch
+  - apiGroups:
+    - argoproj.io
+    resources:
+    - workflowtaskresults
+    verbs:
+    - create
+    - get
+    - list
+    - patch
+    - watch   
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: hook
+  annotations:
+    argo-hub/version: '0.0.2'
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: hook
+subjects:
+  - kind: ServiceAccount
+    name: hook
+```
+
+## Related articles
+[Configure Promotion Workflows]({{site.baseurl}}/docs/promotions/promotion-workflow/)  
+[Configure hooks in Promotion Workflows]({{site.baseurl}}/docs/promotions/promotion-hooks/)  
+[Configure Promotion Flows]({{site.baseurl}}/docs/promotions/promotion-flow/)  

_docs/promotions/promotion-workflow.md

@@ -3,7 +3,8 @@ title: "YAML specs"
 description: "YAML specifications for promotion entities"
 group: promotions
 redirect-from: 
- - /docs/promotions/entities/yaml
+ - /docs/promotions/configuration/
+ - /docs/promotions/entities/yaml/
 toc: true
 ---
 

_docs/promotions/service-accounts-promotion-workflows.md

@@ -9,7 +9,7 @@ toc: true
 ---
 
 
-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.
 
@@ -24,22 +24,27 @@ kind: PromotionFlow
 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
+
 ```
 
 ## Promotion Flow YAML field descriptions
@@ -51,12 +56,18 @@ spec:
 |`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`| 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.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.policy.preAction`        | The name of the Promotion Workflow to execute _before_ `spec.steps.policy.action`.                      | string  | Optional          |
-| `spec.steps.policy.postAction`       | The name of the Promotion Workflow to execute _after_ `spec.steps.policy.action`.                         | string  | Optional          |  
+|`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><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.hooks`       | The promotion hooks to run for the _environment_, and can be any of the following:{::nomarkdown}<ul><li><code class="highlighter-rouge">onStart</code>: The promotion hook to run when the promotion reaches the environment.</li><li><code class="highlighter-rouge">onSuccess</code>: The promotion hook to run when the promotion completes successfully in the environment.</li><li><code class="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><code class="highlighter-rouge">onStart</code>: The promotion hook to run when the release is initiated.</li><li><code class="highlighter-rouge">onSuccess</code>: The promotion hook to run when the release completes successfully.</li><li><code class="highlighter-rouge">onFail</code>: The promotion hook to run when the release fails.</li></ul>{:/}| string  | Optional          |
+
+
 
 ## Related articles
+[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/)  

_docs/promotions/yaml.md

@@ -0,0 +1 @@
+../../_docs/promotions/promotion-context-promotion-workflows.md

_docs/promotions/yaml/promotion-flow-crd.md

@@ -0,0 +1 @@
+../../_docs/promotions/promotion-hooks.md

_gitops/promotions/promotion-context-promotion-workflows.md

@@ -0,0 +1 @@
+../../_docs/promotions/service-accounts-promotion-workflows.md

_gitops/promotions/promotion-hooks.md

@@ -65,7 +65,6 @@
   "/docs/products/promotion-version-properties/": "/gitops/products/promotion-version-properties/",
   "/docs/products/releases-in-products/": "/gitops/products/releases-in-products/",
   "/docs/promotions/create-promotion-sequence/": "/gitops/promotions/create-promotion-sequence/",
-  "/docs/promotions/entities/": "/gitops/promotions/entities/",
   "/docs/promotions/product-promotion-props/": "/gitops/promotions/product-promotion-props/",
   "/docs/promotions/product-releases/": "/gitops/promotions/product-releases/",
   "/docs/promotions/promotion-components/": "/gitops/promotions/promotion-components/",
@@ -116,7 +115,10 @@
   "/docs/installation/gitops/runtime-argocd-admin-api-token/": "/gitops/gitops-runtimes/runtime-argocd-admin-api-token/",
   "/docs/installation/gitops/runtime-install-ingress-service-mesh-access-mode/": "/gitops/gitops-runtimes/runtime-install-ingress-service-mesh-access-mode/",
   "/docs/promotions/getting-started/": "/gitops/promotions/getting-started/",
+  "/docs/promotions/promotion-hooks/": "/gitops/promotions/promotion-hooks/",
   "/docs/installation/gitops/runtime-troubleshooting/": "/gitops/gitops-runtimes/runtime-troubleshooting/",
   "/docs/products/promotion-concurrency/": "/gitops/products/promotion-concurrency/",
+  "/docs/promotions/promotion-context-promotion-workflows/": "/gitops/promotions/promotion-context-promotion-workflows/",
+  "/docs/promotions/service-accounts-promotion-workflows/": "/gitops/promotions/service-accounts-promotion-workflows/",
   "/docs/installation/gitops/runtime-install-with-new-argo-cd/": "/gitops/gitops-runtimes/runtime-install-with-new-argo-cd/"
 }