GitOps-enabled Folder Versioning

Overview

This guide explains how to use GitOps-enabled folder version control in Digital.ai Release. With this feature, you can manage the contents of a folder—such as templates, triggers, patterns, and other configuration entities—using a connected Git repository. Versioning allows you to track changes, view commit history, apply previous versions, and keep environments in sync.

You need to follow these steps to use GitOps-enabled version control on a folder:

1. Enable Git Folder Versioning
2. Set Up a Git repository Connection
3. Configure Git Folder Versioning
4. Handling Passwords in Configurations and Templates

Enable Git Folder Versioning

GitOps-enabled version control allows you to store folder content—such as templates, variables, and configurations—as YAML code in Git. This enables a GitOps-style workflow to author, review, and promote content across Release environments.

• To enable or disable this feature, go to Settings > System settings > General and use the Enable GitOps Folder Version Control checkbox. For more information, see GitOps Version Control (Recommended).

• By default, the Enable GitOps Folder Version Control checkbox is selected, enabling GitOps-based version control in your Release environments.

  note

  You must have Administrator access to change this setting.

• When Enable GitOps Folder Version Control checkbox is selected, a Version control tab appears under the Configuration section of the selected folder.

  

Set Up a Git Repository Connection

There are two locations where you can define a Git repository connection:

• Global level: From the left navigation menu, under the CONFIGURATION section, click the Connections tab.
• Folder level: Select the desired folder, and under the CONFIGURATION section, click the Connections tab.

To set up a Git repository connection:

1. In Digital.ai Release, navigate to one of the two specified locations.
2. Click the + icon next to Git: Repository
3. Enter the following details:
   • In the Title field, enter a name for the configuration.
   • In the URL field, enter the repository path (including repository name).
   • In the Authentication method field, select the authentication method used for authenticating to the remote repository.
   • To connect, you can:
     • Use your Username and Password, or
     • Use a Personal Access Token (PAT).
       note

       If using a PAT, select Basic as the authentication method and paste the token into the Password field. The Username field can be left empty.

4. Click Test to verify the connection.
5. Click Save to save the configuration.

Configure Folder Version Control

To configure folder versioning for a given folder:

1. Select the folder, go to CONFIGURATION, and click Version control.

2. Click Configure button.

3. Select a Git repository from the dropdown, or click New repository if you don't have one.

4. Select a branch that you want to synchronize with. The branch must already exist on the remote repository.

5. Enter the Repository path where you want the folder contents to be stored as YAML files.
   By default, this path matches the name of the folder being versioned and is used as the tag prefix when creating a new version.

   Example Tag Format

   If the folder path is main and the version is v1.0.0, the resulting Git tag will be main/v1.0.0 — a combination of the folder path and version to represent a specific version.

6. Select a Versioning style from the dropdown list (as described in the table) to export entities to the Git repository.
   This setting determines how many YAML files are generated in source control.

   tip

   Entities refer to: Templates, Workflows, Patterns, Triggers, Variables, Connections, Dashboards, Notifications, Teams & Permissions, Applications, and Environments.

   Versioning style	Multiple files – one per entity	Multiple files – one per type	Single file
   Description	Each supported entity is exported as a separate YAML file.	Entities are grouped by type; each type is exported as a single YAML file.	All entities and subfolders are combined into a single YAML file.
   Applicable to entities	Separate files are generated for: Templates, Workflows, Patterns, Triggers and Dashboards This strategy does not apply to: Applications, Environments, Connections, Notifications, Permissions and Variables. These are always grouped in one file per type.	Applies to all available entities. Each type is exported into a separate file.	Applies to all available entities. All content is included in a single file.
   Example	Separate files: TemplateA.yaml , TemplateB.yaml Workflow1.yaml , Workflow2.yaml Entities for which this strategy is not applicable: Environments.yaml (Dev, QA, Prod) Variables.yaml (all variables)	Templates.yaml (all templates) Workflows.yaml (all workflows) Environments.yaml (all environments)	Releasefile.yaml containing all entities
   Output (number of files)	• One file per entity (for supported types) • One file per type (for grouped entities)	One file per entity type	Always a single file

7. Click Save.

   note

   To configure folder version control, you need the Edit version control settings permission. See Version control permissions for details.

   After the folder versioning is configured, Release will start cloning the repository locally, which might take a couple of minutes if the repository is very large.

Enable or Disable Entity Export

To enable or disable export of entities:

1. In the navigation pane, under the OVERVIEW group, click Folders.

2. In the Folders page, click the folder you want to modify.

3. In the navigation pane, click Version control.

4. In the Version Control page, click Configure.

5. In the Select the entities to export section:

   • Turn on the toggle next to each entity you want to export to the Git repository in YAML format.
   • Turn off the toggle to prevent an entity from being exported.

   

Using GitOps-Enabled Folder Version Control

With GitOps-enabled folder version control, you can view version history, pull updates from the Git repository, save new versions, and restore folder configurations using previously saved versions.

Listing the Version History

When folder version control is configured and the user has sufficient permissions to view it, find the tagged version (commit) history by selecting Version control from the left navigation pane in the folder. Only Git commits that are tagged with a prefix matching the configured tag prefix in the folder versioning configuration settings are displayed. These commits are listed in descending order by creation date, with the newest at the top.

• The first item in the list, labeled Current, represents the unsaved state of your folder, including any changes that have not been committed yet.

• The Applied version indicates the currently active version that has been applied and is also stored in the Git repository.

  note

  If changes were made after this version was applied, they will appear under Current.

• Items under Previous versions correspond to the tagged commits stored in the Git repository.

  

To preview a specific commit, choose the corresponding YAML file from the selector.

note

To list versions and preview YAML, you need the View version control permission. See Version control permissions for details.

Fetching Latest Changes

The commits listed in Version history are from the local repository on Release server. To synchronize with the latest changes on remote repository, you must click Fetch changes. When you hover over Fetch changes you will see the date the last time a fetch was done.

note

To fetch changes, you need the View version control permission. See Version control permissions for details.

Saving a New Version

To export the current state of the folder into the remote repository:

1. Go to Version control.
2. Under Version history, click Current (pre-selected).
3. Click Save as a new version.
4. Enter the version name in the Version name field.
   This field will be used in the tag of the commit and appended to the configured tag prefix.
   Example Tag Format

   If the folder path is main and the version is v1.0.0, the resulting Git tag will be main/v1.0.0 — a combination of the folder path and version to represent a specific version.

5. Enter the commit description in the Description field.
   This field will be used in the commit message. If left empty, the Name field will be used in the commit message.
6. Click Save.
   note

   • To save a new version, you need the create a new version permission. Folder owners have this permission by default. See Version control permissions for details.
   • For XL CLI users who do not have this permission, regular permission checks are applied, for example, you will require View template permission to generate templates.

Applying an Existing Version

To revert the folder to the state defined in the Releasefile.yaml of a previously saved version:

1. Go to Version control.
2. Under Version history click on a version you wish to apply.
3. Click Apply this version.
4. Click Apply in the modal. After a version is successfully applied, it will display an Applied badge until a new version is saved.
   note

   To apply a version, you need the Apply version permission. See Version control permissions for details.

Handling Passwords in Configurations and Templates

The passwords in versioned entities will not be exported, instead the generated Releasefile.yaml will have
!value somePassword placeholder tags. This is to avoid leaking passwords to a plain text file on an external server. The variables should be one of the following:

• Global password variables
• Folder password variables of a parent folder (not versioned)
• Folder password variables of the versioned folder, if you disable versioning for variables in folder version control configuration
• Folder password variables of the versioned folder, if they are External Password Variables with the Secrets Server configured outside the versioned folder

Password Placeholders

When you create a new version, all properties containing passwords in the generated YAML files are replaced with !value tags with placeholders. The actual passwords are never included or displayed in the YAML file.
For example:

!value "jenkins_Server_jenkins1_password"

This applies to password values found in:

• Connections - password/secret fields in versioned Connections
• Templates - properties, run automated tasks as user password field
• Templates - template tasks with Connection password/secret fields
• Triggers - passwords for Connections for Git, Jira, Nexus and others
• Triggers - create release password-type variable values
• Variables - password-type variable values

The mapping between placeholder and actual password of every version folder is saved and maintained in the Release database, and is automatically updated every time you create a new version or apply an old version. You can switch to an older folder version with different entities without losing the passwords, as the older mappings are not deleted.

note

• When you apply an existing version, the current folder state is generated and the mapping is updated before you apply the version.
• There is no UI to view the mapped values. However, you can use XL CLI to extract the password.

Password Validation Warnings

There are two types of warnings related to password validation:

• Warning about hard-coded passwords
• Warning about missing passwords

A Warning icon next to the version indicates about the warnings that must be resolved.

Warning About Hard-coded Passwords

When creating a new version, a warning message is displayed if any of the properties defined in the Releasefile.yaml file uses a hard-coded password (plain text password), and you try to save as new version.

You may create a new version by clicking Save with warnings button. However, we recommend you to resolve the warnings and use password variables instead of plain text passwords.

To resolve the warnings:

1. Click the link under the Title column.
   The folder template page is displayed.

2. In the Template details section, click the ${ toggle button to switch from password to password variable.

   

3. In the Password box, click to select the variable from the drop-down menu.
   

   note

   If you have not created a password variable already, you can create the variable from Configuration > Global variables. For more information, see Create Release Variables.

Warning About Missing Passwords

When applying an existing version, a warning message is displayed if any of the properties defined in the Releasefile.yaml file has placeholder in the password field (!value tags) but there is no password mapped to the placeholder in the Release database.

You may ignore the warnings after applying the version. The Password fields with missing passwords will be kept blank.

To resolve the warnings:

1. After you update the missing passwords for the properties in the YAML file, select Done check box under the Status column.

   

2. Click Close, and then click Apply this version.
   The Warning icon next to the version disappears.