Promotions: End-to-end guide

Step-by-step guide to creating, triggering, and monitoring promotions

This article covers the end-to-end flow of creating a promotion sequence, from initial setup to execution and monitoring.

A successful promotion sequence relies on several key components that govern and orchestrate the promotion flow across environments.

The sections that follow describe the steps you’ll need to configure for your specific deployment and compliance needs.

Prerequisites

1. Configuration Runtime
   The Configuration Runtime is a GitOps Runtime that stores the manifests of the 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.

2. Admin permissions
   Only account admins can create promotion entities such as Promotion Policies and Promotion Flows.

3. User permissions
   Users need permissions to create Promotion Workflows, configure product settings, and trigger promotions.

How to: Step-by-step

1. Create environments
   Environments define the starting and the end points of promotions.
   For a promotion sequence, you need at least two environments: the trigger environment, which is the source of the changes to promote, and the target environment, to which the changes need to be promoted.

2. Create applications
   Applications represent the components or services to be promoted and deployed, and are the smallest unit of deployment within a promotion sequence. To promote across an application across environments, you need an application for each target environment.
   Create Argo CD applications in our user interface. For seamless promotions, group related applications within a product to manage them collectively.

3. Create products
   Products connect related applications and group them as a single entity. Applications represent instances of products within each environment. Being able to apply promotion settings at the level of the product, and being able to promote applications belonging to the same product, simplifies promotion management.
   Create a product and connect related applications to it, either manually or declaratively.

4. Create promotion workflows
   As part of promoting changes across environments, it’s customary to run tests and validations that match the requirements of the target environments in the promotion sequence. For example, create workflows that run smoke tests to verify basic functionality or database validation checks to ensure data integrity. Create Promotion Workflows (Argo Workflows) to implement any type of tests, validations, and custom requirements.

5. Create policies to govern environment promotions
   Govern promotion behavior for environments by setting rules, checks, and validations that environments must meet before and after changes are promoted. Promotion Policies allow you to define these rules by combining Promotion Workflows and the promotion action based on environment type, product, or other criteria. When a promotion is triggered for an environment, the policy mechanism merges settings from all relevant global policies according to priority, providing automated governance for consistent and reliable promotion behavior.

6. Create promotion flows to orchestrate promotions
   Orchestrate the sequence of actions to move and deploy changes through the required environments, from the trigger environment to the final target environment.
   Promotion Flows ensure that changes are promoted in a controlled and predictable manner by integrating environments, products and applications, promotion workflows, and policies.

7. Configure promotion settings and flows for product
   After setting up the core and promotion-specific entities, configure additional promotion-specific settings for your product.
   These settings include the attributes to be promoted across the product’s applications (Product Promotion Templates), the promotion flows valid for the product and flow-specific trigger conditions (Promotion Flows).

8. Trigger promotions
   Trigger the promotion, either manually or automatically.

9. Track releases for products
   Monitor the deployment progress for the product as it moves through the promotion sequence.
   Use the Releases feature to track and ensure successful deployments across environments.

Related articles

About promotions
Promotion building blocks
Promotion tutorials
Trigger promotions
Tracking product releases