Azure DevOps Integration

Integrate Toggly with Azure DevOps Build and Release pipelines to automate feature flag management, release tracking, and deployment workflows.

Overview

The Toggly Azure DevOps extension provides custom pipeline tasks that enable you to:

🚀 Create and manage releases with feature flag changes
🔗 Associate builds with releases for complete traceability
🎛️ Create and update feature flags from pipelines
🌍 Configure feature flags per environment
✅ Activate releases with automated quality gates
↩️ Automatically roll back features on deployment failures
📊 Display rich release information in build summaries

Installation

From Azure DevOps Marketplace

Visit the Azure DevOps Marketplace
Search for "Toggly Feature Flags"
Click Get it free
Select your Azure DevOps organization
Click Install

The extension will be available in all projects within your organization.

Configuration

Step 1: Get OAuth2 Credentials

Log in to Toggly
Navigate to Team Settings → API Credentials
Click Create New Credential
Set the following:
- Name: "Azure DevOps Integration"
- Scopes: Select apiAccess
Click Create
Copy the Client ID and Client Secret (you won't see the secret again!)

Step 2: Create Service Connection

In Azure DevOps, go to your project
Navigate to Project Settings → Service connections
Click New service connection
Search for and select Toggly Feature Flags
Fill in the connection details:
- Service connection name: Toggly-Production (or your preferred name)
- Client ID: Paste your OAuth2 Client ID
- Client Secret: Paste your OAuth2 Client Secret
- Authority URL: https://auth.toggly.io (default)
- API URL: https://app.toggly.io/api (default)
Click Verify connection to test
Click Save

tip

Create separate service connections for different environments (e.g., Toggly-Staging, Toggly-Production)

Available Tasks

1. Toggly - Create Release

Creates a new Toggly release to track feature flag changes and deployments.

- task: TogglyCreateRelease@1
  inputs:
    connectedService: 'Toggly-Production'
    applicationId: 'your-app-id'
    name: 'Release $(Build.BuildNumber)'
    releaseNotes: |
      ## Release $(Build.BuildNumber)
      
      Changes deployed in this release.

Inputs:

connectedService (required): Service connection name
applicationId (required): Your Toggly application ID
name (required): Release name (supports Azure DevOps variables)
releaseNotes (optional): Markdown-formatted notes
featureChanges (optional): JSON array of feature changes

Outputs:

Toggly.ReleaseId: The created release ID
Toggly.ReleaseUrl: URL to view the release in Toggly

2. Toggly - Associate Build

Associates the current Azure DevOps build with a Toggly release, providing complete traceability.

- task: TogglyAssociateBuild@1
  inputs:
    connectedService: 'Toggly-Production'
    projectKey: 'your-app-id'
    environment: 'Production'
    mode: 'use-latest-draft-or-create'

Inputs:

connectedService (required): Service connection name
projectKey (required): Application ID or project name
environment (required): Target environment (Production, Staging, etc.)
mode (required): How to find/create release
- use-latest-draft-or-create: Use latest draft release or create new
- create-new: Always create a new release
- use-latest-draft: Use latest draft only (fail if none exists)
releaseTemplateKey (optional): Template for creating releases
namePattern (optional): Pattern for release name (e.g., Release ${branch} - ${buildNumber})

Outputs:

Toggly.ReleaseId: The associated release ID
Toggly.ReleaseUrl: URL to view the release

3. Toggly - Create Feature

Creates a new feature flag in Toggly.

- task: TogglyCreateFeature@1
  inputs:
    connectedService: 'Toggly-Production'
    applicationId: 'your-app-id'
    featureName: 'New Dashboard'
    featureKey: 'new-dashboard'
    description: 'Redesigned user dashboard'
    tags: 'ui, dashboard, v2'

Inputs:

connectedService (required): Service connection name
applicationId (required): Application ID
featureName (required): Display name for the feature
featureKey (required): Unique identifier (used in code)
description (optional): Markdown description
category (optional): Feature category
tags (optional): Comma-separated tags

Outputs:

Toggly.FeatureKey: The created feature key

4. Toggly - Update Feature

Updates metadata for an existing feature flag.

- task: TogglyUpdateFeature@1
  inputs:
    connectedService: 'Toggly-Production'
    applicationId: 'your-app-id'
    featureKey: 'new-dashboard'
    description: 'Updated: Dashboard with real-time updates'

Inputs:

connectedService (required): Service connection name
applicationId (required): Application ID
featureKey (required): Feature to update
featureName (optional): New display name
description (optional): New description
category (optional): New category
tags (optional): New comma-separated tags

5. Toggly - Update Feature Environment

Enable, disable, or configure a feature flag on a specific environment.

# Enable a feature
- task: TogglyUpdateFeatureEnv@1
  inputs:
    connectedService: 'Toggly-Production'
    applicationId: 'your-app-id'
    environment: 'Production'
    featureKey: 'new-dashboard'
    action: 'enable'

# Gradual rollout (20%)
- task: TogglyUpdateFeatureEnv@1
  inputs:
    connectedService: 'Toggly-Production'
    applicationId: 'your-app-id'
    environment: 'Production'
    featureKey: 'new-checkout'
    action: 'custom'
    filters: |
      [{
        "name": "PercentageFilter",
        "parameters": { "Value": 20 }
      }]

Inputs:

connectedService (required): Service connection name
applicationId (required): Application ID
environment (required): Target environment
featureKey (required): Feature to configure
action (required): enable, disable, or custom
filters (optional): JSON array of filters (required when action is custom)

6. Toggly - Activate Release

Activates a release, applying all feature flag changes. Can wait for quality gates.

- task: TogglyActivateRelease@1
  inputs:
    connectedService: 'Toggly-Production'
    releaseId: '$(Toggly.ReleaseId)'
    waitForGates: true
    gateTimeout: 600

Inputs:

connectedService (required): Service connection name
releaseId (optional): Release ID (defaults to $(Toggly.ReleaseId))
waitForGates (optional): Wait for gates to pass (default: false)
gateTimeout (optional): Max wait time in seconds (default: 300)
gatePollInterval (optional): Poll interval in seconds (default: 10)

7. Toggly - Rollback Release

Rolls back a release, restoring feature flags to their previous state.

- task: TogglyRollbackRelease@1
  condition: failed()  # Only run on failure
  inputs:
    connectedService: 'Toggly-Production'
    releaseId: '$(Toggly.ReleaseId)'
    reason: 'Deployment failed - automatic rollback'

Inputs:

connectedService (required): Service connection name
releaseId (optional): Release ID (defaults to $(Toggly.ReleaseId))
reason (optional): Reason for rollback (for audit trail)

Common Scenarios

Scenario 1: Basic Deployment with Release Tracking

Track deployments and feature changes:

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

variables:
  TogglyConnection: 'Toggly-Production'
  AppId: 'app-12345'

stages:
  - stage: Build
    jobs:
      - job: Build
        steps:
          # Create release
          - task: TogglyCreateRelease@1
            inputs:
              connectedService: '$(TogglyConnection)'
              applicationId: '$(AppId)'
              name: 'Release $(Build.BuildNumber)'
              releaseNotes: |
                ## Release $(Build.BuildNumber)
                Branch: $(Build.SourceBranchName)
                Commit: $(Build.SourceVersion)

          # Associate build
          - task: TogglyAssociateBuild@1
            inputs:
              connectedService: '$(TogglyConnection)'
              projectKey: '$(AppId)'
              environment: 'Production'

          # Your build steps
          - script: |
              npm install
              npm run build
              npm test

  - stage: Deploy
    dependsOn: Build
    jobs:
      - deployment: DeployProd
        environment: Production
        strategy:
          runOnce:
            deploy:
              steps:
                # Deploy your application
                - script: |
                    kubectl apply -f deployment.yaml

                # Activate release
                - task: TogglyActivateRelease@1
                  inputs:
                    connectedService: '$(TogglyConnection)'

Scenario 2: Deployment with Quality Gates and Rollback

Use gates to validate deployment quality and automatically rollback on failure:

- stage: Deploy
  jobs:
    - deployment: DeployProduction
      environment: Production
      strategy:
        runOnce:
          deploy:
            steps:
              # Deploy application
              - script: |
                  echo "Deploying to production..."
                  kubectl apply -f k8s/deployment.yaml
                  kubectl wait --for=condition=ready pod -l app=myapp --timeout=300s

              # Activate with gates
              - task: TogglyActivateRelease@1
                inputs:
                  connectedService: 'Toggly-Production'
                  releaseId: '$(Toggly.ReleaseId)'
                  waitForGates: true
                  gateTimeout: 600  # 10 minutes
                  gatePollInterval: 15

              # Post-deployment validation
              - script: |
                  echo "Running smoke tests..."
                  npm run smoke-tests

          on:
            failure:
              steps:
                # Automatic rollback on any failure
                - task: TogglyRollbackRelease@1
                  inputs:
                    connectedService: 'Toggly-Production'
                    releaseId: '$(Toggly.ReleaseId)'
                    reason: 'Deployment or validation failed - automatic rollback'

Scenario 3: Progressive Feature Rollout

Gradually roll out a feature to users:

- stage: ProgressiveRollout
  jobs:
    - job: Phase1
      displayName: 'Rollout to 10%'
      steps:
        - task: TogglyUpdateFeatureEnv@1
          inputs:
            connectedService: 'Toggly-Production'
            applicationId: 'app-12345'
            environment: 'Production'
            featureKey: 'new-checkout-flow'
            action: 'custom'
            filters: |
              [{
                "name": "PercentageFilter",
                "parameters": { "Value": 10 }
              }]

        # Monitor for 30 minutes
        - script: sleep 1800

    - job: Phase2
      displayName: 'Rollout to 50%'
      dependsOn: Phase1
      steps:
        - task: TogglyUpdateFeatureEnv@1
          inputs:
            connectedService: 'Toggly-Production'
            applicationId: 'app-12345'
            environment: 'Production'
            featureKey: 'new-checkout-flow'
            action: 'custom'
            filters: |
              [{
                "name": "PercentageFilter",
                "parameters": { "Value": 50 }
              }]

        # Monitor for 30 minutes
        - script: sleep 1800

    - job: Phase3
      displayName: 'Full Rollout'
      dependsOn: Phase2
      steps:
        - task: TogglyUpdateFeatureEnv@1
          inputs:
            connectedService: 'Toggly-Production'
            applicationId: 'app-12345'
            environment: 'Production'
            featureKey: 'new-checkout-flow'
            action: 'enable'

Scenario 4: Multi-Environment Deployment

Deploy to multiple environments with different configurations:

stages:
  - stage: DeployStaging
    jobs:
      - deployment: Staging
        environment: Staging
        strategy:
          runOnce:
            deploy:
              steps:
                - task: TogglyAssociateBuild@1
                  inputs:
                    connectedService: 'Toggly-Staging'
                    projectKey: 'app-12345'
                    environment: 'Staging'

                # Enable all features in staging
                - task: TogglyUpdateFeatureEnv@1
                  inputs:
                    connectedService: 'Toggly-Staging'
                    applicationId: 'app-12345'
                    environment: 'Staging'
                    featureKey: 'experimental-feature'
                    action: 'enable'

                - task: TogglyActivateRelease@1
                  inputs:
                    connectedService: 'Toggly-Staging'

  - stage: DeployProduction
    dependsOn: DeployStaging
    jobs:
      - deployment: Production
        environment: Production
        strategy:
          runOnce:
            deploy:
              steps:
                - task: TogglyAssociateBuild@1
                  inputs:
                    connectedService: 'Toggly-Production'
                    projectKey: 'app-12345'
                    environment: 'Production'

                # Keep experimental features disabled in production
                - task: TogglyUpdateFeatureEnv@1
                  inputs:
                    connectedService: 'Toggly-Production'
                    applicationId: 'app-12345'
                    environment: 'Production'
                    featureKey: 'experimental-feature'
                    action: 'disable'

                - task: TogglyActivateRelease@1
                  inputs:
                    connectedService: 'Toggly-Production'
                    waitForGates: true

Build Summary

The extension automatically adds rich release information to your Azure DevOps build summary:

📋 Release name and status
🎯 Feature flag changes
✅ Gate status and evaluation results
🔗 CI/CD build links
🌐 Direct link to view release in Toggly

This provides complete visibility of feature flag changes directly in your pipeline results.

Pipeline Variables

The extension sets these variables that can be used in subsequent tasks:

Variable	Description	Set By Tasks
`Toggly.ReleaseId`	The release ID	Create Release, Associate Build
`Toggly.ReleaseUrl`	URL to view release in Toggly	Create Release, Associate Build
`Toggly.FeatureKey`	The feature key	Create Feature

Use these variables in subsequent tasks:

- task: TogglyCreateRelease@1
  inputs:
    # ... inputs ...

# Use the release ID in a later task
- task: TogglyActivateRelease@1
  inputs:
    connectedService: 'Toggly-Production'
    releaseId: '$(Toggly.ReleaseId)'  # Uses variable from previous task

Best Practices

1. Use Service Connections per Environment

Create separate service connections for each environment:

Toggly-Development
Toggly-Staging
Toggly-Production

This provides better security and isolation.

2. Always Use Rollback Tasks

Add rollback tasks to your deployment jobs:

strategy:
  runOnce:
    deploy:
      steps:
        # ... deployment steps ...
    on:
      failure:
        steps:
          - task: TogglyRollbackRelease@1
            inputs:
              connectedService: 'Toggly-Production'

3. Use Gates for Production

Enable gates for production deployments:

- task: TogglyActivateRelease@1
  inputs:
    connectedService: 'Toggly-Production'
    waitForGates: true
    gateTimeout: 600

4. Track All Deployments

Always associate builds with releases:

- task: TogglyAssociateBuild@1
  inputs:
    connectedService: 'Toggly-Production'
    projectKey: 'your-app'
    environment: 'Production'

5. Use Release Notes

Include meaningful release notes:

- task: TogglyCreateRelease@1
  inputs:
    connectedService: 'Toggly-Production'
    applicationId: 'your-app'
    name: 'Release $(Build.BuildNumber)'
    releaseNotes: |
      ## Release $(Build.BuildNumber)
      
      ### Changes
      $(Build.SourceVersionMessage)
      
      ### Build
      - Branch: $(Build.SourceBranchName)
      - Commit: $(Build.SourceVersion)
      - Build: $(Build.BuildNumber)

Troubleshooting

Authentication Errors

Problem: "Service connection not found" or "Authentication failed"

Solutions:

Verify the service connection name matches exactly
Check OAuth2 credentials are valid and haven't expired
Ensure the API token has apiAccess scope
Test the service connection in Azure DevOps settings

Application Not Found

Problem: "Application not found" or "Access denied"

Solutions:

Verify the Application ID is correct
Check your API credentials have access to the application
Ensure you're a member of the team that owns the application

Gate Timeout

Problem: Gates timeout before passing

Solutions:

Increase the gateTimeout value
Check gate configurations in Toggly UI
Review gate evaluation logs in Toggly
Verify metrics are being collected properly

Variable Not Set

Problem: $(Toggly.ReleaseId) is empty

Solutions:

Ensure a previous task (Create Release or Associate Build) ran successfully
Check task execution order in your pipeline
Verify the tasks are in the same job (variables don't persist across jobs)

Support

Need help with the Azure DevOps integration?

Overview​

Installation​

From Azure DevOps Marketplace​

Configuration​

Step 1: Get OAuth2 Credentials​

Step 2: Create Service Connection​

Available Tasks​

1. Toggly - Create Release​

2. Toggly - Associate Build​

3. Toggly - Create Feature​

4. Toggly - Update Feature​

5. Toggly - Update Feature Environment​

6. Toggly - Activate Release​

7. Toggly - Rollback Release​

Common Scenarios​

Scenario 1: Basic Deployment with Release Tracking​

Scenario 2: Deployment with Quality Gates and Rollback​

Scenario 3: Progressive Feature Rollout​

Scenario 4: Multi-Environment Deployment​

Build Summary​

Pipeline Variables​

Best Practices​

1. Use Service Connections per Environment​

2. Always Use Rollback Tasks​

3. Use Gates for Production​

4. Track All Deployments​

5. Use Release Notes​

Troubleshooting​

Authentication Errors​

Application Not Found​

Gate Timeout​

Variable Not Set​

Further Reading​

Support​

Overview

Installation

From Azure DevOps Marketplace

Configuration

Step 1: Get OAuth2 Credentials

Step 2: Create Service Connection

Available Tasks

1. Toggly - Create Release

2. Toggly - Associate Build

3. Toggly - Create Feature

4. Toggly - Update Feature

5. Toggly - Update Feature Environment

6. Toggly - Activate Release

7. Toggly - Rollback Release

Common Scenarios

Scenario 1: Basic Deployment with Release Tracking

Scenario 2: Deployment with Quality Gates and Rollback

Scenario 3: Progressive Feature Rollout

Scenario 4: Multi-Environment Deployment

Build Summary

Pipeline Variables

Best Practices

1. Use Service Connections per Environment

2. Always Use Rollback Tasks

3. Use Gates for Production

4. Track All Deployments

5. Use Release Notes

Troubleshooting

Authentication Errors

Application Not Found

Gate Timeout

Variable Not Set

Further Reading

Support