Repository: codefresh-io/docs.codefresh.io
Pull request #1277: Gitops promotion hooks
Author: login: NimRegev
Created: 2025-04-09T08:41:30Z | Merged: 2025-05-14T08:52:37Z

First dart of promotion hooks


Diff:
diff --git a/_data/argohub-nav.yml b/_data/argohub-nav.yml
index 394f6f85e..17e4cbbf1 100644
--- a/_data/argohub-nav.yml
+++ b/_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 
diff --git a/_data/nav.yml b/_data/nav.yml
index db8c8e51d..d6f6c23ef 100644
--- a/_data/nav.yml
+++ b/_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 
diff --git a/_docs/promotions/create-promotion-sequence.md b/_docs/promotions/create-promotion-sequence.md
index c2094da1e..fca9dee3e 100644
--- a/_docs/promotions/create-promotion-sequence.md
+++ b/_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
diff --git a/_docs/promotions/product-releases.md b/_docs/promotions/product-releases.md
index 560384eee..4c576d68d 100644
--- a/_docs/promotions/product-releases.md
+++ b/_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
 
diff --git a/_docs/promotions/promotion-components.md b/_docs/promotions/promotion-components.md
index 35d788584..3202d5ff2 100644
--- a/_docs/promotions/promotion-components.md
+++ b/_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>
diff --git a/_docs/promotions/promotion-context-promotion-workflows.md b/_docs/promotions/promotion-context-promotion-workflows.md
new file mode 100644
index 000000000..93b6c1db3
--- /dev/null
+++ b/_docs/promotions/promotion-context-promotion-workflows.md
@@ -0,0 +1,427 @@
+---
+title: "Promotion contexts for promotion hooks"
+description: "Use promotion contexts to expose custom parameters to hooks in Promotion Flows"
+group: promotions
+toc: true
+---
+
+
+{{site.data.callout.callout_tip}}
+Available as part of the early access program.
+{{site.data.callout.end}}
+
+## About promotion contexts
+
+Promotion Workflows with hooks in Codefresh GitOps have access to a standard set of [default parameters]({{site.baseurl}}/docs/promotions/promotion-hooks/#default-arguments-in-promotion-hooks), such as the release ID, current release version, product, and commit SHA. When you define these parameters in the hook as input parameters, their values are dynamically retrieved from the ongoing promotion.
+
+Because promotion hooks run within GitOps Runtimes in your own clusters, custom parameters such as Jira ticket IDs, approver names, or Slack channel names are not automatically exposed to the promotion process. To use these custom parameters in hooks, you have two options:
+* Define the custom parameters and their values manually in the workflow
+* Use a **promotion context** for a more flexible and dynamic approach
+
+A **promotion context** is a user-defined JSON object that allows you to pass custom values between promotion hooks in the same Promotion Flow. See [Creating and exporting a promotion context](#creating-and-exporting-a-promotion-context) and [Example of Promotion Workflow with promotion context](#example-of-promotion-workflow-with-promotion-context).
+
+Defining a promotion context with the custom parameters and then **exporting the context** makes these custom values available to all subsequent hooks in the same Promotion Flow. Each hook can access and use the values from the promotion context as needed.  
+Using promotion contexts enables scenarios like notifying specific Slack channels or linking Jira tickets to releases. See [How promotion context works during execution](#how-promotion-context-works-during-execution).  
+
+To see a practical example, follow the [Walkthrough: Using promotion hooks in Promotion Flows to handle promotion failures](#walkthough-using-promotion-hooks-in-promotion-flows-to-handle-promotion-failures), where you create different Promotion Workflows with hooks, define a promotion context in a workflow, and assign hooks at different stages of the Promotion Flow.
+
+
+## Creating and exporting a promotion context 
+You can use any method to create a promotion context as a JSON object and define the parameters you need.  
+The key step is **exporting the promotion context**, as this makes its content available to the Promotion Workflow. The content is saved in the platform. 
+
+When you export the promotion context, `name.outputs.parameters` must be set to `PROMOTION_CONTEXT` and _cannot be changed_. See [Example of Promotion Workflow with promotion context](#example-of-promotion-workflow-with-promotion-context).
+
+
+
+## Example of Promotion Workflow with promotion context  
+The example creates a promotion context `PROMOTION_CONTEXT` as a JSON object and exports it as an output parameter.
+* The promotion context defines `JIRA_ISSUE_SOURCE_FIELD` and `JIRA_BASE_URL` 
+* Writes the context to a file `/tmp/promotion-context.txt`
+* Adds `PROMOTION_CONTEXT` to `outputs.parameters.name`, defines `globalName` as the name of the promotion context, and in `valueFrom.path` specifies the file path where the promotion context JSON was saved for GitOps Cloud to retrieve and pass on to subsequent Promotion  Workflows.
+
+  
+```yaml 
+...
+spec:
+...
+    - name: set-promotion-context
+      serviceAccountName: hook
+      inputs:
+        parameters:
+          - name: JIRA_ISSUE_SOURCE_FIELD
+          - name: JIRA_BASE_URL
+      script:
+        image: alpine
+        command:
+          - sh
+        source: |
+            export JIRA_ISSUE_BASE_URL="{{inputs.parameters.JIRA_BASE_URL}}"
+            export JIRA_ISSUE_SOURCE_FIELD="{{inputs.parameters.JIRA_ISSUE_SOURCE_FIELD}}"
+            PROMOTION_CONTEXT=$(echo "{\"JIRA_ISSUE_URL\": \"${JIRA_ISSUE_BASE_URL}/browse/${JIRA_ISSUE_SOURCE_FIELD}\"}")
+            echo "$PROMOTION_CONTEXT" > /tmp/promotion-context.txt
+      outputs:
+        parameters:
+          - name: PROMOTION_CONTEXT  #  cannot be changed
+            globalName: PROMOTION_CONTEXT # name of promotion context
+            valueFrom:
+              path: /tmp/promotion-context.txt
+...
+``` 
+
+## How promotion context works during execution
+
+When a hook exports a promotion context, the promotion mechanism passes the parameters defined within the context to all subsequent hooks in the Promotion Flow.  regardless of whether these hooks include promotion contexts. The promotion context is saved in the GitOps Cloud platform.
+
+This ensures:
+* Context values persist across environments and clusters
+* If a hook redefines a parameter already in the context, the new value takes precedence
+
+
+##### Triggering the first promotion hook
+When the Promotion Flow is triggered and a product release is created, the promotion mechanism:
+* Passes the default input parameters defined (release ID, commit SHA for example) to all hooks configured for the Promotion Flow
+* Initializes the promotion context, if defined and exported, with custom values 
+
+##### Triggering subsequent promotion hooks
+As the Flow progresses, the promotion mechanism:
+* Retrieves the promotion context exported by the previous hook
+* Passes the promotion context automatically to the next hook
+* If the current hook defines one or more of the parameters from the promotion context as input parameters, their values are taken from the context
+* If the current hook also exports a promotion context with the same parameter, the value from the current hook’s promotion context overrides the value from the previous context
+  
+
+
+{% include 
+image.html 
+lightbox="true" 
+file="/images/gitops-promotions/hooks/promotion-context-behavior.png" 
+url="/images/gitops-promotions/hooks/promotion-context-behavior.png"
+alt="Promotion context shared across promotion hooks in Promotion Flow" 
+caption="Promotion context shared across promotion hooks in Promotion Flow"
+max-width="60%"
+%}
+
+
+## Walkthrough: Using promotion hooks in Promotion Flows to handle promotion failures
+
+Promotion hooks are designed to take action or provide information related to a release and its environments when a promotion is triggered.
+In this walkthrough, you'll see how to create and export a promotion context, and create promotion hooks and use the promotion context to handle promotion failures, ensuring that stakeholders are notified with the right information—without needing to monitor the release manually.
+
+This walkthrough covers:
+* [Creating a Promotion Workflow template with a generic promotion context](#create-promotion-workflow-template-with-generic-promotion-context)
+* [Creating Promotion Workflows with hooks](#create-promotion-workflows-with-hooks)
+* [Assigning hooks in Promotion Flow](#assign-hooks-to-promotion-flow)
+* [Triggering hooks in Promotion Flow](#result-of-triggering-hooks-1-and-2-work-in-the-promotion-flow)
+
+### Create Promotion Workflow template with generic promotion context
+
+This Promotion Workflow template:
+* Defines a generic promotion context as a key-value map in JSON format. 
+* Uses a single parameter, `context-params`, which is a JSON string of arbitrary keys and values, such as metadata for the promotion, Jira ticket references, base URLs.
+* Exports the promotion context as `PROMOTION_CONTEXT`, ensuring that it's available to any promotion hook which references it.
+
+##### Example YAML
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: WorkflowTemplate
+metadata:
+  name: set-promotion-context
+  annotations:
+    version: 0.0.1
+    codefresh.io/workflow-origin: promotion
+spec:
+  entrypoint: generate-context
+  templates:
+    - name: generate-context
+      serviceAccountName: hook
+      inputs:
+        parameters:
+          - name: context-params
+            description: JSON string of key-value pairs
+            # Example: '{"JIRA_ISSUE_SOURCE_FIELD": "ABC-123", "JIRA_BASE_URL": "https://jira.example.com"}'
+      script:
+        image: alpine
+        command: [sh]
+        source: |
+          echo '{{inputs.parameters.context-params}}' > /tmp/context.json
+          CONTEXT_JSON=$(cat /tmp/context.json)
+
+          # Output the context as is
+          echo "$CONTEXT_JSON" > /tmp/promotion-context.txt
+      outputs:
+        parameters:
+          - name: PROMOTION_CONTEXT
+            globalName: PROMOTION_CONTEXT
+            valueFrom:
+              path: /tmp/promotion-context.txt
+```
+
+
+### Create Promotion Workflows with hooks
+
+#### Hook 1: Create Jira ticket on promotion failure and export Jira issue URL through promotion context
+This hook performs two main actions:
+* Creates a Jira issue when a promotion fails.
+* References the  exports a promotion context that stores the URL of the created Jira issue, making it available to later hooks in the same Promotion Flow.
+
+
+{: .table .table-bordered .table-hover}
+| Hook 1 feature               | Description                                                                                       |
+|-----------------------------|---------------------------------------------------------------------------------------------------|
+| **Two-step DAG structure**  | The hook defines a Directed Acyclic Graph (DAG) with two steps: `create-issue` followed by `set-promotion-context`, which depends on successful Jira issue creation. |
+| **Jira issue creation**     | The `create-issue` step runs a container that creates a Jira issue and outputs its key or ID.     |
+| **Referenced template**     | The `set-promotion-context` step uses a reusable WorkflowTemplate named `set-promotion-context`, referencing its `generate-context` template. |
+| **Promotion context setup** | The `set-promotion-context` step passes a `context-params` JSON object with a dynamic Jira field value (`JIRA_ISSUE_SOURCE_FIELD`) from `create-issue` and a static base URL (`JIRA_ISSUE_URL`). It outputs this object as `PROMOTION_CONTEXT`. |
+| **Global sharing of context** | The exported `PROMOTION_CONTEXT` is globally accessible to any subsequent hook in the Promotion Flow. |
+
+
+
+
+##### Example YAML
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: WorkflowTemplate
+metadata:
+  name: jira-open-bug
+  annotations:
+    codefresh.io/workflow-origin: promotion
+    version: 0.0.1
+
+spec:
+  serviceAccountName: hook
+  entrypoint: main-dag
+  templates:
+    - name: main-dag
+      dag:
+        tasks:
+          - name: create-issue
+            template: create-issue
+          - name: set-promotion-context
+            templateRef:
+              name: set-promotion-context
+              template: generate-context
+            depends: "create-issue.Succeeded"
+            arguments:
+              parameters:
+                - name: context-params
+                  value: |
+                    {
+                      "JIRA_ISSUE_SOURCE_FIELD": "{{tasks.create-issue.outputs.parameters.JIRA_ISSUE_SOURCE_FIELD}}",
+                      "JIRA_ISSUE_URL": "https://testjira273.atlassian.net"
+                    }
+
+    - name: create-issue
+      serviceAccountName: hook
+      retryStrategy:
+        limit: "3"
+        retryPolicy: "Always"
+        backoff:
+          duration: "5s"
+      inputs:
+        parameters:
+          - name: SLACK_TOKEN
+            valueFrom:
+              secretKeyRef:
+                name: promotions-secrets
+                key: slack-token
+          - name: JIRA_ISSUE_URL
+            value: https://testjira273.atlassian.net
+          - name: JIRA_USERNAME
+            value: testjira273@gmail.com
+          - name: JIRA_API_KEY_SECRET_KEY
+            default: 'api-key'
+          - name: JIRA_USERNAME_SECRET_KEY
+            default: 'username'
+          - name: ISSUE_PROJECT
+            default: 'TEST'
+          - name: ISSUE_SUMMARY
+            default: 'migration for product release failed'
+          - name: ISSUE_DESCRIPTION
+            default: 'fix migration and current db state'
+          - name: ISSUE_COMPONENTS
+            default: ''
+          - name: ISSUE_CUSTOMFIELDS
+            default: ''
+          - name: ISSUE_TYPE
+            default: 'Task'
+      outputs:
+        parameters:
+          - name: JIRA_ISSUE_SOURCE_FIELD
+            valueFrom:
+              path: /tmp/JIRA_ISSUE_SOURCE_FIELD
+      container:
+        name: main
+        imagePullPolicy: Always
+        image: quay.io/codefreshplugins/argo-hub-workflows-jira-versions-0.0.1-images-jira-manager:main
+        command:
+          - python
+          - /jira/jira_issue_manager.py
+        env:
+          - name: JIRA_BASE_URL
+            value: ''
+          - name: JIRA_USERNAME
+            value: ''
+          - name: JIRA_API_SECRET_KEY
+            value: ''
+          - name: ACTION
+            value: 'issue_create'
+          - name: ISSUE_PROJECT
+            value: ''
+          - name: ISSUE_SUMMARY
+            value: ''
+          - name: ISSUE_DESCRIPTION
+            value: ''
+          - name: ISSUE_COMPONENTS
+            value: ''
+          - name: ISSUE_CUSTOMFIELDS
+            value: ''
+          - name: ISSUE_TYPE
+            value: ''
+        volumeMounts:
+          - name: promotion-context
+            mountPath: /tmp
+      volumes:
+        - name: promotion-context
+          emptyDir: {}
+   
+```
+<br><br>
+
+#### Hook 2: Create a hook that sends a Slack notification 
+This hook sends a Slack notification when a promotion fails. It uses the promotion context set by the Jira creation hook to include a direct link to the Jira issue in the Slack message.
+
+
+{: .table .table-bordered .table-hover}
+| Hook 2 feature         | Description       | 
+| --------------    | --------------    |  
+| **Single-step notification flow** | This hook uses a simple, single `send-message` template to post a Slack message. |
+| **Detailed Slack notification** | The Slack message the includes product name, commit SHA, promotion flow name, release URL, release ID, failed environments, error message, and **the Jira ticket URL**. |
+| **Dynamic inputs** | Parameters like `PRODUCT_NAME`, `COMMIT_SHA`, `ERROR_MESSAGE`, and `JIRA_ISSUE_URL` are passed dynamically, allowing the message to include real-time promotion failure details. |
+| **Simple and reusable Slack template** | The hook uses a standard Slack webhook and a flexible `SLACK_TEXT` format, making it easy to modify for different products or flows without changing the container logic. |
+| **Promotion context usage** | The `JIRA_ISSUE_URL` from the promotion context created in the previous hook is injected into the Slack message, linking the notification directly to the Jira ticket for tracking. |
+
+##### Example YAML
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: WorkflowTemplate
+metadata:
+  name: slack-fail-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
+      - name: FAILED_ENVIRONMENTS
+        value: '[]'
+      - name: ERROR_MESSAGE  
+      - name: JIRA_ISSUE_URL
+  serviceAccountName: hook
+  entrypoint: send-message
+  templates:
+    - name: send-message
+      retryStrategy:
+        limit: "1"
+        retryPolicy: "Always"
+        backoff:
+          duration: "5s"
+      inputs:
+        parameters:
+          - name: MODE
+            value: "simple"
+          - name: SLACK_HOOK_URL
+            value: https://hooks.slack.com/services/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
+          - name: SLACK_TEXT
+            value: |
+              🚨 *Promotion Failed!* 🚨  
+              *Product:* {{workflow.parameters.PRODUCT_NAME}}  
+              *Trigger Commit Sha:* {{workflow.parameters.COMMIT_SHA}}  
+              *Promotion Flow:* {{workflow.parameters.PROMOTION_FLOW_NAME}}  
+              *Release:* <{{workflow.parameters.RELEASE_URL}}|View Release>  
+              *Release ID:* {{workflow.parameters.RELEASE_ID}}  
+              *Failed Environments:* {{workflow.parameters.FAILED_ENVIRONMENTS}}
+              *Error Message:* {{workflow.parameters.ERROR_MESSAGE}}
+              *JIRA Ticket:* {{workflow.parameters.JIRA_ISSUE_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 }}'
+
+```
+
+
+### Assign hooks to Promotion Flow
+
+The next step is to assign Hook 1 and Hook 2 to different stages of the Promotion Flow.
+
+Here's an example of the Chart and YAML views of a Promotion Flow with several promotion hooks assigned. The hooks relevant to the examples above are highlighted.
+
+{% include 
+image.html 
+lightbox="true" 
+file="/images/gitops-promotions/hooks/promotion-flow-hooks-chart-view.png" 
+url="/images/gitops-promotions/hooks/promotion-flow-hooks-chart-view.png"
+alt="Chart view of Promotion Flows with hooks" 
+caption="Chart view of Promotion Flows with hooks" 
+max-width="60%"
+%}
+
+{% include 
+image.html 
+lightbox="true" 
+file="/images/gitops-promotions/hooks/promotion-flow-hooks-yaml.png" 
+url="/images/gitops-promotions/hooks/promotion-flow-hooks-yaml.png"
+alt="YAML view of Promotion Flows with hooks" 
+caption="YAML view of Promotion Flows with hooks" 
+max-width="60%"
+%}
+
+
+
+### Result of triggering Hooks 1 and 2 work in the Promotion Flow
+The table describes the results when the two hooks are triggered. 
+
+
+{: .table .table-bordered .table-hover}
+| Step | Action |
+|----|------|
+| **1** | Promotion fails in `staging` environment |  Triggers `On Failure` hook configured for `staging` environment |
+| **2** | On Failure Hook 1: `jira-open-bug`| {::nomarkdown}<ol><li>Creates new Jira issue describing the release failure.</li><li>Defines a promotion context including the Jira issue URL</li><li>Exports the promotion context to all subsequent hooks in the Promotion Flow, including On Release Failure Hook 2: `slack-fail-hook`.</li></ul>  |
+| **3** | Promotion failure for environment triggers On Release Failure  | Hook 2: `slack-fail-hook` sends a Slack notification to all stakeholders. The notification includes detailed failure information including the Jira issue URL value and other values available. | 
+
+Here's an example of the Slack notification sent on release failure:
+
+{% include 
+image.html 
+lightbox="true" 
+file="/images/gitops-promotions/hooks/hook-slack-notification-example.png" 
+url="/images/gitops-promotions/hooks/hook-slack-notification-example.png"
+alt="Example of Slack notification sent on release failure with link to Jira issue URL" 
+caption="Example of Slack notification sent on release failure with link to Jira issue URL" 
+max-width="60%"
+%}
+
+
+
+
+## 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/)  
diff --git a/_docs/promotions/promotion-flow.md b/_docs/promotions/promotion-flow.md
index 0caec8815..456421204 100644
--- a/_docs/promotions/promotion-flow.md
+++ b/_docs/promotions/promotion-flow.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/)  
diff --git a/_docs/promotions/promotion-hooks.md b/_docs/promotions/promotion-hooks.md
new file mode 100644
index 000000000..27d1bd153
--- /dev/null
+++ b/_docs/promotions/promotion-hooks.md
@@ -0,0 +1,301 @@
+---
+title: "Configure hooks in Promotion Workflows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+{{site.data.callout.callout_tip}}
+Available as part of the early access program.
+{{site.data.callout.end}}
+
+## Promotion hooks overview
+
+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 
+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%"
+%}
+
+Promotion hooks use the same mechanism as standard Promotion Workflows but run with additional context and scope on releases and environments. 
+Unlike Pre- and Post-Action Promotion Workflows, which operate on each application within environments, promotion hooks run once 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.
+
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a product release:  
+* **Release**: When Promotion Flow trigger creates a product release:
+  * **On start**: When the release is initiated  
+  * **On success**: When the release completes successfully
+  * **On failure**: When the release fails
+* **Per environment**: When a release transitions through specific environments:  
+  * **On start**: When the promotion reaches an environment
+  * **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). For the YAML specifications of promotion hooks when assigned, see [Promotion Flow YAML]({{site.baseurl}}/docs/promotions/yaml/promotion-flow-crd/).
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire product 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.  
+
+* 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"}.
+
+##### Arguments in promotion hooks
+A default set of arguments are available to all Promotion Workflows with hooks. See [Default arguments in Promotion Workflows with hooks](#default-arguments-for-promotion-hooks).
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (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. |
+| **Runtime**    | Cluster with the Configuration Runtime. | Runtime managing the application.    |
+| **Scope**      | Runs on cluster at release, or once per environment.    | Runs per application in the environment. |
+| **Effect on promotion**  | If a hook fails, the product release fails as well. <br>If the release is terminated, the On Fail and On Release Fail hooks, if defined, will run.<br>If an On Start or On Success hook fails, the On Fail hook, if defined, will run. |   If a workflow fails, the product release fails as well.  |
+
+
+<!--- ## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repo in `<gitops-runtime>/<shared-configuration-repo>/resources/control-planes/promotion-workflows/`.  
+
+The Workflow when submitted runs in the namespace of the Runtime designated as the [Configuration Runtime]({{site.baseurl}}/docs/installation/gitops/configuration-runtime/). If there is more than one Configuration Runtime, it runs on the first such Runtime in the list.  -->
+
+
+## Default arguments in Promotion Workflows with hooks
+The table below describes the default arguments that are replaced with values that GitOps Cloud retrieves from the promotion process.
+* When you create a Promotion Workflow template from the Codefresh UI, these arguments are automatically defined in `spec.arguments.parameters`.
+* When you create a template in Git, you must _manually add these arguments as required inputs_ if you want to use them.
+
+{: .table .table-bordered .table-hover}
+| Parameter         | Description       | Notes | 
+| --------------    | --------------    |  --------------   |
+|`RELEASE_URL`  | The URL link to the release associated with the promotion.  | All hooks   | 
+|`PRODUCT_NAME` | The name of the product for which the promotion release is running.  | All hooks   |
+|`VERSION`      | The version of the current release.| All hooks   | 
+|`COMMIT_SHA`   | The unique identifier (SHA) of the commit, generated by Git, that triggered the promotion and created the release.| All hooks   | 
+|`PROMOTION_FLOW_NAME` | The name of the Promotion Flow triggered for the release.  | All hooks   | 
+|`RELEASE_ID` | The unique identifier of the release.  | All hooks   | 
+|`ERROR_MESSAGE` | The system-generated error message identifying the reason why the release failed to complete. For example, `Product release was automatically terminated because the workflow state remained unknown`. | OnFailed hooks only  | 
+|`FAILED_ENVIRONMENTS` | The environment or environments which failed in the release with this information: {::nomarkdown}<ul><li><b>Name</b>: The name of the environment that failed to complete the release. For example, production</li><li><b>Status</b>: The release or promotion status for the environment. Can be one of the following: <ul><li>Successful</li><li>Running</li><li>Suspended</li><li>Failed</li><li>Terminated</li></ul></li><li><b>Error-message</b>: The system-generated error message identifying the reason for the failed promotion. For example, <code class="highlighter-rouge">Product release was automatically terminated because the workflow state remained unknown</code>. {:/}| OnFailed hooks only  | 
+
+## Promotion contexts in Promotion Workflows with hooks
+In a Promotion Flow, hooks may need custom parameters beyond the default ones available to the promotion mechanism. Because promotion hooks run within GitOps Runtimes in your own clusters, they do not automatically have access to these custom internal parameters. To pass custom values like Jira ticket IDs, approver names, or Slack channel information between hooks in the same Promotion Flow, you must define and export a promotion context. For details, see [Creating and exporting a promotion context](#creating-and-exporting-a-promotion-context).
+
+
+## Service accounts for promotion hooks
+
+Promotion Workflows that include hooks must also specify a service account with the required permissions. For details, see [Service accounts for Promotion Workflows]({{site.baseurl}}/docs/promotions/service-accounts-promotion-workflows/).
+
+
+## Examples of hooks in Promotion Workflows
+The following are examples of Promotion Workflows with hooks. 
+Though the hooks runs in the context of a promotion, they do not rely on implicit promotion behavior which makes the hooks reusable in different Promotion Flows at release or environment levels.
+
+For examples of hooks with promotion contexts, see 
+
+
+### On-start promotion hook example
+The example below shows a Promotion Workflow configured as an on-start hook. This workflow can run when a new release starts or when a promotion begins in any environment. It sends a Slack notification with the required parameters explicitly defined as input parameters. As they are not within a promotion context, these parameters are only available within the scope of this specific hook.
+
+
+##### Default parameters in on-start hook
+These are defined in `arguments.parameters` and GitOps Cloud dynamically retrieves their values during the promotion. 
+* `RELEASE_URL`  
+* `PRODUCT_NAME`  
+* `COMMIT_SHA`  
+* `PROMOTION_FLOW_NAME`  
+* `RELEASE_ID`  
+
+
+##### Additional parameters in on-start hook  
+This hook defines additional input parameters in the `send-message` template. Note that all parameters are defined with explicit values. 
+* `MODE` is the value used by the Slack plugin logic.
+* `SLACK_HOOK_URL` is the user-define incoming webhook URL.
+* `SLACK_TEXT` is the message to send. The example uses the default parameter `RELEASE_URL`.
+
+
+
+##### YAML example for on-start hook
+
+```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: https://hooks.slack.com/services/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
+          - 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 }}'
+```
+
+### On-fail promotion hook example
+
+The example below shows a Promotion Workflow configured as an on-fail hook. This workflow can run when a new release fails or when a promotion fails in any environment. It sends a Slack notification with additional context also explicitly defined as input parameters and not as part of a promotion context.
+
+
+##### Default parameters in on-fail hook
+It includes the same set of default parameters as for the [on-start hook Promotion Workflow](#default-parameters-in-on-start-hook) with two additional parameters specific to failed promotions:
+* `FAILED_ENVIRONMENTS` is a JSON array of failed environments if the hook is configured at release-level, or the specific environment if configured at environment level. 
+* `ERROR_MESSAGE` is the message describing the failure.
+
+
+##### Additional parameters in on-fail hook  
+This hook defines the same custom parameters as in the [on-start promotion hook](#custom-parameters-in-on-start-hook). 
+The `SLACK_TEXT` parameter is extended to include additional information, such as product, Promotion Flow, release ID, and more, ensuring that you have enough context to take action.
+
+
+##### On-fail hook YAML
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: WorkflowTemplate
+metadata:
+  name: on-fail-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
+      - name: FAILED_ENVIRONMENTS
+        value: '[]'
+      - name: ERROR_MESSAGE  
+  serviceAccountName: hook
+  entrypoint: send-message
+  templates:
+    - name: send-message
+      retryStrategy:
+        limit: "1"
+        retryPolicy: "Always"
+        backoff:
+          duration: "5s"
+      inputs:
+        parameters:
+          - name: MODE
+            value: "simple"
+          - name: SLACK_HOOK_URL
+            value: https://hooks.slack.com/services/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
+          - name: SLACK_TEXT
+            value: |
+              🚨 *Promotion Failed!* 🚨  
+              *Product:* {{workflow.parameters.PRODUCT_NAME}}  
+              *Trigger Commit Sha:* {{workflow.parameters.COMMIT_SHA}}  
+              *Promotion Flow:* {{workflow.parameters.PROMOTION_FLOW_NAME}}  
+              *Release:* <{{workflow.parameters.RELEASE_URL}}|View Release>  
+              *Release ID:* {{workflow.parameters.RELEASE_ID}}  
+              *Failed Environments:* {{workflow.parameters.FAILED_ENVIRONMENTS}}
+              *Error Message:* {{workflow.parameters.ERROR_MESSAGE}}
+      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 }}'
+```
+
+
+
+## Assigning promotion hooks in Promotion Flows
+
+Assign Promotion Workflows with promotion hooks to the Promotion Flow for the release or for one or more environments:
+* Release-level hooks run before the trigger environment and after the final target environment.
+* Environment-level hooks run on entry to or exit from each environment.
+* Multiple hooks can run based the stage in the product release they are configured. Promotion failure for an environment will run both On Fail hooks if configured the environment and for the release.
+
+You can also define them in the YAML manifest, as described in [Promotion Flow YAML]({{site.baseurl}}/docs/promotions/yaml/promotion-flow-crd/).
+
+
+{% include 
+image.html 
+lightbox="true" 
+file="/images/gitops-promotions/hooks/assign-promotion-hooks-in-ui.png" 
+url="/images/gitops-promotions/hooks/assign-promotion-hooks-in-ui.png"
+alt="Assign promotion hooks in Promotion Flow" 
+caption="Assign promotion hooks in Promotion Flow"
+max-width="60%"
+%}
+
+>**NOTE**  
+You cannot assign a Promotion Hook Workflow to the Trigger Environment itself. 
+
+
+
+
+## Related articles
+[Configure Promotion Flows]({{site.baseurl}}/docs/promotions/promotion-flow/)  
+[Configure Promotion Workflows]({{site.baseurl}}/docs/promotions/promotion-workflow/)  
+[Promotion Flow YAML]({{site.baseurl}}/docs/promotions/yaml/promotion-flow-crd/)  
+[Tracking product releases]({{site.baseurl}}/docs/promotions/product-releases/)  
+[Promotions: Setup & configuration guidelines]({{site.baseurl}}/docs/promotions/create-promotion-sequence/)  
+
+
diff --git a/_docs/promotions/promotion-policy.md b/_docs/promotions/promotion-policy.md
index 424de317a..321392a87 100644
--- a/_docs/promotions/promotion-policy.md
+++ b/_docs/promotions/promotion-policy.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/)  
diff --git a/_docs/promotions/promotion-workflow.md b/_docs/promotions/promotion-workflow.md
index 21bdaa086..e33daf867 100644
--- a/_docs/promotions/promotion-workflow.md
+++ b/_docs/promotions/promotion-workflow.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
diff --git a/_docs/promotions/service-accounts-promotion-workflows.md b/_docs/promotions/service-accounts-promotion-workflows.md
new file mode 100644
index 000000000..4ef1266ef
--- /dev/null
+++ b/_docs/promotions/service-accounts-promotion-workflows.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/)  
diff --git a/_docs/promotions/yaml.md b/_docs/promotions/yaml.md
index 3610afa16..ed96c42c4 100644
--- a/_docs/promotions/yaml.md
+++ b/_docs/promotions/yaml.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
 ---
 
diff --git a/_docs/promotions/yaml/promotion-flow-crd.md b/_docs/promotions/yaml/promotion-flow-crd.md
index 38f482862..82d6eca03 100644
--- a/_docs/promotions/yaml/promotion-flow-crd.md
+++ b/_docs/promotions/yaml/promotion-flow-crd.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/)  
diff --git a/_gitops/promotions/promotion-context-promotion-workflows.md b/_gitops/promotions/promotion-context-promotion-workflows.md
new file mode 120000
index 000000000..0d8e2583c
--- /dev/null
+++ b/_gitops/promotions/promotion-context-promotion-workflows.md
@@ -0,0 +1 @@
+../../_docs/promotions/promotion-context-promotion-workflows.md
\ No newline at end of file
diff --git a/_gitops/promotions/promotion-hooks.md b/_gitops/promotions/promotion-hooks.md
new file mode 120000
index 000000000..92dd562e8
--- /dev/null
+++ b/_gitops/promotions/promotion-hooks.md
@@ -0,0 +1 @@
+../../_docs/promotions/promotion-hooks.md
\ No newline at end of file
diff --git a/_gitops/promotions/service-accounts-promotion-workflows.md b/_gitops/promotions/service-accounts-promotion-workflows.md
new file mode 120000
index 000000000..0489cfaf6
--- /dev/null
+++ b/_gitops/promotions/service-accounts-promotion-workflows.md
@@ -0,0 +1 @@
+../../_docs/promotions/service-accounts-promotion-workflows.md
\ No newline at end of file
diff --git a/assets/js/src/argohub-redirect-mapping.json b/assets/js/src/argohub-redirect-mapping.json
index a18f45606..a7834ac26 100644
--- a/assets/js/src/argohub-redirect-mapping.json
+++ b/assets/js/src/argohub-redirect-mapping.json
@@ -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/"
 }
diff --git a/images/gitops-promotions/hooks/assign-promotion-hooks-in-ui.png b/images/gitops-promotions/hooks/assign-promotion-hooks-in-ui.png
new file mode 100644
index 000000000..a73c511e4
Binary files /dev/null and b/images/gitops-promotions/hooks/assign-promotion-hooks-in-ui.png differ
diff --git a/images/gitops-promotions/hooks/hook-slack-notification-example.png b/images/gitops-promotions/hooks/hook-slack-notification-example.png
new file mode 100644
index 000000000..8a762f618
Binary files /dev/null and b/images/gitops-promotions/hooks/hook-slack-notification-example.png differ
diff --git a/images/gitops-promotions/hooks/promotion-context-behavior.png b/images/gitops-promotions/hooks/promotion-context-behavior.png
new file mode 100644
index 000000000..e4e0d3357
Binary files /dev/null and b/images/gitops-promotions/hooks/promotion-context-behavior.png differ
diff --git a/images/gitops-promotions/hooks/promotion-flow-hooks-chart-view.png b/images/gitops-promotions/hooks/promotion-flow-hooks-chart-view.png
new file mode 100644
index 000000000..ed89320b8
Binary files /dev/null and b/images/gitops-promotions/hooks/promotion-flow-hooks-chart-view.png differ
diff --git a/images/gitops-promotions/hooks/promotion-flow-hooks-yaml.png b/images/gitops-promotions/hooks/promotion-flow-hooks-yaml.png
new file mode 100644
index 000000000..f5d440cc3
Binary files /dev/null and b/images/gitops-promotions/hooks/promotion-flow-hooks-yaml.png differ
diff --git a/images/gitops-promotions/hooks/promotion-hooks-in-flow.png b/images/gitops-promotions/hooks/promotion-hooks-in-flow.png
new file mode 100644
index 000000000..bdd98bfa1
Binary files /dev/null and b/images/gitops-promotions/hooks/promotion-hooks-in-flow.png differ
diff --git a/images/promotion-flow-yaml-with-hooks.png b/images/promotion-flow-yaml-with-hooks.png
new file mode 100644
index 000000000..3a52bf845
Binary files /dev/null and b/images/promotion-flow-yaml-with-hooks.png differ


Reviews:
user: login: kim-codefresh
state: COMMENTED
author_association: NONE
submitted_at: 2025-04-23T07:46:40Z
user: login: NimRegev
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-23T08:42:02Z
user: login: NimRegev
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-23T08:43:00Z
user: login: NimRegev
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-23T08:46:09Z
user: login: NimRegev
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-23T09:59:01Z
user: login: NimRegev
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-24T07:45:05Z
user: login: scme0
body: Just one minor comment from me. Looks good!
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-05-05T07:47:35Z
user: login: francisco-cocozza
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-07T21:04:50Z
user: login: NimRegev
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-11T10:12:09Z
user: login: NimRegev
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-11T10:13:45Z
user: login: NimRegev
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-11T10:13:58Z
user: login: NimRegev
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-11T10:23:41Z
user: login: NimRegev
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-11T10:40:14Z

Review comments:
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: ```suggestion
description: "Configure hooks to capture release and environment level events in promotion releases"
```
created_at: 2025-04-21T14:38:08Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: we called promotion release product release
created_at: 2025-04-21T14:38:39Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: not sure that `They are not tied to a particular deployment or application` is enough. need to mention it will run just one per environment event. regardless number of applications
created_at: 2025-04-21T14:40:25Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: I would suggestion consult with @laurencagneyoctopus and @francisco-cocozza for more usages
created_at: 2025-04-21T14:42:05Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: I would point the users to argo hub for more usefull options
created_at: 2025-04-21T14:42:39Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: Its need to be clear that we supply it but its flexible to change 
created_at: 2025-04-21T14:43:27Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run at release start, end (success, failure), or per environment (start, success, failure) | Runs for each application in an environment before and after promotion |
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: Runs run
created_at: 2025-04-21T14:50:50Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: hooks Effect on promotion is that if the hook fail it will fail the release as well, if release is terminated it will run the onFail as well, if onStart or onSuccess failed it will run the onFail if exist as well
of course if the onFail succeeded the release remains failed/ terminated
created_at: 2025-04-21T14:52:36Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: for pre/post its blocks the promotion if the workflow failed. not if condition failed
created_at: 2025-04-21T14:53:13Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: this is not accurate.
The hooks are configure in isc for all runtimes (I would mention here the path)
Then when submitting and running the workflow, it will run on the configuration runtime ns, but if there are multiple configuration runtimes then it will run on the first one that will act (we are planning to change it to the first one that was installed)
created_at: 2025-04-21T14:58:09Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repository of the Runitme designated as the Configuration Runtime.
+If you have multiple Configuration Runtimes, the hooks are saved in the first Configuration Runtime in the list  
+
+TBD - SHOW EXAMPLE OF SETTINGS
+
+## Service accounts & service account roles for Promotion Hook Workflows
+When a GitOps Runtime is installed, to support promotion hooks, Codefresh GitOps creates the following resources:  
+
+* **Service account**  
+  * `cf-default-promotion-workflows-sa` service account with the required role and role binding.  
+  * Workflow template manifests in Codefresh reference this service account.  
+
+* **Service account role**
+  `cf-default-promotion-workflows-role`, the default role for Promotion Workflows, bound to the service account `cf-default-promotion-workflows-sa`.  
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: when creating the promotion workflow from ui it will automatically add this service account to the yaml, but if they creating the promotion workflow from git, nothing will verify it 
created_at: 2025-04-22T08:43:19Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repository of the Runitme designated as the Configuration Runtime.
+If you have multiple Configuration Runtimes, the hooks are saved in the first Configuration Runtime in the list  
+
+TBD - SHOW EXAMPLE OF SETTINGS
+
+## Service accounts & service account roles for Promotion Hook Workflows
+When a GitOps Runtime is installed, to support promotion hooks, Codefresh GitOps creates the following resources:  
+
+* **Service account**  
+  * `cf-default-promotion-workflows-sa` service account with the required role and role binding.  
+  * Workflow template manifests in Codefresh reference this service account.  
+
+* **Service account role**
+  `cf-default-promotion-workflows-role`, the default role for Promotion Workflows, bound to the service account `cf-default-promotion-workflows-sa`.  
+
+If you already have service accounts or want to create your own service accounts, make sure that the system-provided service account is not compromised.
+
+
+### RBAC permissions for service account role  
+The following Role-Based Access Control (RBAC) permissions are required:   
+* `GET`  
+* `WATCH`  
+* `PATCH`  
+
+These permissions allow hooks to retrieve and update release and promotion details securely. 
+
+### Using an existing service account
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: its not clear this is optional, need to have like a topic of adding extra permission/ using your own role/ something similar
created_at: 2025-04-22T08:46:28Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repository of the Runitme designated as the Configuration Runtime.
+If you have multiple Configuration Runtimes, the hooks are saved in the first Configuration Runtime in the list  
+
+TBD - SHOW EXAMPLE OF SETTINGS
+
+## Service accounts & service account roles for Promotion Hook Workflows
+When a GitOps Runtime is installed, to support promotion hooks, Codefresh GitOps creates the following resources:  
+
+* **Service account**  
+  * `cf-default-promotion-workflows-sa` service account with the required role and role binding.  
+  * Workflow template manifests in Codefresh reference this service account.  
+
+* **Service account role**
+  `cf-default-promotion-workflows-role`, the default role for Promotion Workflows, bound to the service account `cf-default-promotion-workflows-sa`.  
+
+If you already have service accounts or want to create your own service accounts, make sure that the system-provided service account is not compromised.
+
+
+### RBAC permissions for service account role  
+The following Role-Based Access Control (RBAC) permissions are required:   
+* `GET`  
+* `WATCH`  
+* `PATCH`  
+
+These permissions allow hooks to retrieve and update release and promotion details securely. 
+
+### Using an existing service account
+For existing service accounts:
+* Create a new role with the required RBAC permissions.
+* Add a role binding to associate the new role with the service account.
+
+
+### Creating a new service account.
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: also here its not clear that there are 2 options
1. create new role and new role binding that will bind it to codefresh service account (cf-default-promotion-workflows-sa)
2. use their own service account and make sure to bind codefresh role to it (cf-default-promotion-workflows-role)
created_at: 2025-04-22T08:48:21Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repository of the Runitme designated as the Configuration Runtime.
+If you have multiple Configuration Runtimes, the hooks are saved in the first Configuration Runtime in the list  
+
+TBD - SHOW EXAMPLE OF SETTINGS
+
+## Service accounts & service account roles for Promotion Hook Workflows
+When a GitOps Runtime is installed, to support promotion hooks, Codefresh GitOps creates the following resources:  
+
+* **Service account**  
+  * `cf-default-promotion-workflows-sa` service account with the required role and role binding.  
+  * Workflow template manifests in Codefresh reference this service account.  
+
+* **Service account role**
+  `cf-default-promotion-workflows-role`, the default role for Promotion Workflows, bound to the service account `cf-default-promotion-workflows-sa`.  
+
+If you already have service accounts or want to create your own service accounts, make sure that the system-provided service account is not compromised.
+
+
+### RBAC permissions for service account role  
+The following Role-Based Access Control (RBAC) permissions are required:   
+* `GET`  
+* `WATCH`  
+* `PATCH`  
+
+These permissions allow hooks to retrieve and update release and promotion details securely. 
+
+### Using an existing service account
+For existing service accounts:
+* Create a new role with the required RBAC permissions.
+* Add a role binding to associate the new role with the service account.
+
+
+### Creating a new service account.
+* Bind the `cf-default-promotion-workflows-role` to the new service account.
+
+
+## Promotion contexts for promotion hooks
+All promotion hooks receive a standard set of [default arguments](#default-arguments-in-promotion-hook-workflows) such as the release ID, product, commit SHA.  
+To expose custom data such as Jira ticket IDs, approver names, or Slack channels, and make this data available to additional promotion hooks in the same Promotion Flow, you must define a **promotion context**.
+A promotion context is a user-defined JSON object passed between hooks in the same Promotion Flow. It enables the sharing values that Codefresh does not access by default.  
+
+Unlike standard Promotion Workflows which have built-in access to internal context, promotion hooks run within GitOps Runtimes in your own clusters. These hooks do not automatically receive custom values unless you define them in a promotion context. 
+
+Promotion contexts allow you to:
+* Expose and store user-defined variables that Codefresh cannot natively access.
+* Make those variables available as input parameters to subsequent Promotion Hook Workflows in the same Promotion Flow.
+
+Examples:
+* Send a Slack alert to a specific channel by passing the channel name in the promotion context
+* Link to a Jira ticket across all hooks in the release by storing the ticket ID in the context
+
+
+### Creating and exporting a promotion context 
+
+Create a promotion context in a Promotion Workflow as a JSON object including the custom parameters, and the file to which to export or save it and export the promotion context an output parameter to pass to subsequent Promotion Hook Workflow
+
+
+1. **Create the promotion context**  
+  * Create the promotion context as a JSON object containing the:
+      * Input parameters as variables
+      * File to which to save the promotion context. The file is referenced as the promotion context source.
+
+  **Example:**  
+  The example creates a promotion context `PROMOTION_CONTEXT` as a JSON object passed to subsequent promotion hooks in the same Promotion Flow. 
+  The promotion context:
+  * Defines `JIRA_ISSUE_SOURCE_FIELD` and makes it available an input parameter to subsequent hooks.
+  * Writes the context to a file `/tmp/promotion-context.txt`
+  
+```yaml 
+...
+spec:
+...
+    - name: set-promotion-context
+      serviceAccountName: hook
+      inputs:
+        parameters:
+          - name: JIRA_ISSUE_SOURCE_FIELD
+          - name: JIRA_BASE_URL
+      script:
+        image: alpine
+        command:
+          - sh
+        source: |
+            export JIRA_ISSUE_BASE_URL="{{inputs.parameters.JIRA_BASE_URL}}"
+            export JIRA_ISSUE_SOURCE_FIELD="{{inputs.parameters.JIRA_ISSUE_SOURCE_FIELD}}"
+            PROMOTION_CONTEXT=$(echo "{\"JIRA_ISSUE_URL\": \"${JIRA_ISSUE_BASE_URL}/browse/${JIRA_ISSUE_SOURCE_FIELD}\"}")
+            echo "$PROMOTION_CONTEXT" > /tmp/promotion-context.txt
+...
+``` 
+
+1. **Export promotion context**  
+  Expose the file with the promotion context as an output parameter to make it available to promotion mechanism.
+  * Add `PROMOTION_CONTEXT` as the `name` to `outputs.parameters`. _The name must not be changed_.
+  * Add the `globalName` attribute to make it available globally. The value must be identical to the name of the promotion context.
+  * `valueFrom` attribute to reference the file path
+
+  **Example:** The example adds `PROMOTION_CONTEXT` to `outputs.parameters.name`,  defines `globalName` as the name of the promotion context, and specifies the file path where the promotion context JSON was saved for Codefresh GitOps to retrieve and pass on to subsequent Promotion Hook Workflows.
+
+```yaml 
+...
+spec:
+...
+      outputs:
+        parameters:
+          - name: PROMOTION_CONTEXT  # cannot be changed
+            globalName: PROMOTION_CONTEXT # name of promotion context
+            valueFrom:
+              path: /tmp/promotion-context.txt
+...
+``` 
+
+
+
+
+
+
+## Examples of Promotion Hook Workflows
+The following examples of Promotion Hook Workflows 
+
+TBD
+
+
+## Assigning promotion hooks in Promotion Flows
+
+Assign Promotion Workflows with promotion hooks in the Promotion Flow for the release or environments:
+* Release-level hooks run before the trigger environment and after the final target environment
+* Environment-level hooks run on entry to or exit from each environment
+
+  >**NOTE**  
+  You cannot assign a Promotion Hook Workflow to the Trigger Environment itself. 
+
+
+SCREENSHOT TBD
+
+## How promotion hooks work during execution
+
+Once you assign Promotion Workflows with promotion hooks in a Promotion Flow, Codefresh GitOps executes them automatically at the relevant stages of the Promotion Flow:
+
+**Triggering the first hook**
+When the Promotion Flow is triggered, the promotion mechanism:
+* Passes the default promotion metadata (e.g., release ID, commit SHA)
+* Initializes the promotion context, if defined and valid, with any custom values 
+
+**Triggering subsequent hooks**
+As the Flow progresses, the promotion mechanism:
+* Retrieves the promotion context with the custom variables stored in the first hook
+* Passes the context automatically to all subsequent hooks as input parameters, making user-defined values consistently available across the entire flow, regardless of environment or cluster
+
+For example, if a Jira ticket ID is defined in the context when a promotion starts, it’s accessible later when a post-promotion hook runs in a different environment or cluster.
+
+DIAGRAM
+
+
+## Default arguments in Promotion Hook Workflows
+
+{: .table .table-bordered .table-hover}
+| Parameter                     | Description            | Notes | 
+| --------------                 | --------------           |  --------------   |
+|`RELEASE_URL` | The URL link to the release associated with the promotion. Is this the release nmae? Can you see this somewhere? How can users  | All hooks   | 
+|`PRODUCT_NAME` | The name of the product for which the promotion release is running.  | All hooks   | 
+|`COMMIT_SHA`   | The unique identifier (SHA) of the commit, generated by Git, that triggered the promotion and creaged the release.| All hooks   | 
+|`PROMOTION_FLOW_NAME` | The name of the Promotion Flow triggerend for the release .  | All hooks   | 
+|`RELEASE_ID` | The unique identifier of the release.  | All hooks   | 
+|`ERROR_MESSAGE` | The system-generated error message identifying the reason why the release failed to complete. For example, `Product release was automatically terminated because the workflow state remained unknown`. | OnFailed hooks only  | 
+|`FAILED_ENVIRONMENTS` | The environment or environments which failed in the release with this information: {::nomarkdown}<ul><li>Name: The name of the environment that failed to complete the release. For example, production</li><li>Status: The release or promotion status for the environment. Can be one of the following: {::nomarkdown}<ul><li>**Successful** </li><li>Running</li><li>Suspended</li><li>Failed</li><li>Terminated</li></ul></li><li>Error-message: Thesystem-generated error message identifying the reason for the failed promotion. For example, `Product release was automatically terminated because the workflow state remained unknown`. | OnFailed hooks only  | 
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: this is not clear
created_at: 2025-04-23T06:49:40Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repository of the Runitme designated as the Configuration Runtime.
+If you have multiple Configuration Runtimes, the hooks are saved in the first Configuration Runtime in the list  
+
+TBD - SHOW EXAMPLE OF SETTINGS
+
+## Service accounts & service account roles for Promotion Hook Workflows
+When a GitOps Runtime is installed, to support promotion hooks, Codefresh GitOps creates the following resources:  
+
+* **Service account**  
+  * `cf-default-promotion-workflows-sa` service account with the required role and role binding.  
+  * Workflow template manifests in Codefresh reference this service account.  
+
+* **Service account role**
+  `cf-default-promotion-workflows-role`, the default role for Promotion Workflows, bound to the service account `cf-default-promotion-workflows-sa`.  
+
+If you already have service accounts or want to create your own service accounts, make sure that the system-provided service account is not compromised.
+
+
+### RBAC permissions for service account role  
+The following Role-Based Access Control (RBAC) permissions are required:   
+* `GET`  
+* `WATCH`  
+* `PATCH`  
+
+These permissions allow hooks to retrieve and update release and promotion details securely. 
+
+### Using an existing service account
+For existing service accounts:
+* Create a new role with the required RBAC permissions.
+* Add a role binding to associate the new role with the service account.
+
+
+### Creating a new service account.
+* Bind the `cf-default-promotion-workflows-role` to the new service account.
+
+
+## Promotion contexts for promotion hooks
+All promotion hooks receive a standard set of [default arguments](#default-arguments-in-promotion-hook-workflows) such as the release ID, product, commit SHA.  
+To expose custom data such as Jira ticket IDs, approver names, or Slack channels, and make this data available to additional promotion hooks in the same Promotion Flow, you must define a **promotion context**.
+A promotion context is a user-defined JSON object passed between hooks in the same Promotion Flow. It enables the sharing values that Codefresh does not access by default.  
+
+Unlike standard Promotion Workflows which have built-in access to internal context, promotion hooks run within GitOps Runtimes in your own clusters. These hooks do not automatically receive custom values unless you define them in a promotion context. 
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: its not just "internal context" but usually standard promotion workflow are pre/post-action that runs where the application run
created_at: 2025-04-23T06:59:49Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repository of the Runitme designated as the Configuration Runtime.
+If you have multiple Configuration Runtimes, the hooks are saved in the first Configuration Runtime in the list  
+
+TBD - SHOW EXAMPLE OF SETTINGS
+
+## Service accounts & service account roles for Promotion Hook Workflows
+When a GitOps Runtime is installed, to support promotion hooks, Codefresh GitOps creates the following resources:  
+
+* **Service account**  
+  * `cf-default-promotion-workflows-sa` service account with the required role and role binding.  
+  * Workflow template manifests in Codefresh reference this service account.  
+
+* **Service account role**
+  `cf-default-promotion-workflows-role`, the default role for Promotion Workflows, bound to the service account `cf-default-promotion-workflows-sa`.  
+
+If you already have service accounts or want to create your own service accounts, make sure that the system-provided service account is not compromised.
+
+
+### RBAC permissions for service account role  
+The following Role-Based Access Control (RBAC) permissions are required:   
+* `GET`  
+* `WATCH`  
+* `PATCH`  
+
+These permissions allow hooks to retrieve and update release and promotion details securely. 
+
+### Using an existing service account
+For existing service accounts:
+* Create a new role with the required RBAC permissions.
+* Add a role binding to associate the new role with the service account.
+
+
+### Creating a new service account.
+* Bind the `cf-default-promotion-workflows-role` to the new service account.
+
+
+## Promotion contexts for promotion hooks
+All promotion hooks receive a standard set of [default arguments](#default-arguments-in-promotion-hook-workflows) such as the release ID, product, commit SHA.  
+To expose custom data such as Jira ticket IDs, approver names, or Slack channels, and make this data available to additional promotion hooks in the same Promotion Flow, you must define a **promotion context**.
+A promotion context is a user-defined JSON object passed between hooks in the same Promotion Flow. It enables the sharing values that Codefresh does not access by default.  
+
+Unlike standard Promotion Workflows which have built-in access to internal context, promotion hooks run within GitOps Runtimes in your own clusters. These hooks do not automatically receive custom values unless you define them in a promotion context. 
+
+Promotion contexts allow you to:
+* Expose and store user-defined variables that Codefresh cannot natively access.
+* Make those variables available as input parameters to subsequent Promotion Hook Workflows in the same Promotion Flow.
+
+Examples:
+* Send a Slack alert to a specific channel by passing the channel name in the promotion context
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: there must be more exmaples such as service now (open/close)
I would advice with Support or cs
created_at: 2025-04-23T07:01:36Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repository of the Runitme designated as the Configuration Runtime.
+If you have multiple Configuration Runtimes, the hooks are saved in the first Configuration Runtime in the list  
+
+TBD - SHOW EXAMPLE OF SETTINGS
+
+## Service accounts & service account roles for Promotion Hook Workflows
+When a GitOps Runtime is installed, to support promotion hooks, Codefresh GitOps creates the following resources:  
+
+* **Service account**  
+  * `cf-default-promotion-workflows-sa` service account with the required role and role binding.  
+  * Workflow template manifests in Codefresh reference this service account.  
+
+* **Service account role**
+  `cf-default-promotion-workflows-role`, the default role for Promotion Workflows, bound to the service account `cf-default-promotion-workflows-sa`.  
+
+If you already have service accounts or want to create your own service accounts, make sure that the system-provided service account is not compromised.
+
+
+### RBAC permissions for service account role  
+The following Role-Based Access Control (RBAC) permissions are required:   
+* `GET`  
+* `WATCH`  
+* `PATCH`  
+
+These permissions allow hooks to retrieve and update release and promotion details securely. 
+
+### Using an existing service account
+For existing service accounts:
+* Create a new role with the required RBAC permissions.
+* Add a role binding to associate the new role with the service account.
+
+
+### Creating a new service account.
+* Bind the `cf-default-promotion-workflows-role` to the new service account.
+
+
+## Promotion contexts for promotion hooks
+All promotion hooks receive a standard set of [default arguments](#default-arguments-in-promotion-hook-workflows) such as the release ID, product, commit SHA.  
+To expose custom data such as Jira ticket IDs, approver names, or Slack channels, and make this data available to additional promotion hooks in the same Promotion Flow, you must define a **promotion context**.
+A promotion context is a user-defined JSON object passed between hooks in the same Promotion Flow. It enables the sharing values that Codefresh does not access by default.  
+
+Unlike standard Promotion Workflows which have built-in access to internal context, promotion hooks run within GitOps Runtimes in your own clusters. These hooks do not automatically receive custom values unless you define them in a promotion context. 
+
+Promotion contexts allow you to:
+* Expose and store user-defined variables that Codefresh cannot natively access.
+* Make those variables available as input parameters to subsequent Promotion Hook Workflows in the same Promotion Flow.
+
+Examples:
+* Send a Slack alert to a specific channel by passing the channel name in the promotion context
+* Link to a Jira ticket across all hooks in the release by storing the ticket ID in the context
+
+
+### Creating and exporting a promotion context 
+
+Create a promotion context in a Promotion Workflow as a JSON object including the custom parameters, and the file to which to export or save it and export the promotion context an output parameter to pass to subsequent Promotion Hook Workflow
+
+
+1. **Create the promotion context**  
+  * Create the promotion context as a JSON object containing the:
+      * Input parameters as variables
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: this is not correct, the only thing the user need is an output param called PROMOTION_CONTEXT that will include this JSON file
created_at: 2025-04-23T07:03:53Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repository of the Runitme designated as the Configuration Runtime.
+If you have multiple Configuration Runtimes, the hooks are saved in the first Configuration Runtime in the list  
+
+TBD - SHOW EXAMPLE OF SETTINGS
+
+## Service accounts & service account roles for Promotion Hook Workflows
+When a GitOps Runtime is installed, to support promotion hooks, Codefresh GitOps creates the following resources:  
+
+* **Service account**  
+  * `cf-default-promotion-workflows-sa` service account with the required role and role binding.  
+  * Workflow template manifests in Codefresh reference this service account.  
+
+* **Service account role**
+  `cf-default-promotion-workflows-role`, the default role for Promotion Workflows, bound to the service account `cf-default-promotion-workflows-sa`.  
+
+If you already have service accounts or want to create your own service accounts, make sure that the system-provided service account is not compromised.
+
+
+### RBAC permissions for service account role  
+The following Role-Based Access Control (RBAC) permissions are required:   
+* `GET`  
+* `WATCH`  
+* `PATCH`  
+
+These permissions allow hooks to retrieve and update release and promotion details securely. 
+
+### Using an existing service account
+For existing service accounts:
+* Create a new role with the required RBAC permissions.
+* Add a role binding to associate the new role with the service account.
+
+
+### Creating a new service account.
+* Bind the `cf-default-promotion-workflows-role` to the new service account.
+
+
+## Promotion contexts for promotion hooks
+All promotion hooks receive a standard set of [default arguments](#default-arguments-in-promotion-hook-workflows) such as the release ID, product, commit SHA.  
+To expose custom data such as Jira ticket IDs, approver names, or Slack channels, and make this data available to additional promotion hooks in the same Promotion Flow, you must define a **promotion context**.
+A promotion context is a user-defined JSON object passed between hooks in the same Promotion Flow. It enables the sharing values that Codefresh does not access by default.  
+
+Unlike standard Promotion Workflows which have built-in access to internal context, promotion hooks run within GitOps Runtimes in your own clusters. These hooks do not automatically receive custom values unless you define them in a promotion context. 
+
+Promotion contexts allow you to:
+* Expose and store user-defined variables that Codefresh cannot natively access.
+* Make those variables available as input parameters to subsequent Promotion Hook Workflows in the same Promotion Flow.
+
+Examples:
+* Send a Slack alert to a specific channel by passing the channel name in the promotion context
+* Link to a Jira ticket across all hooks in the release by storing the ticket ID in the context
+
+
+### Creating and exporting a promotion context 
+
+Create a promotion context in a Promotion Workflow as a JSON object including the custom parameters, and the file to which to export or save it and export the promotion context an output parameter to pass to subsequent Promotion Hook Workflow
+
+
+1. **Create the promotion context**  
+  * Create the promotion context as a JSON object containing the:
+      * Input parameters as variables
+      * File to which to save the promotion context. The file is referenced as the promotion context source.
+
+  **Example:**  
+  The example creates a promotion context `PROMOTION_CONTEXT` as a JSON object passed to subsequent promotion hooks in the same Promotion Flow. 
+  The promotion context:
+  * Defines `JIRA_ISSUE_SOURCE_FIELD` and makes it available an input parameter to subsequent hooks.
+  * Writes the context to a file `/tmp/promotion-context.txt`
+  
+```yaml 
+...
+spec:
+...
+    - name: set-promotion-context
+      serviceAccountName: hook
+      inputs:
+        parameters:
+          - name: JIRA_ISSUE_SOURCE_FIELD
+          - name: JIRA_BASE_URL
+      script:
+        image: alpine
+        command:
+          - sh
+        source: |
+            export JIRA_ISSUE_BASE_URL="{{inputs.parameters.JIRA_BASE_URL}}"
+            export JIRA_ISSUE_SOURCE_FIELD="{{inputs.parameters.JIRA_ISSUE_SOURCE_FIELD}}"
+            PROMOTION_CONTEXT=$(echo "{\"JIRA_ISSUE_URL\": \"${JIRA_ISSUE_BASE_URL}/browse/${JIRA_ISSUE_SOURCE_FIELD}\"}")
+            echo "$PROMOTION_CONTEXT" > /tmp/promotion-context.txt
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: again here the important part is the output param, need to add it to the example yaml as well
created_at: 2025-04-23T07:04:53Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repository of the Runitme designated as the Configuration Runtime.
+If you have multiple Configuration Runtimes, the hooks are saved in the first Configuration Runtime in the list  
+
+TBD - SHOW EXAMPLE OF SETTINGS
+
+## Service accounts & service account roles for Promotion Hook Workflows
+When a GitOps Runtime is installed, to support promotion hooks, Codefresh GitOps creates the following resources:  
+
+* **Service account**  
+  * `cf-default-promotion-workflows-sa` service account with the required role and role binding.  
+  * Workflow template manifests in Codefresh reference this service account.  
+
+* **Service account role**
+  `cf-default-promotion-workflows-role`, the default role for Promotion Workflows, bound to the service account `cf-default-promotion-workflows-sa`.  
+
+If you already have service accounts or want to create your own service accounts, make sure that the system-provided service account is not compromised.
+
+
+### RBAC permissions for service account role  
+The following Role-Based Access Control (RBAC) permissions are required:   
+* `GET`  
+* `WATCH`  
+* `PATCH`  
+
+These permissions allow hooks to retrieve and update release and promotion details securely. 
+
+### Using an existing service account
+For existing service accounts:
+* Create a new role with the required RBAC permissions.
+* Add a role binding to associate the new role with the service account.
+
+
+### Creating a new service account.
+* Bind the `cf-default-promotion-workflows-role` to the new service account.
+
+
+## Promotion contexts for promotion hooks
+All promotion hooks receive a standard set of [default arguments](#default-arguments-in-promotion-hook-workflows) such as the release ID, product, commit SHA.  
+To expose custom data such as Jira ticket IDs, approver names, or Slack channels, and make this data available to additional promotion hooks in the same Promotion Flow, you must define a **promotion context**.
+A promotion context is a user-defined JSON object passed between hooks in the same Promotion Flow. It enables the sharing values that Codefresh does not access by default.  
+
+Unlike standard Promotion Workflows which have built-in access to internal context, promotion hooks run within GitOps Runtimes in your own clusters. These hooks do not automatically receive custom values unless you define them in a promotion context. 
+
+Promotion contexts allow you to:
+* Expose and store user-defined variables that Codefresh cannot natively access.
+* Make those variables available as input parameters to subsequent Promotion Hook Workflows in the same Promotion Flow.
+
+Examples:
+* Send a Slack alert to a specific channel by passing the channel name in the promotion context
+* Link to a Jira ticket across all hooks in the release by storing the ticket ID in the context
+
+
+### Creating and exporting a promotion context 
+
+Create a promotion context in a Promotion Workflow as a JSON object including the custom parameters, and the file to which to export or save it and export the promotion context an output parameter to pass to subsequent Promotion Hook Workflow
+
+
+1. **Create the promotion context**  
+  * Create the promotion context as a JSON object containing the:
+      * Input parameters as variables
+      * File to which to save the promotion context. The file is referenced as the promotion context source.
+
+  **Example:**  
+  The example creates a promotion context `PROMOTION_CONTEXT` as a JSON object passed to subsequent promotion hooks in the same Promotion Flow. 
+  The promotion context:
+  * Defines `JIRA_ISSUE_SOURCE_FIELD` and makes it available an input parameter to subsequent hooks.
+  * Writes the context to a file `/tmp/promotion-context.txt`
+  
+```yaml 
+...
+spec:
+...
+    - name: set-promotion-context
+      serviceAccountName: hook
+      inputs:
+        parameters:
+          - name: JIRA_ISSUE_SOURCE_FIELD
+          - name: JIRA_BASE_URL
+      script:
+        image: alpine
+        command:
+          - sh
+        source: |
+            export JIRA_ISSUE_BASE_URL="{{inputs.parameters.JIRA_BASE_URL}}"
+            export JIRA_ISSUE_SOURCE_FIELD="{{inputs.parameters.JIRA_ISSUE_SOURCE_FIELD}}"
+            PROMOTION_CONTEXT=$(echo "{\"JIRA_ISSUE_URL\": \"${JIRA_ISSUE_BASE_URL}/browse/${JIRA_ISSUE_SOURCE_FIELD}\"}")
+            echo "$PROMOTION_CONTEXT" > /tmp/promotion-context.txt
+...
+``` 
+
+1. **Export promotion context**  
+  Expose the file with the promotion context as an output parameter to make it available to promotion mechanism.
+  * Add `PROMOTION_CONTEXT` as the `name` to `outputs.parameters`. _The name must not be changed_.
+  * Add the `globalName` attribute to make it available globally. The value must be identical to the name of the promotion context.
+  * `valueFrom` attribute to reference the file path
+
+  **Example:** The example adds `PROMOTION_CONTEXT` to `outputs.parameters.name`,  defines `globalName` as the name of the promotion context, and specifies the file path where the promotion context JSON was saved for Codefresh GitOps to retrieve and pass on to subsequent Promotion Hook Workflows.
+
+```yaml 
+...
+spec:
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: I would merge those example, its not making sense to not export promotion context
created_at: 2025-04-23T07:05:58Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repository of the Runitme designated as the Configuration Runtime.
+If you have multiple Configuration Runtimes, the hooks are saved in the first Configuration Runtime in the list  
+
+TBD - SHOW EXAMPLE OF SETTINGS
+
+## Service accounts & service account roles for Promotion Hook Workflows
+When a GitOps Runtime is installed, to support promotion hooks, Codefresh GitOps creates the following resources:  
+
+* **Service account**  
+  * `cf-default-promotion-workflows-sa` service account with the required role and role binding.  
+  * Workflow template manifests in Codefresh reference this service account.  
+
+* **Service account role**
+  `cf-default-promotion-workflows-role`, the default role for Promotion Workflows, bound to the service account `cf-default-promotion-workflows-sa`.  
+
+If you already have service accounts or want to create your own service accounts, make sure that the system-provided service account is not compromised.
+
+
+### RBAC permissions for service account role  
+The following Role-Based Access Control (RBAC) permissions are required:   
+* `GET`  
+* `WATCH`  
+* `PATCH`  
+
+These permissions allow hooks to retrieve and update release and promotion details securely. 
+
+### Using an existing service account
+For existing service accounts:
+* Create a new role with the required RBAC permissions.
+* Add a role binding to associate the new role with the service account.
+
+
+### Creating a new service account.
+* Bind the `cf-default-promotion-workflows-role` to the new service account.
+
+
+## Promotion contexts for promotion hooks
+All promotion hooks receive a standard set of [default arguments](#default-arguments-in-promotion-hook-workflows) such as the release ID, product, commit SHA.  
+To expose custom data such as Jira ticket IDs, approver names, or Slack channels, and make this data available to additional promotion hooks in the same Promotion Flow, you must define a **promotion context**.
+A promotion context is a user-defined JSON object passed between hooks in the same Promotion Flow. It enables the sharing values that Codefresh does not access by default.  
+
+Unlike standard Promotion Workflows which have built-in access to internal context, promotion hooks run within GitOps Runtimes in your own clusters. These hooks do not automatically receive custom values unless you define them in a promotion context. 
+
+Promotion contexts allow you to:
+* Expose and store user-defined variables that Codefresh cannot natively access.
+* Make those variables available as input parameters to subsequent Promotion Hook Workflows in the same Promotion Flow.
+
+Examples:
+* Send a Slack alert to a specific channel by passing the channel name in the promotion context
+* Link to a Jira ticket across all hooks in the release by storing the ticket ID in the context
+
+
+### Creating and exporting a promotion context 
+
+Create a promotion context in a Promotion Workflow as a JSON object including the custom parameters, and the file to which to export or save it and export the promotion context an output parameter to pass to subsequent Promotion Hook Workflow
+
+
+1. **Create the promotion context**  
+  * Create the promotion context as a JSON object containing the:
+      * Input parameters as variables
+      * File to which to save the promotion context. The file is referenced as the promotion context source.
+
+  **Example:**  
+  The example creates a promotion context `PROMOTION_CONTEXT` as a JSON object passed to subsequent promotion hooks in the same Promotion Flow. 
+  The promotion context:
+  * Defines `JIRA_ISSUE_SOURCE_FIELD` and makes it available an input parameter to subsequent hooks.
+  * Writes the context to a file `/tmp/promotion-context.txt`
+  
+```yaml 
+...
+spec:
+...
+    - name: set-promotion-context
+      serviceAccountName: hook
+      inputs:
+        parameters:
+          - name: JIRA_ISSUE_SOURCE_FIELD
+          - name: JIRA_BASE_URL
+      script:
+        image: alpine
+        command:
+          - sh
+        source: |
+            export JIRA_ISSUE_BASE_URL="{{inputs.parameters.JIRA_BASE_URL}}"
+            export JIRA_ISSUE_SOURCE_FIELD="{{inputs.parameters.JIRA_ISSUE_SOURCE_FIELD}}"
+            PROMOTION_CONTEXT=$(echo "{\"JIRA_ISSUE_URL\": \"${JIRA_ISSUE_BASE_URL}/browse/${JIRA_ISSUE_SOURCE_FIELD}\"}")
+            echo "$PROMOTION_CONTEXT" > /tmp/promotion-context.txt
+...
+``` 
+
+1. **Export promotion context**  
+  Expose the file with the promotion context as an output parameter to make it available to promotion mechanism.
+  * Add `PROMOTION_CONTEXT` as the `name` to `outputs.parameters`. _The name must not be changed_.
+  * Add the `globalName` attribute to make it available globally. The value must be identical to the name of the promotion context.
+  * `valueFrom` attribute to reference the file path
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: potentially they can take it wherever they want from
created_at: 2025-04-23T07:06:48Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repository of the Runitme designated as the Configuration Runtime.
+If you have multiple Configuration Runtimes, the hooks are saved in the first Configuration Runtime in the list  
+
+TBD - SHOW EXAMPLE OF SETTINGS
+
+## Service accounts & service account roles for Promotion Hook Workflows
+When a GitOps Runtime is installed, to support promotion hooks, Codefresh GitOps creates the following resources:  
+
+* **Service account**  
+  * `cf-default-promotion-workflows-sa` service account with the required role and role binding.  
+  * Workflow template manifests in Codefresh reference this service account.  
+
+* **Service account role**
+  `cf-default-promotion-workflows-role`, the default role for Promotion Workflows, bound to the service account `cf-default-promotion-workflows-sa`.  
+
+If you already have service accounts or want to create your own service accounts, make sure that the system-provided service account is not compromised.
+
+
+### RBAC permissions for service account role  
+The following Role-Based Access Control (RBAC) permissions are required:   
+* `GET`  
+* `WATCH`  
+* `PATCH`  
+
+These permissions allow hooks to retrieve and update release and promotion details securely. 
+
+### Using an existing service account
+For existing service accounts:
+* Create a new role with the required RBAC permissions.
+* Add a role binding to associate the new role with the service account.
+
+
+### Creating a new service account.
+* Bind the `cf-default-promotion-workflows-role` to the new service account.
+
+
+## Promotion contexts for promotion hooks
+All promotion hooks receive a standard set of [default arguments](#default-arguments-in-promotion-hook-workflows) such as the release ID, product, commit SHA.  
+To expose custom data such as Jira ticket IDs, approver names, or Slack channels, and make this data available to additional promotion hooks in the same Promotion Flow, you must define a **promotion context**.
+A promotion context is a user-defined JSON object passed between hooks in the same Promotion Flow. It enables the sharing values that Codefresh does not access by default.  
+
+Unlike standard Promotion Workflows which have built-in access to internal context, promotion hooks run within GitOps Runtimes in your own clusters. These hooks do not automatically receive custom values unless you define them in a promotion context. 
+
+Promotion contexts allow you to:
+* Expose and store user-defined variables that Codefresh cannot natively access.
+* Make those variables available as input parameters to subsequent Promotion Hook Workflows in the same Promotion Flow.
+
+Examples:
+* Send a Slack alert to a specific channel by passing the channel name in the promotion context
+* Link to a Jira ticket across all hooks in the release by storing the ticket ID in the context
+
+
+### Creating and exporting a promotion context 
+
+Create a promotion context in a Promotion Workflow as a JSON object including the custom parameters, and the file to which to export or save it and export the promotion context an output parameter to pass to subsequent Promotion Hook Workflow
+
+
+1. **Create the promotion context**  
+  * Create the promotion context as a JSON object containing the:
+      * Input parameters as variables
+      * File to which to save the promotion context. The file is referenced as the promotion context source.
+
+  **Example:**  
+  The example creates a promotion context `PROMOTION_CONTEXT` as a JSON object passed to subsequent promotion hooks in the same Promotion Flow. 
+  The promotion context:
+  * Defines `JIRA_ISSUE_SOURCE_FIELD` and makes it available an input parameter to subsequent hooks.
+  * Writes the context to a file `/tmp/promotion-context.txt`
+  
+```yaml 
+...
+spec:
+...
+    - name: set-promotion-context
+      serviceAccountName: hook
+      inputs:
+        parameters:
+          - name: JIRA_ISSUE_SOURCE_FIELD
+          - name: JIRA_BASE_URL
+      script:
+        image: alpine
+        command:
+          - sh
+        source: |
+            export JIRA_ISSUE_BASE_URL="{{inputs.parameters.JIRA_BASE_URL}}"
+            export JIRA_ISSUE_SOURCE_FIELD="{{inputs.parameters.JIRA_ISSUE_SOURCE_FIELD}}"
+            PROMOTION_CONTEXT=$(echo "{\"JIRA_ISSUE_URL\": \"${JIRA_ISSUE_BASE_URL}/browse/${JIRA_ISSUE_SOURCE_FIELD}\"}")
+            echo "$PROMOTION_CONTEXT" > /tmp/promotion-context.txt
+...
+``` 
+
+1. **Export promotion context**  
+  Expose the file with the promotion context as an output parameter to make it available to promotion mechanism.
+  * Add `PROMOTION_CONTEXT` as the `name` to `outputs.parameters`. _The name must not be changed_.
+  * Add the `globalName` attribute to make it available globally. The value must be identical to the name of the promotion context.
+  * `valueFrom` attribute to reference the file path
+
+  **Example:** The example adds `PROMOTION_CONTEXT` to `outputs.parameters.name`,  defines `globalName` as the name of the promotion context, and specifies the file path where the promotion context JSON was saved for Codefresh GitOps to retrieve and pass on to subsequent Promotion Hook Workflows.
+
+```yaml 
+...
+spec:
+...
+      outputs:
+        parameters:
+          - name: PROMOTION_CONTEXT  # cannot be changed
+            globalName: PROMOTION_CONTEXT # name of promotion context
+            valueFrom:
+              path: /tmp/promotion-context.txt
+...
+``` 
+
+
+
+
+
+
+## Examples of Promotion Hook Workflows
+The following examples of Promotion Hook Workflows 
+
+TBD
+
+
+## Assigning promotion hooks in Promotion Flows
+
+Assign Promotion Workflows with promotion hooks in the Promotion Flow for the release or environments:
+* Release-level hooks run before the trigger environment and after the final target environment
+* Environment-level hooks run on entry to or exit from each environment
+
+  >**NOTE**  
+  You cannot assign a Promotion Hook Workflow to the Trigger Environment itself. 
+
+
path: _docs/promotions/promotion-hooks.md
user: login: kim-codefresh
body: another note is that  they can run one after another and not canceling each other, for example if there is onFail for a env and also for the release, in case there was a failure on the environment they both gonna run
created_at: 2025-04-23T07:09:26Z
author_association: NONE
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
path: _docs/promotions/promotion-hooks.md
user: login: NimRegev
body: Change title to better indicate 
Promotion context is optional. Service acnts are required. We supply a default but they can customize - add link to detailed sections
created_at: 2025-04-23T08:42:02Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
path: _docs/promotions/promotion-hooks.md
user: login: NimRegev
body: Change to make it clear where they are saved and where it runs
created_at: 2025-04-23T08:43:00Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repository of the Runitme designated as the Configuration Runtime.
+If you have multiple Configuration Runtimes, the hooks are saved in the first Configuration Runtime in the list  
+
+TBD - SHOW EXAMPLE OF SETTINGS
+
+## Service accounts & service account roles for Promotion Hook Workflows
+When a GitOps Runtime is installed, to support promotion hooks, Codefresh GitOps creates the following resources:  
+
+* **Service account**  
+  * `cf-default-promotion-workflows-sa` service account with the required role and role binding.  
+  * Workflow template manifests in Codefresh reference this service account.  
+
+* **Service account role**
+  `cf-default-promotion-workflows-role`, the default role for Promotion Workflows, bound to the service account `cf-default-promotion-workflows-sa`.  
+
+If you already have service accounts or want to create your own service accounts, make sure that the system-provided service account is not compromised.
+
+
+### RBAC permissions for service account role  
+The following Role-Based Access Control (RBAC) permissions are required:   
+* `GET`  
+* `WATCH`  
+* `PATCH`  
+
+These permissions allow hooks to retrieve and update release and promotion details securely. 
+
+### Using an existing service account
+For existing service accounts:
+* Create a new role with the required RBAC permissions.
+* Add a role binding to associate the new role with the service account.
+
+
+### Creating a new service account.
path: _docs/promotions/promotion-hooks.md
user: login: NimRegev
body: Emphasize that these are optional and when they would need to use their own service accounts
created_at: 2025-04-23T08:46:08Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repository of the Runitme designated as the Configuration Runtime.
+If you have multiple Configuration Runtimes, the hooks are saved in the first Configuration Runtime in the list  
+
+TBD - SHOW EXAMPLE OF SETTINGS
+
+## Service accounts & service account roles for Promotion Hook Workflows
+When a GitOps Runtime is installed, to support promotion hooks, Codefresh GitOps creates the following resources:  
+
+* **Service account**  
+  * `cf-default-promotion-workflows-sa` service account with the required role and role binding.  
+  * Workflow template manifests in Codefresh reference this service account.  
+
+* **Service account role**
+  `cf-default-promotion-workflows-role`, the default role for Promotion Workflows, bound to the service account `cf-default-promotion-workflows-sa`.  
path: _docs/promotions/promotion-hooks.md
user: login: NimRegev
body: Done
created_at: 2025-04-23T09:59:01Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
path: _docs/promotions/promotion-hooks.md
user: login: francisco-cocozza
body: I read the list of use cases, it looks fine.
Maybe one use case that isn't listed is related to pausing the Promotion Flow.

In case a Pause cannot be implemented in the PR of the Action, customers can leverage a Promotion hook for that.
For example, to add an Approval done in another Platform (e.g., ServiceNow)
created_at: 2025-04-23T23:21:30Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire promotion 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.  
+
+##### Requirements for promotion hooks
+
+* Service account
+* Service account role and role binding 
+* Promotion context
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows.
+
+| **Feature**    | **Promotion Hooks**  | **Promotion Workflows**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release  | Provide information on promoted changes in applications within an environment    |
+| **Execution**  | Runs run 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**  | ??? | Blocks a promotion if conditions fail  |
+
+
+
+## Promotion hooks in Shared Configuration Repository
+Promotion Workflows with hooks are saved in the Shared Configuration Repository of the Runitme designated as the Configuration Runtime.
+If you have multiple Configuration Runtimes, the hooks are saved in the first Configuration Runtime in the list  
+
+TBD - SHOW EXAMPLE OF SETTINGS
+
+## Service accounts & service account roles for Promotion Hook Workflows
+When a GitOps Runtime is installed, to support promotion hooks, Codefresh GitOps creates the following resources:  
+
+* **Service account**  
+  * `cf-default-promotion-workflows-sa` service account with the required role and role binding.  
+  * Workflow template manifests in Codefresh reference this service account.  
+
+* **Service account role**
+  `cf-default-promotion-workflows-role`, the default role for Promotion Workflows, bound to the service account `cf-default-promotion-workflows-sa`.  
+
+If you already have service accounts or want to create your own service accounts, make sure that the system-provided service account is not compromised.
+
+
+### RBAC permissions for service account role  
+The following Role-Based Access Control (RBAC) permissions are required:   
+* `GET`  
+* `WATCH`  
+* `PATCH`  
+
+These permissions allow hooks to retrieve and update release and promotion details securely. 
+
+### Using an existing service account
+For existing service accounts:
+* Create a new role with the required RBAC permissions.
+* Add a role binding to associate the new role with the service account.
+
+
+### Creating a new service account.
+* Bind the `cf-default-promotion-workflows-role` to the new service account.
+
+
+## Promotion contexts for promotion hooks
+All promotion hooks receive a standard set of [default arguments](#default-arguments-in-promotion-hook-workflows) such as the release ID, product, commit SHA.  
+To expose custom data such as Jira ticket IDs, approver names, or Slack channels, and make this data available to additional promotion hooks in the same Promotion Flow, you must define a **promotion context**.
+A promotion context is a user-defined JSON object passed between hooks in the same Promotion Flow. It enables the sharing values that Codefresh does not access by default.  
+
+Unlike standard Promotion Workflows which have built-in access to internal context, promotion hooks run within GitOps Runtimes in your own clusters. These hooks do not automatically receive custom values unless you define them in a promotion context. 
+
+Promotion contexts allow you to:
+* Expose and store user-defined variables that Codefresh cannot natively access.
+* Make those variables available as input parameters to subsequent Promotion Hook Workflows in the same Promotion Flow.
+
+Examples:
+* Send a Slack alert to a specific channel by passing the channel name in the promotion context
+* Link to a Jira ticket across all hooks in the release by storing the ticket ID in the context
+
+
+### Creating and exporting a promotion context 
+
+Create a promotion context in a Promotion Workflow as a JSON object including the custom parameters, and the file to which to export or save it and export the promotion context an output parameter to pass to subsequent Promotion Hook Workflow
+
+
+1. **Create the promotion context**  
+  * Create the promotion context as a JSON object containing the:
+      * Input parameters as variables
path: _docs/promotions/promotion-hooks.md
user: login: NimRegev
body: Done
created_at: 2025-04-24T07:45:05Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,105 @@
+---
+title: "Service account for Promotion Workflows"
+description: "Understand the service account and role requirements for Promotion Workflows"
+group: promotions
+toc: true
+---
+
+
+
+## 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 service role
+
+If you need a service role with additional permissions or a new service account, do one of the following:
path: _docs/promotions/service-accounts-promotion-workflows.md
user: login: francisco-cocozza
body: It should be _"if you need a Role"_ (not Service Role)
created_at: 2025-05-02T00:17:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,105 @@
+---
+title: "Service account for Promotion Workflows"
+description: "Understand the service account and role requirements for Promotion Workflows"
+group: promotions
+toc: true
+---
+
+
+
+## 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 service role
+
+If you need a service 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`.
path: _docs/promotions/service-accounts-promotion-workflows.md
user: login: francisco-cocozza
body: Same here, the name is just "Role" (or Cluster Role, in case it's defined at the Cluster level)
created_at: 2025-05-02T00:19:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,105 @@
+---
+title: "Service account for Promotion Workflows"
+description: "Understand the service account and role requirements for Promotion Workflows"
+group: promotions
+toc: true
+---
+
+
+
+## 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 service role
+
+If you need a service 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 service account and service role
path: _docs/promotions/service-accounts-promotion-workflows.md
user: login: francisco-cocozza
body: Example of a Service Account and a Role
created_at: 2025-05-02T00:20:43Z
author_association: CONTRIBUTOR
path: _docs/promotions/promotion-hooks.md
user: login: francisco-cocozza
body: Suggestion:
I'm missing the spec of a Promotion Flow (the YAML spec|schema)
Also, this section: "When are promotion hooks triggered?" should have a link to that schema.
That way, the user can associate these events with the spec and understand them better.
created_at: 2025-05-02T15:48:13Z
author_association: CONTRIBUTOR
path: _docs/promotions/promotion-hooks.md
user: login: francisco-cocozza
body: Clarification:
I think the Promotion Flow spec|schema should be here:
http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/gitops/promotions/promotion-flow/

So later, other sections, such as "When are promotion hooks triggered?" (in [promotion-hooks](http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/gitops/promotions/promotion-hooks/ )), can reference it.
created_at: 2025-05-02T15:51:30Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,281 @@
+---
+title: "Configure hooks in Promotion Workflows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+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.   
+
+{% 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%"
+%}
+
+Promotion hooks use the same mechanism as standard Promotion Workflows but run with additional context and scope on releases and environments. 
+Unlike Pre- and Post-Action Promotion Workflows, which operate on each application within environments, promotion hooks run once 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.
+
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a product release:  
+* **Release**: When Promotion Flow trigger creates a product release:
+  * **On release start**: When a release is initiated  
+  * **On release end**: When a release completes, whether **successful** or **failed** 
+* **Per environment**: When a release transitions through specific environments:  
+  * **On start**: When the promotion reaches an environment
+  * **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).
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire product 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.  
+
+Explore examples in [Codefresh Hub for Argo](https://codefresh.io/argohub/){:target="\_blank"}.
+
+##### Arguments in promotion hooks
+A default set of arguments are available to all Promotion Workflows with hooksd. See [Default arguments in Promotion Workflows with hooks](#default-arguments-for-promotion-hooks).
path: _docs/promotions/promotion-hooks.md
user: login: francisco-cocozza
body: hooksd --> hooks
created_at: 2025-05-02T15:53:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,281 @@
+---
+title: "Configure hooks in Promotion Workflows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+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.   
+
+{% 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%"
+%}
+
+Promotion hooks use the same mechanism as standard Promotion Workflows but run with additional context and scope on releases and environments. 
+Unlike Pre- and Post-Action Promotion Workflows, which operate on each application within environments, promotion hooks run once 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.
+
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a product release:  
+* **Release**: When Promotion Flow trigger creates a product release:
+  * **On release start**: When a release is initiated  
+  * **On release end**: When a release completes, whether **successful** or **failed** 
+* **Per environment**: When a release transitions through specific environments:  
+  * **On start**: When the promotion reaches an environment
+  * **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).
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire product 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.  
+
+Explore examples in [Codefresh Hub for Argo](https://codefresh.io/argohub/){:target="\_blank"}.
+
+##### Arguments in promotion hooks
+A default set of arguments are available to all Promotion Workflows with hooksd. See [Default arguments in Promotion Workflows with hooks](#default-arguments-for-promotion-hooks).
path: _docs/promotions/promotion-hooks.md
user: login: francisco-cocozza
body: This link:
`[Default arguments in Promotion Workflows with hooks](#default-arguments-for-promotion-hooks).`
doesn't work for me
created_at: 2025-05-02T15:54:21Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,281 @@
+---
+title: "Configure hooks in Promotion Workflows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+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.   
+
+{% 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%"
+%}
+
+Promotion hooks use the same mechanism as standard Promotion Workflows but run with additional context and scope on releases and environments. 
+Unlike Pre- and Post-Action Promotion Workflows, which operate on each application within environments, promotion hooks run once 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.
+
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a product release:  
+* **Release**: When Promotion Flow trigger creates a product release:
+  * **On release start**: When a release is initiated  
+  * **On release end**: When a release completes, whether **successful** or **failed** 
+* **Per environment**: When a release transitions through specific environments:  
+  * **On start**: When the promotion reaches an environment
+  * **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).
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire product 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.  
+
+Explore examples in [Codefresh Hub for Argo](https://codefresh.io/argohub/){:target="\_blank"}.
+
+##### Arguments in promotion hooks
+A default set of arguments are available to all Promotion Workflows with hooksd. See [Default arguments in Promotion Workflows with hooks](#default-arguments-for-promotion-hooks).
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+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**    |
path: _docs/promotions/promotion-hooks.md
user: login: francisco-cocozza
body: I think that if we're making reference to "Pre- and Post-Action Workflows", then the second column should be "Promotion Hooks Workflows" (without the `in`)
created_at: 2025-05-02T15:55:51Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,281 @@
+---
+title: "Configure hooks in Promotion Workflows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+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.   
+
+{% 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%"
+%}
+
+Promotion hooks use the same mechanism as standard Promotion Workflows but run with additional context and scope on releases and environments. 
+Unlike Pre- and Post-Action Promotion Workflows, which operate on each application within environments, promotion hooks run once 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.
+
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a product release:  
+* **Release**: When Promotion Flow trigger creates a product release:
+  * **On release start**: When a release is initiated  
+  * **On release end**: When a release completes, whether **successful** or **failed** 
+* **Per environment**: When a release transitions through specific environments:  
+  * **On start**: When the promotion reaches an environment
+  * **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).
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire product 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.  
+
+Explore examples in [Codefresh Hub for Argo](https://codefresh.io/argohub/){:target="\_blank"}.
+
+##### Arguments in promotion hooks
+A default set of arguments are available to all Promotion Workflows with hooksd. See [Default arguments in Promotion Workflows with hooks](#default-arguments-for-promotion-hooks).
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+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**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release.  | Provide information on promoted changes in applications within an environment.    |
path: _docs/promotions/promotion-hooks.md
user: login: francisco-cocozza
body: I think the Purpose of Promotion Hooks could be expanded to "Provide information on the release and its environments" (or something similar)

created_at: 2025-05-02T15:57:00Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,281 @@
+---
+title: "Configure hooks in Promotion Workflows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+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.   
+
+{% 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%"
+%}
+
+Promotion hooks use the same mechanism as standard Promotion Workflows but run with additional context and scope on releases and environments. 
+Unlike Pre- and Post-Action Promotion Workflows, which operate on each application within environments, promotion hooks run once 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.
+
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a product release:  
+* **Release**: When Promotion Flow trigger creates a product release:
+  * **On release start**: When a release is initiated  
+  * **On release end**: When a release completes, whether **successful** or **failed** 
+* **Per environment**: When a release transitions through specific environments:  
+  * **On start**: When the promotion reaches an environment
+  * **On success**: When the promotion completes successfully in an environment  
+  * **On failure**: When the promotion fails in an environment
path: _docs/promotions/promotion-hooks.md
user: login: scme0
body: I feel like we should do something like this here, to keep it consistent:
```suggestion
* **Release**: When Promotion Flow trigger creates a product release:
  * **On start**: When a release is initiated  
  * **On success**: When a release completes successfully
  * **On failure**: When a release fails
* **Per environment**: When a release transitions through specific environments:  
  * **On start**: When the promotion reaches an environment
  * **On success**: When the promotion completes successfully in an environment  
  * **On failure**: When the promotion fails in an environment
```
created_at: 2025-05-05T07:25:24Z
author_association: CONTRIBUTOR
path: _docs/promotions/promotion-hooks.md
user: login: NimRegev
body: So far, all the YAML specs are collated in https://codefresh.io/docs/docs/promotions/yaml/.
From each topic, I have a link to the relevant YAML. 

I think that's more usable because having the YAML specs as part of the same topic, will make it overly long and complicated.
created_at: 2025-05-11T10:12:09Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,281 @@
+---
+title: "Configure hooks in Promotion Workflows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+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.   
+
+{% 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%"
+%}
+
+Promotion hooks use the same mechanism as standard Promotion Workflows but run with additional context and scope on releases and environments. 
+Unlike Pre- and Post-Action Promotion Workflows, which operate on each application within environments, promotion hooks run once 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.
+
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a product release:  
+* **Release**: When Promotion Flow trigger creates a product release:
+  * **On release start**: When a release is initiated  
+  * **On release end**: When a release completes, whether **successful** or **failed** 
+* **Per environment**: When a release transitions through specific environments:  
+  * **On start**: When the promotion reaches an environment
+  * **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).
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire product 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.  
+
+Explore examples in [Codefresh Hub for Argo](https://codefresh.io/argohub/){:target="\_blank"}.
+
+##### Arguments in promotion hooks
+A default set of arguments are available to all Promotion Workflows with hooksd. See [Default arguments in Promotion Workflows with hooks](#default-arguments-for-promotion-hooks).
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+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**    |
path: _docs/promotions/promotion-hooks.md
user: login: NimRegev
body: Yes, I had that in the beginning but changed it later. I think I'll add a heading Promotion Workflows and then two column headings below Promotion Hooks and Pre-and Post-Action

created_at: 2025-05-11T10:13:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,281 @@
+---
+title: "Configure hooks in Promotion Workflows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+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.   
+
+{% 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%"
+%}
+
+Promotion hooks use the same mechanism as standard Promotion Workflows but run with additional context and scope on releases and environments. 
+Unlike Pre- and Post-Action Promotion Workflows, which operate on each application within environments, promotion hooks run once 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.
+
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a product release:  
+* **Release**: When Promotion Flow trigger creates a product release:
+  * **On release start**: When a release is initiated  
+  * **On release end**: When a release completes, whether **successful** or **failed** 
+* **Per environment**: When a release transitions through specific environments:  
+  * **On start**: When the promotion reaches an environment
+  * **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).
+
+##### Use cases for promotion hooks
+* Auditing and visibility  
+  Capture details on the entire product 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.  
+
+Explore examples in [Codefresh Hub for Argo](https://codefresh.io/argohub/){:target="\_blank"}.
+
+##### Arguments in promotion hooks
+A default set of arguments are available to all Promotion Workflows with hooksd. See [Default arguments in Promotion Workflows with hooks](#default-arguments-for-promotion-hooks).
+
+## Promotion hooks vs. Pre- and Post-Action Promotion Workflows
+
+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**    |
+|----------------|----------------------|-----------------------------------------------|
+| **Purpose**    | Provide information on the release.  | Provide information on promoted changes in applications within an environment.    |
path: _docs/promotions/promotion-hooks.md
user: login: NimRegev
body: I don't see this title anymore so I added to Promotion hooks overview 
created_at: 2025-05-11T10:13:58Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,105 @@
+---
+title: "Service account for Promotion Workflows"
+description: "Understand the service account and role requirements for Promotion Workflows"
+group: promotions
+toc: true
+---
+
+
+
+## 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 service role
+
+If you need a service 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 service account and service role
path: _docs/promotions/service-accounts-promotion-workflows.md
user: login: NimRegev
body: Same as above; fixed the role but leaving in lowercase
created_at: 2025-05-11T10:23:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,228 @@
+---
+title: "Hooks in Promotion Flows"
+description: "Configure hooks to capture release- and environment-level events in promotion releases"
+group: promotions"
+toc: true
+---
+
+
+## What are promotion hooks?
+
+Promotion hooks in Codefresh GitOps are specialized workflows that run at key points during a promotion release. A promotion release is created when a Promotion Flow is manually or automatically triggered.   
+Promotion hooks are implemented using the same underlying mechanism as standard Promotion Workflows, but run with additional context and scope—on releases and environments. 
+
+Unlike Pre- and Post-Action Promotion Workflows, which run in specific environments and target individual applications, promotion hooks run at the release or environment level. They are not tied to a particular deployment or application, and enable real-time alerts, custom logic and actions without requiring users to monitor the promotion directly in the UI. This allows teams to stay informed and take action instantly as promotions progress.
+
+DIAGRAM
+
+
+##### When are promotion hooks triggered?  
+Promotion hooks can run at different stages of a release:  
+* **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:  
+  * **On start**: When the promotion reaches an environment.  
+  * **On success**: When the promotion completes successfully in an environment.  
+  * **On failure**: When the promotion fails in an environment.  
+
+##### Use cases for promotion hooks
path: _docs/promotions/promotion-hooks.md
user: login: NimRegev
body: Done
created_at: 2025-05-11T10:40:14Z
author_association: CONTRIBUTOR

PR comments:
user: login: codefresh-git-integration[bot]
created_at: 2025-04-09T08:45:45Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-09T08:54:50Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-09T09:21:41Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-09T09:42:46Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-21T10:02:41Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-23T07:28:35Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-23T11:25:47Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-24T07:34:12Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-24T07:46:34Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-24T08:37:11Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-24T10:37:29Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-24T10:43:04Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-27T11:59:03Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-27T13:39:18Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-28T12:59:08Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-28T13:19:23Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-28T13:27:21Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-04-28T13:58:54Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-05-07T12:36:54Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-05-07T13:03:55Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-05-07T13:05:52Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-05-11T11:06:02Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-05-13T10:49:41Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-05-14T08:26:23Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE
user: login: codefresh-git-integration[bot]
created_at: 2025-05-14T08:30:18Z
body: "[CI] Staging environment is at http://staging-docs.codefresh.io.s3-website.us-east-1.amazonaws.com/gitops-auto-promotion-req/docs/"
author_association: NONE