diff --git a/_data/nav.yml b/_data/nav.yml
index fc57071eb..afedb8a14 100644
--- a/_data/nav.yml
+++ b/_data/nav.yml
@@ -368,6 +368,12 @@
- title: Troubleshooting Argo CD applications
url: "/troubleshooting-gitops-apps"
+- title: Promotions
+ url: "/promotions"
+ pages:
+ - title: Promotion Policies
+ url: "/promotion-policy"
+
- title: Pipelines
url: "/pipelines"
pages:
diff --git a/_docs/promotions/promotion-policy.md b/_docs/promotions/promotion-policy.md
new file mode 100644
index 000000000..700dfdeb8
--- /dev/null
+++ b/_docs/promotions/promotion-policy.md
@@ -0,0 +1,319 @@
+---
+title: "Configure Promotion Policies"
+description: "Run validations through Promotion Policies to assess environment readiness before orchestrating promotion"
+group: promotions
+toc: true
+---
+
+
+
+
+When a promotion is triggered for a product in an environment, it's essential to validate the environment's readiness before deploying changes and promoting the Product.
+Readiness validation ensures that the product's applications and their dependencies meet the necessary requirements and standards for deployment in the target environment.
+These validations include various checks, such as code quality, unit or smoke tests, compatibility with dependencies, security compliance,
+and other relevant factors specific to the target environment.
+
+##### Promotion Policies for readiness validation
+Codefresh empowers you to create and automate environment readiness validations through Promotion Policies.
+A Promotion Policy combines promotion settings defining workflows to validate environment readiness, and targets defining the products or environments for which to implement the Policies.
+
+The Policies can be tailored for any combination of Products and Environments, or be generic to match all Products and Environments, giving you the flexibility you need to implement the most complex to the most simple of policies.
+
+You can create dedicated Promotion Policies, or define them as part of a Promotion Flow which orchestrates the promotion and deployment of the Product across all Environments.
+
+DIAGRAM
+
+Review the [settings](#promotion-policy-settings) you can configure for a Promotion Policy, and how to [create a Promotion Policy](#create-a-promotion-policy).
+
+##### Promotion Policy implementation
+More than one Promotion Policy can match the same target Product or Environment.
+The logic for applying Promotion Policy settings is based on predefined priorities and target attributes.
+[Promotion Policy logic](#promotion-policy-logic) details different scenarios and examples describing the implementation logic.
+
+
+
+
+
+
+## Key features of Promotion Policies
+
+* **Automated validation**
+ Validations defined in the Promotion Policy are enforced automatically, minimizing the risk of errors, and ensuring consistency and reliability in deployments.
+
+* **Flexible configuration**
+ Promotion Policies are highly customizable to match your requirements. Define Policies per Product, per Environment,
+ or with broader coverage for a specific Product across all environments, or only by specific types of Environments.
+
+* **Priority-driven enforcement**
+In cases where multiple Promotion Policies match Products, Environments, or a combination of both, Codefresh merges Promotion Settings from matching Policies in order of priority, ensuring seamless enforcement.
+
+* **On-demand evaluation**
+Visualize Promotion Settings applied to a Product-Environment pair with Evaluate Promotion Policy option. Not only does this option identify Product-Environment pairs which do match existing Promotion Policies, it also identifies misconfigured policies.
+
+* **Git-based and custom promotion actions**
+Whether your promotion actions are Git-based or utilize custom repositories and mechanisms for compiling application repositories, Codefresh supports both types of actions.
+
+
+
+See ???
+
+
+
+
+
+## Promotion Policy settings & targets
+
+A Promotion Policy comprises the Policy's promotion settings and the Policy's targets.
+The table below describes the settings and targets you can define for a Promotion Policy.
+
+{% include
+image.html
+lightbox="true"
+file="/images/promotions/promotion-policy-settings.png"
+url="/images/promotions/promotion-policy-settings.png"
+alt="Promotion Policy settings"
+caption="Promotion Policy settings"
+max-width="60%"
+%}
+
+
+
+{: .table .table-bordered .table-hover}
+| Item | Description |
+| -------------- | -------------- |
+|**Name** | The name of the Promotion Policy.
The name must be unique in the cluster and must match Kubernetes naming conventions. |
+|**Promotion Settings** | The settings that comprise the Promotion Policy.
{::nomarkdown} - Pre-Action Workflow: Optional. The Promotion Workflow to run before the Promotion Action.
- ActionRequired. The Promotion Action to update the target application's source repository:
- Commit: Perform a Git commit on the source repository. Commits are implemented immediately without not requiring manual approval to move to the next stage of the Promotion Policy.
- Pull Request: Open a pull request (PR) on the change to the source repository. Depending on your PR policy, this option may require manual approval to move to the nex stage.
- No Action: Run the selected Pre-Action Workflow, and the Post-Action Workflow if any, without performing a commit or opening a pull request on the application's source repository.
This option is useful to run custom promotion policy mechanisms, not involving updating the target application's source repository to promote the application.
{:/}See [Promotion Workflows]({{site.baseurl}}/docs/promotions/promotion-workflow/).|
+|**Products** |Single or multiple Products to which to apply the Promotion Policy.
Match Products by the name or names defined. |
+|**Environments** |Single or multiple Environments to which to apply the Promotion Policy. {::nomarkdown}- Kind: Match Environments by their type, either Pre-production or Production.
- Environment: Match Environments by the name or names defined.
{:/}|
+|**Priority** |The priority assigned to the Promotion Policy. The priority determines how and which Promotion Settings are applied when two or Polices match the target attributes. The priority is a positive or negative integer and defined in ascending order.
To understand how Promotion Settings are implemented, see [Promotion Policy implementation logic](#promotion-policy-implementation-logic).|
+
+
+## Best practices for Promotion Policies
+
+TBD
+Examples showing when to set by environment, by product and others
+
+## Promotion Policy implementation logic
+
+Every Promotion Policy can define a few or all promotion settings, and one or more Products or Environments as targets.
+When a Promotion Policy is to be run to validate readiness for an environment, promotion settings are merged from all matched policies based on their priority.
+Policies with higher priority always take precedence over those with lower priority.
+
+
+### Example Promotion Policies
+
+Let's consider a few different Promotion Polices. As you can see in the table below, each Policy has a name, priority, validation settings, and target attributes.
+Note that not all settings are defined or configured for all policies. But all policies have a pre-defined Priority, and one or both target attributes.
+
+{: .table .table-bordered .table-hover}
+| Promotion Policy | |
+| Name |Priority |Pre-Action Workflow | Action | Post-Action Workflow | Products | Environments |
+| -----------| ----------| ------------------ | ---------------------| ----------| -------------|
+| pp-demo | 20 |send-slack-alert | commit |- | demo | - |
+| pp-notify | 300 |send-slack-alert-1 | ?? |send-slack-success-fail | demo | - |
+| pp-pre-prod |200 | | commit | validate-deployment | - | ENV_TYPE=non-prod |
+| pp-prod |100 | send-slack-alert | pr |- |- | ENV_TYPE=prod |
+
+
+(NIMA: will convert this into a diagram)
+
+
+### Promotion Policies in Trigger Environments
+TBD
+
+
+
+
+
+
+### Scenario 1: Applying Promotion Policies with identical target attributes
+This scenario reviews how Promotion Policy settings are applied when at least two Policies match the same target attributes.
+
+**Goal**: Promote `demo` product
+**Matched Promotion Policies**:
+ * `pp-demo` with the target Product attribute, `demo`
+ * `pp-notify` also with target Product attribute, `demo`
+**Apply Promotion Policy**:
+When more than one Policy matches the promotion requirement, the same Product in this case, the Priority determines how Policy settings are applied.
+* **Priority**: Promotion Policy `pp-demo` has the highest priority (priority is in ascending order)
+* **Promotion Policy settings**:
+ * Pre-Action Workflow: Configured for `pp-demo` as `send-slack-alert`
+ * Action: Configured for `pp-demo` as `commit`
+ * Post-Action Workflow:
+ Not configured for `pp-demo`
+ The Promotion Policy with the next highest priority that defines a Post-Action is `pp-notify`, as `send-slack-success-fail`
+
+##### Summary
+The promotion policy `pp-demo` has the highest priority (20), so its Pre-Action (`send-slack-alert`) and Action (`commit`) are applied.
+The Post-Action comes from `pp-notify`, the Policy with the next highest priority that defines a Post-Action.
+
+
+### Scenario 2: Applying Promotion Policies with different target attributes
+
+This scenario reviews how Promotion Policy settings are applied when two Policies have different target attributes that match the requirements.
+
+**Goal**: Promote `demo` product to all non-production environments
+**Matched Promotion Policies**:
+ * `pp-pre-prod` matches target Environment, `ENV_TYPE=non-prod`
+ * `pp-demo` matches target Product, `demo`
+**Apply Promotion Policy**:
+When there are no specific attributes, the Priority determines how Policy settings are applied.
+* **Priority**: Promotion Policy `pp-demo` has the highest priority (priority is in ascending order)
+* **Promotion Policy settings**:
+ * Pre-Action Workflow: Configured for `pp-demo` as `send-slack-alert`
+ * Action: Configured for `pp-demo` as `commit`
+ * Post-Action:
+ Not configured for `pp-demo`
+ The Promotion Policy with the next highest priority that defines a Post-Action is `pp-notify`, as `send-slack-success-fail`
+
+##### Summary
+The promotion policy `pp-demo` has the highest priority (20), so its Pre-Action (`send-slack-alert`) and Action (`commit`) are applied.
+The Post-Action comes from `pp-notify`, the Policy with the next highest priority that defines a Post-Action.
+
+## Create a Promotion Policy
+Create a Promotion Policy to validate an environment's readiness before promoting and deploying changes to a Product.
+
+##### Before you begin
+
+* Create [Promotion Workflows]({{site.baseurl}}/docs/promotions/promotion-policy/)
+
+##### How to
+
+1. In the Codefresh UI, on the toolbar, click the **Settings** icon, and then from Promotions in the sidebar, select [Promotion Policies](https://g.codefresh.io/2.0/?????){:target="\_blank"}.
+1. Do one of the following:
+ * To create your first Promotion Policy, click **Add Policy**.
+ * If you have already Promotion Policies, click **Add** at the bottom of the list.
+1. Select the mode in which to define the Promotion Policy as **YAML** or **Form**.
+ You can toggle between the modes as you define the Promotion Policy.
+1. Define the **Policy Settings**, as described in XREF:
+1. Define how and which **Products** to select for this Promotion Policy.
+1. Define how and which **Environments** to select for this Promotion Policy.
+1. Commit the changes.
+ The Promotion Policy is added to the Promotion List.
+
+## Promotion Policy list
+
+Here's an example of the Promotion Policy page which displays all Promotion Policies in the account. This is also the location from which you can create and manage existing policies.
+SCREENSHOT
+
+* If there are multiple Promotion Policies that match the same Product or Environments, the Priority determines how Promotion Policy settings are applied.
+* The **Evaluate Promotion Policy** functionality allows you to select any Product and Environment pair and visualize the Promotion Settings that will be applied from all the Promotion Policies that match the selected pair. See [Evaluate Promotion Settings for Products and Environments ](#match-promotion-policies-to-products-and-environments).
+
+
+## Evaluate Promotion Settings for Products and Environments
+Select a specific Product-Environment pair and preview the Promotion Settings that will be applied for it.
+
+Evaluate Promotion Policies to identify:
+* Product-Environment pairs that don't match any existing Promotion Policies
+* Missing Promotion Settings
+* Possible conflicts with Promotion Flows
+* How to optimize existing Policies
+
+If there are multiple Policies with either identical or different target attributes that match the Product-Environment selected, Codefresh merges Promotion Settings from all matched polices based on the priority of each Policy and the [implementation logic](#promotion-policy-implementation-logic).
+
+##### How to
+
+1. In the Codefresh UI, on the toolbar, click the **Settings** icon, and then from Promotions in the sidebar, select **Promotion Policies**.
+1. In the Promotion Policies page, click **Evaluate Promotion Policy**.
+
+{% include
+image.html
+lightbox="true"
+file="/images/promotions/evaluate-promotion-policy.png"
+url="/images/promotions/evaluate-promotion-policy.png"
+alt="Evaluate Promotion Policy"
+caption="Evaluate Promotion Policy"
+max-width="60%"
+%}
+
+{:start="3"}
+1. Select the Product and Environment for which to evaluate the Promotion Policy, and click **Preview Promotion**.
+ The Result summarizes the Promotion Settings that will be applied for the selected pair from all matched Promotion Policies.
+ * If there are messages on misconfigured Policies, see [Evaluate Promotion Settings for Products and Environments](#match-promotion-policies-to-products-and-environments).
+ * On the right, select the Workflows if defined to view manifests.
+
+{% include
+image.html
+lightbox="true"
+file="/images/promotions/promotion-policy-evaluation-result.png"
+url="/images/promotions/promotion-policy-evaluation-result.png"
+alt="Previewing results for Promotion Policy evaluation"
+caption="Previewing results for Promotion Policy evaluation"
+max-width="60%"
+%}
+
+{:start="4"}
+1. If required, update the Promotion Settings for one or more Promotion Policies.
+
+
+
+
+
+### Understand results from Promotion Policy evaluation
+When you evaluate Promotion Policies, in addition to identifying Products and Environments that do not match any existing Policies, you can also identify misconfigured Policies.
+
+Misconfigured Policies include:
+* [Action missing in matched Policies](#action-missing-in-matched-policies)
+* [Pre-Action Workflow does not include required step with promotion action](#pre-action-workflow-does-not-include-required-step-with-promotion-action)
+
+#### No Promotion Policy matches
+
+#### Action missing in matched Policies
+
+**Message**
+Unable to apply any Promotion Policy for the selected Product-Environment pair.
+SCREENSHOT OF MESSAGE
+
+**Reason**
+Promotion Action has not been configured in any of the Policies that match the selected Product-Environment pair.
+Promotion Policy cannot be applied to the pair.
+
+
+**Corrective action**
+Promotion Policies must be configured with an Action: Commit, Pull request, or No Action.
+
+
+#### Pre-Action Workflow does not include required step with promotion action
+**Message**
+Promotion Flow will fail for the selected Product-Environment pair.
+Merged Promotion Settings from the matched Promotion Policies define No Action as the Promotion Action, but either matched Promotion Policies do not include a Pre-Action Workflow or Pre-Action Workflows do not include a step to initiate a corresponding promotion action.
+Configure or update a Pre-Action Workflow in one of the matched Promotion Policies as required.
+
+
+**Reason**
+When No Action is configured as a Promotion Setting, one of the matched Promotion Policies:
+* Must be configured with a Pre-Action Workflow
+* Pre-Action Workflow must include a step that initiates or executes the corresponding Promotion Action
+
+**Corrective action**
+Configure one of the matched Promotion Policies with a Pre-Action Workflow.
+Make sure it includes a step to execute the Promotion Action that will promote the changes in the environment.
+
+## Edit/delete Promotion Policies
+Manage Promotion Policies by updating settings for existing Promotion Policies, and deleting unused Policies.
+
+>**NOTES**
+When editing Promotion Policy settings, you cannot change the name.
+
+Deleting a Promotion Policy removes it from all the Products and Environments it is assigned to.
+
+## Visualize Promotion Workflows in Releases
+
+When a product is promoted manually or automatically, the promotion mechanism create a release for the product with a unique release ID. The release provides a graphical representation of the promotion flow across the environments defined for it.
+The visualization includes the Pre- and Post-Action Promotion Workflows within the environments, more specifically, the steps within the workflows.
+
+SCREENSHOT
+
+For more information, see [Promotion Workflows in Product Releases]({{site.baseurl}}/docs/promotions/releases/#promotion-workflows-in-product-releases).
+
+## Related articles
+TBD
\ No newline at end of file
diff --git a/images/promotions/add-promotion-policy.png b/images/promotions/add-promotion-policy.png
new file mode 100644
index 000000000..53ecd1be7
Binary files /dev/null and b/images/promotions/add-promotion-policy.png differ
diff --git a/images/promotions/evaluate-promotion-policy.png b/images/promotions/evaluate-promotion-policy.png
new file mode 100644
index 000000000..c039d0ebe
Binary files /dev/null and b/images/promotions/evaluate-promotion-policy.png differ
diff --git a/images/promotions/promotion-policy-evaluation-result.png b/images/promotions/promotion-policy-evaluation-result.png
new file mode 100644
index 000000000..0629738a4
Binary files /dev/null and b/images/promotions/promotion-policy-evaluation-result.png differ
diff --git a/images/promotions/promotion-policy-list.png b/images/promotions/promotion-policy-list.png
new file mode 100644
index 000000000..3e6ee5525
Binary files /dev/null and b/images/promotions/promotion-policy-list.png differ
diff --git a/images/promotions/promotion-policy-settings.png b/images/promotions/promotion-policy-settings.png
new file mode 100644
index 000000000..269f03a74
Binary files /dev/null and b/images/promotions/promotion-policy-settings.png differ