From Digital.ai Release 10.2, you can use GitOps-enabled version control to store and track changes to folder entities in the form of YAML files (Releasefile.yaml) within a Git repository.

Preparing your Folder for GitOps-enabled Version Control

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

1. Enable folder version control
2. Configure a Git repository connection
3. Configure folder version control
4. Migrate the passwords on Configurations and Templates

Enable Folder Version Control

You can enable or disable the folder version control feature on the Settings > System Features > Feature flags tab. See Configure Experimental Settings for more information.

Configure a Git Repository Connection

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

• On a global level in Configuration > Connections
• On a folder level, under the Connections tab of the desired folder

To setup a git repository connection:

1. In Digital.ai Release, go 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 address of the repository server as follows: http(s)://address:port/repository
   • In the Authentication Method field, select the authentication method used for authenticating to the remote repository
   • In the Username and Password fields, enter the user ID and password/personal token

note

To use the personal access token for Github and Bitbucket, select Basic from the drop-down list in the Authentication Method field.

4. To test the connection, click Test

note

This will not test if the user has push permissions on the remote repository (required for Saving versions).

5. To save the configuration, click Save

Configure Folder Version Control

To setup folder versioning for a given folder:

1. Select a folder and click Version control
2. Click on the Configure button
3. Select a Git repository from the dropdown, or click on 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. Select a Repository path in the repository where you want the Releasefile.yaml to be stored. By default, the path is the name of the folder. This path will also serve as tag prefix when you create new version.
6. Select which entities you want exported to the local repository in the generated Releasefile.yaml 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.

In the Version control settings page, there were two versioning styles:

• one file per type
• Single file

Now, a new versioning style Multiple files per type is added. This versioning style applies only to selected entities like Templates, Patterns, Triggers, and Dashboards. This style when selected the above mentioned entities are exported to the selected GIT repository in YAML format. Here, you can have 2 templates in YAML format with different names.

Migrate Passwords to Password Variables

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

Using Gitops-Enabled Folder Version Control

Listing The Version History

When you visit the Version control tab, there will be a list of commits under Version history. Only the commits that are tagged in Git, where the tags begin with the same tag prefix as the configured tag prefix in folder versioning configuration, are listed. The commits are ordered by the creation date. The first element in the list (Current) is the current state of your folder before it is saved. The elements under Previous versions are the commits that exist in the Git repository.

In order to view the Releasefile.yaml content of the commit, you must select it and press Preview code.

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. In order 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

In order 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. Type in the Name field. This field will be used in the tag of the commit and appended to the configured tag prefix
5. Type 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

note

To save a new version, you need the Create new version permission. See Version control permissions for details.

Applying an Existing Version

In order set the state of the folder to the one described in the Releasefile.yaml of one of the previous versions:

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 the apply was successful, the version that was applied will have an Applied badge on it, until a new version gets saved.

note

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

Folder Versioning Enhancements

From Release 22.0, Gitops-enabled folder versioning feature is enhanced with additional functionalities and improvements to validation.

Ignore Git Connection in YAML File

The Git connection used by the folder versioning feature is no longer considered for versioning in the Releasefile.yaml file. You can now use the Git connection in the folder where the versioning is enabled without accidentally breaking the connection if you save the Git: Repository page with incorrect details.

Transactional Apply

If there is an error when you apply the Releasefile.yaml file using Gitops-enabled folder versioning, the operation will be rolled back. The CI events—the events that are triggered when a CI is created or updated in the database—will be triggered only after the entire YAML file is processed and successfully applied. When you perform the apply operation in a folder, all the triggers that are running in the folder will be temporarily disabled during the transaction. The triggers will be enabled after the transaction is completed.

Delete Orphans/Overwrite

When you apply the Releasefile.yaml file using Gitops-enabled folder versioning, all the entities that are found in the folder, but not in the YAML file are deleted and log entries of the orphan entities are generated. The entity types that are not included in the YAML file, but are not tracked will not be deleted.

To remove the entities from tracking, do as follows:

1. On the navigation pane, in the Overview group, click Folders.

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

3. From the navigation pane, click Version Control.

4. In the Version Control page, click Configure

5. From the Select the entities to export section, click the toggle switch next to the entity you want to enable or disable. The entities that you disable will not be exported to the Git repository.

   

Note:

• Orphan entities are not deleted in certain cases, for example, deletion of a configuration that is being used by a trigger. In such cases, the apply operation will be successful, but log entries of the orphan entities are generated.
• There could be releases that are running inside the subfolders. Therefore, releases inside the folder and the subfolders are not deleted.

Create a New Version Permission

The Create a new version option provides the folder-level permission to generate generate everything within the folder. This permission is required to generate anything in YAML using Gitops-enabled folder version control feature.

To enable the permission:

1. On the navigation pane, in the Overview group, click Folders.

2. In the Folders page, click the folder for which you want to enable the folder-level permission.

3. From the navigation pane, click Teams & Permissions.

4. Under the Version control section, click the empty box next to Create a new version, and type the user persona to whom you want to enable the folder-level permission, for example, Release Admin.

5. Click Save.

   

Note:

• By default, the folder owners have the Create a new version permission.
• 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.

Password Placeholders

When you create a new version, all the properties containing passwords that are generated in Releasefile.yaml file will be replaced by !value tags with placeholders, for example !value "jenkins_Server_jenkins1_password". The actual passwords are not displayed in the YAML file.

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.