Azure DevOps – Split Help Center

The Split integration with Azure DevOps gives you access to Split feature flags within your workspace which enables a streamlined workflow when you are managing your deployment. Use this integration to:

Customize rollouts: With feature flags, teams can strategically enable rollouts as needed, including canary releases, dark launches, and A/B tests.
Save time: Teams can associate feature flags with items in development with menus and native integration. You no longer have to switch between solutions.

Within Azure DevOps, you can:

Select a feature flag to associate with a given work item
Create a feature flag directly within your project
Automatically configure feature flag rollout plans with each pipeline run
Directly link Azure work items to the Split application

Within Split, you can view your Azure work items connected to each feature flag and the associated status and assignee.

The following flowchart shows how this integration works:

Set up in Split

To start, you need to first set up in Split by doing the following:

From the left hand navigation, click the user's initials at the bottom, and select Admin settings.
Click Integrations.
Locate the Azure DevOps selection, and click Add. A list of workspaces displays.
Select the workspace you want to set the integration up for. This allows you to map each instance of the integration to a Microsoft Azure DevOps project.
Enter your Azure Org ID and optionally enter your Azure personal access token (PAT) and click Save. This takes you back to the marketplace.
From the Azure selection, click Edit. The Connect to Azure DevOps page displays with your generated Split token.
Copy your Split token to configure your Split extension in Azure.

Set up in Azure DevOps

Once you have performed your setup in Split, you can set up your extension in Azure DevOps. The following sections describe how to install and set up an extension.

Install an extension in Azure DevOps organization

The following explains how to install your extension in Azure DevOps organization. To install your Split extension, do the following:

Go to Azure marketplace and click the Split extension. The Split extension displays.
Click Get it free. This brings the extension into your Azure organization. The Split for Azure page displays.
Select your organization and click Install. The extension installs.
Once the installation completes, click Proceed to organization. The Projects page with a list of your projects displays.

Set up an extension

Once you install your extension, you can set it up in the Azure DevOps organization. To set up the extension, do the following:

Go to Azure DevOps project dashboard and click Project Settings.
Select Service connections.
Click New service connections. A new service connection area displays.
Select Split and click Next.
In the Project name field, enter a unique name per service connection.
In the Split token field, enter your Split token that's associated with the workspace you want to map the environment to and click Verify.
In the Service connection name field, enter a name. Be sure to name it in a way that is specific to the workspace that the integration was configured to and allows you to remember the name you enter. Following this pattern, you can map multiple workspaces to a single project in Azure DevOps.
In the Description field, optionally enter a description.
Add all necessary users or groups to the service connection's security settings. Be aware that to work with Split's Azure DevOps integration, you must be assigned a User role or higher.
Click Verify and save to establish and save the connection. A successful service connection displays as Active on the Split integration page. You can now connect your work items to feature flags and configure release tasks.

Use the Azure integration

This section provides instructions on how to use the Azure DevOps integration with Split. From here, you connect your work items to feature flags, which allows you to see what work pertains to which feature flag. You can also automate the creation and update of feature flag targeting rules with pipeline tasks.

Connect feature flags with Azure work items

You can connect your work items with the associated feature flag in Split. To connect a work item to a feature flag, do the following:

From the Work item screen, select the Split tab on the right hand side. The Split fields display in the page.
In the Service connection field, select the desired service connection.
In the Split field, you can:

- Create a new feature flag. If you create a new flag, enter the name, traffic type, and optionally a description.
- Select one or more flags to link to.

Update feature flag targeting definitions with pipeline task

You can trigger feature flag definition changes as part of your deployment process.The targeting definitions can be written both in YAML or via Azure’s task builder. You can create the definition by selecting Split from the tasks menu in the pipeline editing screen. You can then select the desired service connection, workspace, and environment. You can also customize your target definition. To configure your definitions, do the following:

From the Azure Project settings page, click Pipelines from the left hand navigation.
On the right-hand menu, click … menu and then Edit. The pipeline yml page displays.
On the Tasks menu, select the Splits task. The configuration fields display.
In the Service connection field, select the desired service connection.
In the Workspace field, select the desired workspace you want to work on.
In the Environment field, select the desired environment. This updates the targeting rules of this feature flag in this environment.
Under the targeting definition section, the default targeting definition displays. You can customize this definition to something other than 0% ON and 100% OFF. Similar to our API, enter the JSON representation of the targeting definition in this field. Refer to the sample JSON payload below. For more information, refer to our Create Split definition in environment API documentation or if you have questions, contact support@split.io.
Click Add to add this task to the YML file.

Sample JSON payload

The following is a sample payload.

{
  "treatments": [
    {
      "name": "on",
      "description": "feature enabled",
      "keys": [
        "some-user-id"
      ],
      "configurations": "{\"color\":\"green\"}"
    },
    {
      "name": "off",
      "description": "feature disabled",
      "configurations": "{\"color\":\"red\"}"
    }
  ],
  "defaultTreatment": "off",
  "baselineTreatment": "off",
  "trafficAllocation": 40,
  "rules": [
    {
      "buckets": [
        {
          "treatment": "off",
          "size": 100
        }
      ],
      "condition": {
        "combiner": "AND",
        "matchers": [
          {
            "type": "IN_LIST_STRING",
            "strings": [
              "John",
              "Mary"
            ]
          }
        ]
      }
    }
  ],
  "defaultRule": [
    {
      "treatment": "off",
      "size": 100
    }
  ]
}

Visualize Azure work items in Split

Once you link your Azure work items, you can visualize your key work item information associated with a feature flag. To visualize your work items, do the following:

Within the Work items page of Azure DevOps, click the Split tab. The associated feature flags display.
In the desired work item, click the link icon. This takes you to Split.
Click the Integrations tab. You can now visualize your Azure information in Split.

Troubleshooting

The following errors may occur when you run a job:

Targeting definition could not be updated because the feature flag exists in another workspace

If the workspace in the pipeline task (also known as the agent task in Azure) is different from the workspace in the work item, the pipeline task does not create a targeting rule.
Targeting definition could not be updated because a definition already exists in the environment

When you create a work item that is linked to an existing build, and there are more than one flags associated with it, some of the flags get updated but others do not. This action occurs because the targeting rules were already created within the pipeline's environment for that flags.
Targeting definition could not be updated because of environment change permission settings

Currently, the integration only updates targeting rules if change permissions are disabled in the pipeline's environment. If the permissions are enabled in the pipeline's environment, no flag is updated.
Targeting definition could not be updated because of an invalid definition structure

When you define a custom rollout option and you make a syntactical or semantic error in the treatment definition, the task fails when it runs because of a validation error.
Task failed due to invalid JSON

If the JSON has invalid formatting, the task cannot be parsed and it fails.