Improve this page on GitHub

Configuring version and promotable properties for Products

Configure application version and properties to promote for products

App version and promotable properties for Products

By default, when you promote a product across environments, all its applications and their properties are promoted. You may not need to promote everything, as not all properties change with every update, and different environments have different requirements. For example, while development environments may allow frequent updates, staging and production environments often require stricter controls.

By configuring the properties to promote, you ensure that only relevant updates move forward. This improves deployment accuracy, streamlines workflows, and enforces compliance with environment-specific constraints.

Why automate version and property selection?

Automating the selection of the application version and properties ensures that only relevant updates are promoted, improving accuracy, efficiency, and compliance with environment-specific constraints. This approach benefits teams managing complex applications by reducing manual oversight and enforcing structured deployments.

Key benefits of automated selection

Targeted, reliable promotions
Ensures only approved updates, such as tested builds, specific artifact versions, are promoted, minimizing deployment errors.
Environment-specific control
Defines promotable properties to enforce unique requirements per environment, allowing selective updates like image tags while excluding unnecessary modifications.
Scalability for complex applications
Eliminates manual diff reviews for large-scale applications with numerous microservices and configuration files, streamlining deployments.

Primary aspects when promoting applications

When defining which changes to promote, focus one these two aspects:

Defining the source for the application’s release version
Defining the changes to promote across multiple files in the applications

IMPORTANT
For automated retrieval of the application version and promotion of specific attributes from files across environments, all applications within the same product must maintain an identical structure.
Promotion across different environments requires consistent relative paths in each repository. For example, to promote properties from config/settings.yaml in environment dev to testing, config/settings.yaml must also exist in the testing environment.

Where can you configure settings for application version and properties?

In Product > Settings > Promotion Settings.
See also Promotion Settings & Promotion Templates.

Configure version and properties to promote in Product Settings

For how-to instructions, see Configure Promotion Settings.

Configuring versions for promoted applications

The Version attribute specifies the location from which to retrieve version information for the applications in the product.

NOTE The Environments, Product, and GitOps Apps dashboards display the product version only for Helm application types. For other application types, product versions are not displayed even when configured.

Example of version settings for promotion

The Version attribute is defined using a JSON path expression. It is relative to the spec.source.repoURL and spec.source.path attributes defined in the source application’s configuration manifest.

The diagram illustrates how the version attributes configured for the product are correlated with the repo URL and path defined in the application’s manifest to retrieve the correct version.

Version not displayed in dashboards

If the version is not displayed in the dashboards, it could be because your application is not a Helm application.
For Helm applications, if the version is either not displayed or is not correct, it could be because:
- Codefresh could not find the values in the repoURL and path. Verify that the Source settings for the application correspond to the Version attribute configured for the product.
- The JSON key includes a dash character which is not supported. See Dashes in JSON keys.

Examples of version attributes

You can extract version information from different attributes to ensure that it aligns with your deployment and business requirements.

Version attribute	Example configuration	JSON Path expression	Possible use case
Default version attribute	`appVersion: "1.2.3"`	`$.appVersion`	Commonly used in Helm charts or deployment manifests for explicit version management.
Semantic versioning	`version: "2.3.4"`	`$.version`	Indicate backward-compatible changes, new features, and bug fixes.
Image tag	`image: repository: "myrepo/app" tag: "1"`	`$.image.tag`	In containerized environments to manage versions tied to Docker images.
Git commit SHA	`git: commitSha: "abc123def456"`	`$.git.commitSha`	Track versions using specific Git commit SHAs, useful in CI/CD pipelines.
Build number	`build: number: "20230801-001"`	`$.build.number`	Include timestamps or incremental identifiers automatically generated during builds.
Release version	`release: version: "v4.5.6"`	`$.release.version`	Differentiate between stages of software maturity and deployment readiness (e.g., alpha, beta, production).
Deployment version	`deployment: version: "3.2.1"`	`$.deployment.version`	Manage versioning per deployment unit in environments with multiple components or microservices.
Custom metadata version	`metadata: name: "my-application" version: "5.4.3"`	`$.metadata.version`	Use custom metadata fields for additional versioning information specific to the organization or project.

Configuring properties for promotion across applications

Promotable Properties define the specific files or attributes within files which are selected for promotion between environments for the applications in a product. Although optional, defining these properties allow for precise control over which changes are included in a promotion, ensuring compliance with environment-specific requirements and preventing unwanted modifications.

Example of version settings configured and preview of version retrieved for application

IMPORTANT
When no Promotable Properties are defined, all files in the application’s source directory are promoted.
This can result in a large data transfer depending on the size of the directory.

Similar to how you define the Version attribute, Promotable Properties are also defined through JSON path expressions. Unlike the Version attribute, you can define multiple JSON path expressions to different files, or to multiple attributes within the same file.

Examples of properties for promotion

Here’s an example of the Promotable Properties configured for the applications of a Product.

You can see that properties are configured to be promoted from three different files, with values.yaml containing multiple properties to promote.

Example of properties configured for promotion

The following examples show how the JSON path expressions are resolved within the different YAML files. On the left, you can see the YAML manifests, on the right, the previews show how the trio-prod application resolves these values.

`version.yaml’ promoted property resolution & preview

`version.yaml`: Example of manifest (left) and preview (right) with resolved JSON path expression

`chart.yaml’ promoted property resolution & preview

`chart.yaml`: Example of manifest (left) and preview (right) with resolved JSON path expression — `version.yaml`: Example of manifest (left) and preview (right) with resolved JSON path expression

`values.yaml’ promoted property resolution & preview

`values.yaml`: Example of manifest (left) and preview (right) with resolved JSON path expression

JSON path expressions for files and properties

Application versions and properties to be promoted are defined through JSON path expressions. Each JSON expression points to the specified file and the location of the property within the file.

NOTE
Our promotions are optimized for YAML-based configuration files.
For non-YAML file types, JSONPath expressions may not evaluate as expected. In these cases, you have the option to promote the entire file using * as a wildcard.

Example of manifest (left) and preview (right) with resolved JSON path expression for version

Dashes in JSON keys

Dashes in JSON keys are currently not supported in path expressions using dot notation.

Workaround: Use square bracket notation to specify the path, as shown below, and double quotes within the brackets to escape the dashes.
For example:

$["rollout-Canary"]["image"]["tag"]

JSON syntax for YAML files

Here’s a brief summary of JSON syntax and rules. For detailed information, see JSON syntax.

$ JSON path expressions begin with the $ symbol, which represents the root of the YAML file.

$.. Extracts from all levels of the matching object. Use .. (double dot operator) to navigate and extract from any level within the YAML file.

.*
Extracts all properties. Use .* to retrieve all properties of the matching object.

This is an extract from a sample values.yaml file.

global: 
  codefresh:
    url: g.codefresh.io
    tls:
      create: false
argo-cd: 
  tls:
    create: true
    caCert: 'some-argo-cert'

Using the above syntax:

$.global.codefresh.* extracts all attributes that match the codefresh object in the file, which resolves to:
url: g.codefresh.io and tls.create.false
$..tls extracts values from all levels with tls, which resolves to:
create: false (from codefresh.tls object) create: true and caCert: some-argo-cert (both from argo-cd.tls object)

Promotion Settings & Promotion Templates

As with other GitOps entities, you can configure Promotion Settings for the product in either Form or YAML modes.

When you define an Inline template, configure, and commit the settings, the YAML generated, is saved as a promotion-template resource 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/configuration/promotion-templates/.
See Shared Configuration Repository and Designating Configuration Runtimes.

To configure directly in YAML, refer to our Promotion Template YAML.

Assigning applications to Products
Selecting Promotion Flows for Products
Tracking Product releases
Configure Product Settings