Adds critical build flag

Author: brendankowitz

build/ci-pipeline.yml

@@ -1,12 +1,20 @@
-# DESCRIPTION: 	
-# Builds, tests, and packages the solution for the main branch.	
+# DESCRIPTION:
+# Builds, tests, and packages the solution for the main branch.
 
 name: $(SourceBranchName)-$(Date:yyyyMMdd)$(Rev:-r)
 trigger: none
 
+parameters:
+- name: buildCriticalOnly
+  displayName: 'Build Critical Versions Only (skip R4B/R5)'
+  type: boolean
+  default: false
+
 variables:
 - template: ci-variables.yml
 - template: build-variables.yml
+- name: buildCriticalOnly
+  value: ${{ parameters.buildCriticalOnly }}
 
 stages:
 # *********************** Setup ***********************
@@ -124,17 +132,18 @@ stages:
     steps:
     - template: ./jobs/analyze.yml
 
-- stage: DockerBuild  
+- stage: DockerBuild
   displayName: 'Build images'
   dependsOn:
   - UpdateVersion
   variables:
     assemblySemFileVer: $[stageDependencies.UpdateVersion.Semver.outputs['SetVariablesFromGitVersion.assemblySemFileVer']]
   jobs:
   - template: ./jobs/docker-build-all.yml
-    parameters: 
+    parameters:
       tag: $(ImageTag)
       buildPlatform: $(publicDockerImagePlatforms)
+      buildCriticalOnly: ${{ parameters.buildCriticalOnly }}
 
 # *********************** Stu3 ***********************
 - stage: redeployStu3
@@ -217,30 +226,33 @@ stages:
 # *********************** R4B ***********************
 - stage: redeployR4B
   displayName: 'Redeploy R4B CosmosDB Site'
+  condition: eq(variables.buildCriticalOnly, false)
   dependsOn:
   - DockerBuild
   jobs:
   - template: ./jobs/redeploy-webapp.yml
-    parameters: 
+    parameters:
       version: R4B
       webAppName: $(DeploymentEnvironmentNameR4B)
       subscription: $(ConnectedServiceName)
       imageTag: $(ImageTag)
 
 - stage: redeployR4BSql
   displayName: 'Redeploy R4B SQL Site'
+  condition: eq(variables.buildCriticalOnly, false)
   dependsOn:
   - DockerBuild
   jobs:
   - template: ./jobs/redeploy-webapp.yml
-    parameters: 
+    parameters:
       version: R4B
       webAppName: $(DeploymentEnvironmentNameR4BSql)
       subscription: $(ConnectedServiceName)
       imageTag: $(ImageTag)
 
 - stage: testR4B
   displayName: 'Run R4B Tests'
+  condition: eq(variables.buildCriticalOnly, false)
   dependsOn:
   - BuildArtifacts
   - redeployR4B
@@ -256,30 +268,33 @@ stages:
 # *********************** R5 ***********************
 - stage: redeployR5
   displayName: 'Redeploy R5 CosmosDB Site'
+  condition: eq(variables.buildCriticalOnly, false)
   dependsOn:
   - DockerBuild
   jobs:
   - template: ./jobs/redeploy-webapp.yml
-    parameters: 
+    parameters:
       version: R5
       webAppName: $(DeploymentEnvironmentNameR5)
       subscription: $(ConnectedServiceName)
       imageTag: $(ImageTag)
 
 - stage: redeployR5Sql
   displayName: 'Redeploy R5 SQL Site'
+  condition: eq(variables.buildCriticalOnly, false)
   dependsOn:
   - DockerBuild
   jobs:
   - template: ./jobs/redeploy-webapp.yml
-    parameters: 
+    parameters:
       version: R5
       webAppName: $(DeploymentEnvironmentNameR5Sql)
       subscription: $(ConnectedServiceName)
       imageTag: $(ImageTag)
 
 - stage: testR5
   displayName: 'Run R5 Tests'
+  condition: eq(variables.buildCriticalOnly, false)
   dependsOn:
   - BuildArtifacts
   - redeployR5
@@ -295,6 +310,15 @@ stages:
 # *********************** Finalize ***********************
 - stage: DockerAddTag
   displayName: 'Docker add main tag'
+  # Run if all tests succeed, or if critical-only mode and Stu3/R4 succeed (R4B/R5 skipped)
+  condition: |
+    and(
+      succeeded(),
+      or(
+        and(eq(variables.buildCriticalOnly, false), succeeded('testR4B'), succeeded('testR5')),
+        and(eq(variables.buildCriticalOnly, true), succeeded('testStu3'), succeeded('testR4'))
+      )
+    )
   dependsOn:
   - testStu3
   - testR4

build/jobs/docker-build-all.yml

@@ -1,33 +1,38 @@
-# DESCRIPTION: 
+# DESCRIPTION:
 # Builds and pushes images for all supported FHIR versions
 
 parameters:
 - name: tag
   type: string
 - name: buildPlatform
   type: string
+- name: buildCriticalOnly
+  type: boolean
+  default: false
 
 jobs:
 - template: docker-build-push.yml
-  parameters: 
+  parameters:
     version: "R4"
     tag: ${{parameters.tag}}
     buildPlatform: ${{parameters.buildPlatform}}
 
-- template: docker-build-push.yml
-  parameters: 
-    version: "R4B"
-    tag: ${{parameters.tag}}
-    buildPlatform: ${{parameters.buildPlatform}}
+- ${{ if eq(parameters.buildCriticalOnly, false) }}:
+  - template: docker-build-push.yml
+    parameters:
+      version: "R4B"
+      tag: ${{parameters.tag}}
+      buildPlatform: ${{parameters.buildPlatform}}
 
 - template: docker-build-push.yml
-  parameters: 
+  parameters:
     version: "Stu3"
     tag: ${{parameters.tag}}
     buildPlatform: ${{parameters.buildPlatform}}
 
-- template: docker-build-push.yml
-  parameters: 
-    version: "R5"
-    tag: ${{parameters.tag}}
-    buildPlatform: ${{parameters.buildPlatform}}
+- ${{ if eq(parameters.buildCriticalOnly, false) }}:
+  - template: docker-build-push.yml
+    parameters:
+      version: "R5"
+      tag: ${{parameters.tag}}
+      buildPlatform: ${{parameters.buildPlatform}}

build/pr-pipeline.yml

@@ -1,11 +1,19 @@
-# DESCRIPTION: 	
-# Builds, tests, and packages the solution for all PR requests.	
+# DESCRIPTION:
+# Builds, tests, and packages the solution for all PR requests.
 
 trigger: none
 
+parameters:
+- name: buildCriticalOnly
+  displayName: 'Build Critical Versions Only (skip R4B/R5)'
+  type: boolean
+  default: false
+
 variables:
 - template: pr-variables.yml
 - template: build-variables.yml
+- name: buildCriticalOnly
+  value: ${{ parameters.buildCriticalOnly }}
 
 stages:
 - stage: UpdateVersion
@@ -95,17 +103,18 @@ stages:
     steps:
     - template: ./jobs/analyze.yml
 
-- stage: DockerBuild  
+- stage: DockerBuild
   displayName: 'Build images'
   dependsOn:
   - UpdateVersion
   variables:
     assemblySemFileVer: $[stageDependencies.UpdateVersion.Semver.outputs['SetVariablesFromGitVersion.assemblySemFileVer']]
   jobs:
   - template: ./jobs/docker-build-all.yml
-    parameters: 
+    parameters:
       tag: $(ImageTag)
       buildPlatform: $(testDockerImagePlatforms)
+      buildCriticalOnly: ${{ parameters.buildCriticalOnly }}
 
 - stage: provisionEnvironment
   displayName: Provision Environment
@@ -271,13 +280,14 @@ stages:
 
 - stage: deployR4B
   displayName: 'Deploy R4B CosmosDB Site'
+  condition: eq(variables.buildCriticalOnly, false)
   dependsOn:
   - DockerBuild
   - setupEnvironment
   - createNsp
   jobs:
   - template: ./jobs/provision-deploy.yml
-    parameters: 
+    parameters:
       version: R4B
       webAppName: $(DeploymentEnvironmentNameR4B)
       appServicePlanName: '$(appServicePlanName)-cosmos'
@@ -290,13 +300,14 @@ stages:
 
 - stage: deployR4BSql
   displayName: 'Deploy R4B SQL Site'
+  condition: eq(variables.buildCriticalOnly, false)
   dependsOn:
   - DockerBuild
   - setupEnvironment
   - deploySqlServer
   jobs:
   - template: ./jobs/provision-deploy.yml
-    parameters: 
+    parameters:
       version: R4B
       sql: true
       webAppName: $(DeploymentEnvironmentNameR4BSql)
@@ -313,13 +324,14 @@ stages:
 
 - stage: deployR5
   displayName: 'Deploy R5 CosmosDB Site'
+  condition: eq(variables.buildCriticalOnly, false)
   dependsOn:
   - DockerBuild
   - setupEnvironment
   - createNsp
   jobs:
   - template: ./jobs/provision-deploy.yml
-    parameters: 
+    parameters:
       version: R5
       webAppName: $(DeploymentEnvironmentNameR5)
       appServicePlanName: '$(appServicePlanName)-cosmos'
@@ -332,13 +344,14 @@ stages:
 
 - stage: deployR5Sql
   displayName: 'Deploy R5 SQL Site'
+  condition: eq(variables.buildCriticalOnly, false)
   dependsOn:
   - DockerBuild
   - setupEnvironment
   - deploySqlServer
   jobs:
   - template: ./jobs/provision-deploy.yml
-    parameters: 
+    parameters:
       version: R5
       sql: true
       webAppName: $(DeploymentEnvironmentNameR5Sql)
@@ -385,6 +398,7 @@ stages:
 
 - stage: testR4B
   displayName: 'Run R4B Tests'
+  condition: eq(variables.buildCriticalOnly, false)
   dependsOn:
   - BuildArtifacts
   - setupEnvironment
@@ -400,6 +414,7 @@ stages:
 
 - stage: testR5
   displayName: 'Run R5 Tests'
+  condition: eq(variables.buildCriticalOnly, false)
   dependsOn:
   - BuildArtifacts
   - setupEnvironment
@@ -415,6 +430,15 @@ stages:
 
 - stage: cleanup
   displayName: 'Cleanup Azure Environment'
+  # Run if all tests succeed, or if critical-only mode and Stu3/R4 succeed (R4B/R5 skipped)
+  condition: |
+    and(
+      or(succeeded(), failed()),
+      or(
+        and(eq(variables.buildCriticalOnly, false), in(dependencies.testR4B.result, 'Succeeded', 'Failed'), in(dependencies.testR5.result, 'Succeeded', 'Failed')),
+        and(eq(variables.buildCriticalOnly, true), in(dependencies.testStu3.result, 'Succeeded', 'Failed'), in(dependencies.testR4.result, 'Succeeded', 'Failed'))
+      )
+    )
   dependsOn:
   - testStu3
   - testR4

docs/arch/adr-2510-critical-build-flag.md

@@ -0,0 +1,70 @@
+# ADR 2510: Critical-Only Build Flag for CI/PR Pipelines
+Labels: [CI/CD](https://github.com/microsoft/fhir-server/labels/Area-CI-CD)
+
+## Context
+The FHIR server supports four FHIR specification versions: STU3, R4, R4B, and R5. In production environments, the majority of deployments use STU3 and R4, which are mature and widely adopted specifications. R4B and R5 are newer versions with limited production usage.
+
+The current CI and PR pipelines build, deploy, and test all four versions for every commit. Each version requires:
+- Docker image builds (multi-platform for CI)
+- Deployment to test environments (CosmosDB + SQL variants)
+- Integration tests (CosmosDB + SQL)
+- End-to-end tests (CosmosDB + SQL)
+
+This comprehensive validation is essential for ensuring quality across all supported versions. However, when shipping critical hotfixes or iterating rapidly on production issues affecting only R4 or STU3, the time spent deploying and testing R4B and R5 represents significant overhead. A typical full CI build takes substantial time, with R4B and R5 stages accounting for approximately 40% of deployment and test time.
+
+We need a mechanism to accelerate builds when working exclusively on R4 and STU3 production issues, while maintaining the default behavior of comprehensive multi-version validation.
+
+## Decision
+We will add a `buildCriticalOnly` parameter to both the CI and PR pipeline definitions. When set to `true`, this parameter will:
+
+1. **Skip deployment and test stages** for R4B and R5 versions:
+   - Deployment stages (CosmosDB + SQL)
+   - Integration test jobs
+   - End-to-end test jobs
+
+2. **Skip Docker image builds** for R4B and R5 versions in the `docker-build-all.yml` job template
+
+3. **Continue to build all code** in the solution, including R4B and R5 projects, during the build stages. This ensures that changes to shared code (e.g., Core libraries) do not introduce compilation errors in non-critical versions.
+
+The parameter will default to `false`, ensuring that the standard behavior remains comprehensive validation across all versions. Developers and release engineers can opt into the fast path explicitly when appropriate.
+
+### Implementation Approach
+- Add `buildCriticalOnly` parameter (type: boolean, default: false) to pipeline definitions
+- Use Azure Pipelines conditional syntax (`condition: eq(variables.buildCriticalOnly, false)`) on R4B and R5 stages
+- Update stage dependencies to handle conditionally skipped stages
+- Use template conditionals (`${{ if }}`) to skip R4B/R5 Docker builds
+
+### Usage Guidelines
+**When to use `buildCriticalOnly: true`:**
+- Hotfixes for production R4 or STU3 issues
+- Rapid iteration during R4/STU3 feature development
+- Cost-sensitive CI runs when R4B/R5 validation is not required
+
+**When NOT to use it:**
+- Before merging to main branch (full validation recommended)
+- When changes affect shared Core libraries (cross-version validation needed)
+- Release builds
+- When explicitly developing or fixing R4B/R5 functionality
+
+## Status
+Accepted
+
+## Consequences
+### Benefits:
+- **Reduced build time**: 20-30% time savings by skipping ~40% of deployment and test stages
+- **Faster hotfix delivery**: Critical R4/STU3 fixes can be validated and shipped more quickly
+- **Lower build costs**: Reduced Azure DevOps agent minutes and Azure resource usage for test environments
+- **Preserved safety**: Default behavior remains unchanged; full validation is opt-out, not opt-in
+
+### Adverse Effects:
+- **Maintenance overhead**: New parameter must be propagated when adding future FHIR versions
+- **Risk of misuse**: Developers might use the flag inappropriately, skipping validation when it's needed
+- **Incomplete time savings**: All code still compiles, so savings are less than a full solution filter approach would provide
+
+### Neutral Effects:
+- **No impact on default behavior**: Existing builds and processes remain unchanged
+
+## References
+- CI Pipeline: `build/ci-pipeline.yml`
+- PR Pipeline: `build/pr-pipeline.yml`
+- Docker Build Template: `build/jobs/docker-build-all.yml`