2.3 How to add a configuration migration

The GoCD configuration XML file is a very important part of GoCD. When adding new features or changing existing features, sometimes there will be a need to add/remove/modify certain sections of it. Since existing configuration XMLs should continue to work, even for existing users, a "configuration migration" will need to be added to migrate old XMLs.

The configuration XML has a schema version, and configuration migration scripts correspond to that version. These scripts use XSL transformations, and below is a quick guide on how to add a new configuration migration.

Assuming for example that

  • the current schema version is 71, and there's a config migration that removes the <license/> element. Here are the steps you would perform:
  • The project working directory is ~/projects/go

Step 1: Run an automated script to bump schema version

~/projects/go$ ./gradlew -q server:bumpSchemaVersion
Now edit the file ~/projects/go/config/config-server/resources/upgrades/72.xsl

This automated script will actually create and update a few files —

$ git status -s
 M base/src/com/thoughtworks/go/util/GoConstants.java
 M config/config-server/resources/cruise-config.xsd
?? config/config-server/resources/schemas/71_cruise-config.xsd
?? config/config-server/resources/upgrades/72.xsl

Step 2: Add XSL to transform the cruise-config.xml to from one version to the next

Edit the file that was printed on the console and perform the necessary migration.

~/projects/go$ vim ~/projects/go/config/config-server/resources/upgrades/72.xsl

The 72.xsl transformation looks like

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
    <xsl:template match="/cruise/@schemaVersion">
        <xsl:attribute name="schemaVersion">72</xsl:attribute>
    <!-- Copy everything -->
    <xsl:template match="@*|node()" name="identity">
            <xsl:apply-templates select="@*|node()"/>
    <!-- Remove matching node "<license>" -->
    <xsl:template match="//license" />

2.3.2 Testing the newly added migration

Configuration migration tests can be found in com.thoughtworks.go.config.GoConfigMigrationIntegrationTest. For example, a test to verify schema version 72 is written as follows.

public void shouldRemoveLicenseSection_asPartOfMigration72() throws Exception {
    String licenseUser = "Go UAT ThoughtWorks";
    String configWithLicenseSection =
            "<cruise schemaVersion='71'>"+
                "<server artifactsdir='logs' commandRepositoryLocation='default' serverId='dev-id'>" +
                    "   <license user='licenseuser'>"+
                    "       Hq6o5X...." +
                    "   </license>" +
                "  </server>" +

    String migratedContent = migrateXmlString(configWithLicenseSection, 71);
    assertThat(migratedContent, not(containsString("license")));
    assertThat(migratedContent, not(containsString("licenseuser")));

2.3.3 Bump up schema version under Functional tests

Once the configuration has been successfully migrated, schemaVersion under functional-tests repository needs to be changed.

To bump schemaVersion to 95
~/projects/functional-tests$ VERSION=95 rake bump-schema

This automated script will upgrade schema version

$ git status -s
  M src/test/java/com/thoughtworks/cruise/util/CruiseConstants.java
  M src/test/java/config/basic-cruise-config.xml
  M src/test/java/config/community-cruise-config.xml
  M src/test/java/config/conflict-cruise-config-for-pipelineAdmin.xml
  M src/test/java/config/conflict-cruise-config.xml
  M src/test/java/config/delete-package-cruise-config.xml
  M src/test/java/config/empty-cruise-config.xml
  M src/test/java/config/fanin-cruise-config.xml
  M src/test/java/config/group-admin-cruise-config.xml
  M src/test/java/config/invalid-cruise-config.xml
  M src/test/java/config/invalid-ldap-server-cruise-config.xml
  M src/test/java/config/invalid-package-cruise-config.xml
  M src/test/java/config/multiple-agents-cruise-config.xml
  M src/test/java/config/no-license-cruise-config.xml
  M src/test/java/config/package-repo-cruise-config.xml
  M src/test/java/config/permissions-cruise-config.xml
  M src/test/java/config/pipeline-api-cruise-config.xml
  M src/test/java/config/plugins-cruise-config.xml
  M src/test/java/config/secure-cruise-config.xml
  M src/test/java/config/stage-security-cruise-config.xml
  M src/test/java/config/template-admin-cruise-config.xml
  M src/test/java/config/tfs-cruise-config.xml
  M src/test/java/config/valid-ldap-server-cruise-config.xml
  M src/test/java/cruise-config.xsd

2.3.4 Bump up schema version under Ruby Functional tests

Once the configuration has been successfully migrated, schemaVersion under ruby-functional-tests repository needs to be changed.

To bump schemaVersion to 99
~/projects/functional-tests$ VERSION=99 GO_VERSION=17.12.0 rake bump-schema

This automated script will upgrade schema version

$ git status -s
 M resources/config/auth-plugins-config.xml
 M resources/config/basic-cruise-config.xml
 M resources/config/basic-secure-cruise-config.xml
 M resources/config/multiple-agents-cruise-config.xml
 M resources/config/secure-cruise-config.xml
 M resources/config/with-config-repo-cruise-config.xml

results matching ""

    No results matching ""