Feature/Bugfix Branch Deployment Guide

Overview

This guide documents how to deploy feature or bugfix branches using the Platform CI pipeline to the test environment for validation purposes. The CI pipeline is designed to deploy only specific services rather than the entire platform, which saves time and resources during development.

Pipeline Location

The CI pipeline configuration is located at:

• File: .azure-pipelines/test.yaml
• Azure DevOps Pipeline ID: 388
• Pipeline Name: Platform

Available Parameters

The CI pipeline supports multiple deployment parameters that can be configured to control what gets deployed:

Core Deployment Parameters

Parameter	Type	Default	Description
deployInfrastructure	boolean	true	Deploy Azure infrastructure components
deployHelmTemplates	boolean	true	Deploy Helm chart templates
deployServices	boolean	true	Deploy application services
deployDatabase	boolean	true	Deploy database changes
deploySsoPolicies	boolean	true	Deploy Single Sign-On policies
deployNuggetFeed	boolean	true	Deploy NuGet packages to internal feed
cleanupContainerTags	boolean	true	Clean up old container tags
deployPlatformPortal	boolean	false	Deploy Platform Portal frontend
deployAlloyKubernetes	boolean	true	Deploy Alloy monitoring components

Service Configuration

The services parameter accepts an array of service objects. Each service can contain multiple containers:

[
  {
    "name": "SingleSignOn",
    "containers": [
      {
        "name": "singlesignon-api",
        "path": "SingleSignOn.WebApi/",
        "dockerBuild": true
      }
    ]
  }
]

Available Services

The following services are available for deployment:

• ApiManagement: API Gateway and console
• Billing: Billing service
• Cerbos: Authorization service
• ContractManagement: Contract management API
• DocumentVault: Document storage service
• MessageBus: Message bus API
• Monitoring: Alloy monitoring
• Notifications: Notification API
• Onboarding: User onboarding service
• PlatformProducts: Platform products API
• ProductManagement: Product management API and durable functions
• Quoting: Quoting API
• SingleSignOn: Single Sign-On API
• TenantManagement: Tenant management API
• TransactionManagement: Transaction management API
• Verifiers: Various verification services

Recommended Approach: Single Service Deployment

For feature/bugfix branch validation, the recommended approach is to deploy only the service that contains your changes. This approach:

• ✅ Minimizes deployment time
• ✅ Reduces resource consumption
• ✅ Isolates testing to affected components
• ✅ Prevents unnecessary infrastructure changes

Example: Deploying Only SingleSignOn Service

# Using Azure DevOps CLI or API
az devops invoke --area build --resource builds --route-parameters project="Platform" --http-method POST --api-version "7.1" --in-file parameters.json

parameters.json:

{
  "definition": {"id": 388},
  "sourceBranch": "refs/heads/fix/password-policies-missing-in-graph-api",
  "parameters": "{\"deployInfrastructure\": \"false\", \"deployHelmTemplates\": \"false\", \"deployServices\": \"true\", \"deployDatabase\": \"false\", \"deploySsoPolicies\": \"false\", \"deployNuggetFeed\": \"false\", \"cleanupContainerTags\": \"false\", \"deployPlatformPortal\": \"false\", \"deployAlloyKubernetes\": \"false\", \"services\": \"[{\\\"name\\\": \\\"SingleSignOn\\\", \\\"containers\\\": [{\\\"name\\\": \\\"singlesignon-api\\\", \\\"path\\\": \\\"SingleSignOn.WebApi/\\\", \\\"dockerBuild\\\": true}]}]\"}"
}

Step-by-Step Process

1. Identify Target Service

Determine which service contains your changes:

• Look at modified files in your branch
• Identify the service folder structure (services/{ServiceName}/)
• Note the container configuration in the pipeline YAML

2. Prepare Pipeline Parameters

Set the following parameters for single service deployment:

Enable only service deployment:

{
  "deployServices": "true"
}

Disable all other deployments:

{
  "deployInfrastructure": "false",
  "deployHelmTemplates": "false", 
  "deployDatabase": "false",
  "deploySsoPolicies": "false",
  "deployNuggetFeed": "false",
  "cleanupContainerTags": "false",
  "deployPlatformPortal": "false",
  "deployAlloyKubernetes": "false"
}

Configure target service:

{
  "services": "[{\"name\": \"YourServiceName\", \"containers\": [{\"name\": \"container-name\", \"path\": \"ServicePath/\", \"dockerBuild\": true}]}]"
}

3. Trigger the Pipeline

Using the Azure DevOps MCP server or REST API:

// Example using MCP Azure DevOps tool
mcp_azure-devops_build_run_build({
  "definitionId": 388,
  "project": "Platform", 
  "sourceBranch": "your-feature-branch-name",
  "parameters": {
    "deployInfrastructure": "false",
    "deployHelmTemplates": "false",
    "deployServices": "true", 
    "deployDatabase": "false",
    "deploySsoPolicies": "false",
    "deployNuggetFeed": "false",
    "cleanupContainerTags": "false", 
    "deployPlatformPortal": "false",
    "deployAlloyKubernetes": "false",
    "services": "[{\"name\": \"YourService\", \"containers\": [{\"name\": \"your-container\", \"path\": \"YourService.WebApi/\", \"dockerBuild\": true}]}]"
  }
})

4. Monitor Deployment

• Track build progress in Azure DevOps
• Verify container builds successfully
• Confirm deployment to test environment
• Validate your changes in the live environment

Pipeline Execution Flow

When triggered with the recommended parameters, the pipeline will:

1. AlphaBuild Stage:

   • Version the build using GitVersion
   • Build only the specified service container(s)
   • Push container images to the test registry
   • Skip all other build jobs (Bicep, Helm, databases, etc.)

2. AlphaSonarCloudAnalysis Stage:

   • Run in parallel with build
   • Perform code quality analysis
   • Generate test coverage reports

3. AlphaDeploy Stage:

   • Deploy only the specified service(s) to test environment
   • Use existing infrastructure and configurations
   • Skip database, SSO policies, and other components

4. TestAnnotations Stage:

   • Add deployment annotation to Application Insights

Environment Details

Target Environment: Test (Alpha)

• Resource Group: platform-test
• Container Registry: coaxletest.azurecr.io
• Subscription: LSG Dev/Test
• App Configuration: https://coaxle-test.azconfig.io

Common Service Configurations

SingleSignOn Service

{
  "name": "SingleSignOn",
  "containers": [
    {
      "name": "singlesignon-api", 
      "path": "SingleSignOn.WebApi/",
      "dockerBuild": true
    }
  ]
}

ProductManagement Service

{
  "name": "ProductManagement",
  "containers": [
    {
      "name": "productmanagement-api",
      "path": "ProductManagement.WebApi/", 
      "dockerBuild": true
    },
    {
      "name": "productmanagement-durable",
      "path": "ProductManagement.Durable.Isolated/",
      "dockerBuild": true
    }
  ]
}

Billing Service

{
  "name": "Billing",
  "containers": [
    {
      "name": "Billing",
      "path": "Billing/",
      "dockerBuild": true
    }
  ]
}

Best Practices

Before Deployment

• ✅ Ensure your branch builds locally without errors
• ✅ Run unit tests and verify they pass
• ✅ Fix any SonarCloud quality gate issues
• ✅ Identify the minimal set of services affected by your changes

During Deployment

• ✅ Monitor the build logs for any failures
• ✅ Verify container images are built and pushed successfully
• ✅ Check that deployment completes without errors

After Deployment

• ✅ Test your changes in the deployed environment
• ✅ Verify integration with existing services
• ✅ Validate that your fix/feature works as expected
• ✅ Check Application Insights for any runtime errors

Troubleshooting

Common Issues

1. Parameter Formatting: Ensure JSON strings are properly escaped in parameters
2. Service Not Found: Verify service name matches exactly with pipeline configuration
3. Container Path: Ensure container path is correct relative to services folder
4. Branch Name: Use full branch name without refs/heads/ prefix

Debugging Steps

1. Check build logs in Azure DevOps
2. Verify parameter values were passed correctly
3. Confirm source branch exists and is accessible
4. Review container build output for errors
5. Check deployment logs for infrastructure issues

Security Considerations

• Pipeline uses service connections for Azure authentication
• Container images are pushed to private registries
• Secrets are retrieved from Azure Key Vault
• Deployment targets isolated test environment

Related Documentation

---

Last Updated: August 13, 2025
File: docs/deployment/feature-branch-deployment.md
Pipeline Version: test.yaml (Build ID: 93484)
Validated With: SingleSignOn service deployment for password policies fix