Improve this page on GitHub

Configuring app version and promotable properties

Configure application version and properties to promote for products

Automating and customizing which changes are selected for promotion between environments ensures that only the necessary modifications are advanced, enhancing both accuracy and efficiency. By defining clear criteria for the changes to promote, you can streamline the promotion process while ensuring compliance with environment-specific requirements.

Benefits of automating selection of changes for promotion

Precision through automation
Automating the selection of changes for promotion allows you to define which updates are moved forward, removing the need for manual diff reviews. This functionality is invaluable when managing promotions for large-scale applications with large numbers of microservices and configuration files.
Enforce environment-specific requirements
Each environment has distinct constraints and requirements. By automating which changes are promoted, you can ensure that only the updates are valid for each environment are promoted, ensuring compliance with environment-specific needs.
While artifact versions and image tags typically warrant promotion for instance, other changes may be excluded based on the target environment’s specific requirements.

Primary aspects when promoting applications

When defining which changes to promote, there are two primary aspects to focus on:

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, you can configure the changes to promote between the product’s applications in the different environments.
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, they are 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
Configuring promotion flows and triggers for products
Tracking product releases
Creating products