-title:Promotion setup guidelines

url:"/create-promotion-sequence"

-title:Promotion Flows

url:"/promotion-flow"

-title:Promotion hooks

url:"/promotion-hooks"

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

-title:Promotion setup guidelines

url:"/create-promotion-sequence"

-title:Promotion Flows

url:"/promotion-flow"

-title:Promotion hooks

url:"/promotion-hooks"

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

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 storesconfiguration for GitOpspromotion 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.

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.

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:

* Triggerenvironment, the source of the changes being promoted

* TriggerEnvironment, 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)

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

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

</tr>

<tr>

</tr>

<tr>

</tr>

<tr>

title:"Promotion contexts for promotion hooks"

description:"Use promotion contexts to expose custom parameters to hooks in Promotion Flows"

group:promotions

toc:true

Promotion Workflows with hooks in GitOps Cloud 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, product, and commit SHA.

For promotion hooks to have access to additional, custom parameters that are not natively available, you need to use**promotion contexts**.

Because promotion hooks run within GitOps Runtimes in your own clusters, they do not automatically have access to 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, which is a user-defined JSON object. See[Creating and exporting a promotion context](#creating-and-exporting-a-promotion-context).

Each hook in the Promotion Flow has access to the information it needs, no matter where it's running.

This ability to pass custom data across hooks can help with scenarios like notifying specific Slack channels or tracking specific Jira tickets associated with the promotion process. See[Example of Promotion Workflow with promotion context](#example-of-promotion-workflow-with-promotion-context) and[How promotion context works during execution](#how-promotion-context-works-during-execution).

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.

Export the promotion context as an output parameter and make it available to the 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 match the name of the promotion context.

* Add the`valueFrom` attribute to reference the file path.

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.

...

spec:

...

-name:set-promotion-context

serviceAccountName:hook

inputs:

parameters:

-name:JIRA_ISSUE_SOURCE_FIELD

-name:JIRA_BASE_URL

script:

image:alpine

command:

-sh

source:|

outputs:

parameters:

-name:PROMOTION_CONTEXT# cannot be changed

globalName:PROMOTION_CONTEXT# name of promotion context

valueFrom:

path:/tmp/promotion-context.txt

...

When a hook exports a promotion context, the promotion mechanism passes those parameters to all subsequent hooks in the Promotion Flow, regardless of whether the 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

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

* Passes the default metadata (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

As the Flow progresses, the promotion mechanism:

* Retrieves the promotion context from the previous hook

* Passes the context automatically to the next hook as input parameters:

* New parameters are added to the input parameters of the next hook

* For existing parameters, the value of the parameter in the current hook always takes precedence

{% 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%"

%}

[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/)

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.

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.

For each environment, you can explicitly set the Promotion Policy that defines governs promotion behavior for the environment through the Promotion Action (required), andPre- 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%"

%}

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.

***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}<imgsrc="/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

%}

{:start="5"}

1. Optional. Toadd 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}<imgsrc="../../../../images/icons/flow-builder-add-workflow.png"display=inline-block>{:/}, and select a Workflow.

1. Optional. Toassign a workflow to validate the trigger environment after the change and commit action, mouse over the left of the environment node, and click {::nomarkdown}<imgsrc="../../../../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**.

{: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}<imgsrc="../../../../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`.

{% include

image.html

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**.

[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/)