Merge branch 'main' into copilot/fix-github-issue-96

Author: Peter Hauge

.github/workflows/integration-test.yml

@@ -1,3 +1,5 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
 # ===========================================================================
 # Integration Test — Extract→Publish Round-Trip
 # ===========================================================================
@@ -31,6 +33,7 @@ on:
         required: true
         type: choice
         options:
+          - Standard
           - StandardV2
           - Premium
           - PremiumV2
@@ -72,6 +75,8 @@ on:
         required: true
       APIM_PUBLISHER_EMAIL:
         required: true
+      APIM_SKU:
+        required: false
 
 permissions:
   id-token: write
@@ -84,6 +89,8 @@ concurrency:
 env:
   SOURCE_RG: rg-apiops-bvt-source-${{ github.run_id }}
   TARGET_RG: rg-apiops-bvt-target-${{ github.run_id }}
+  SOURCE_APIM: apiops-bvt-src-${{ github.run_id }}
+  TARGET_APIM: apiops-bvt-tgt-${{ github.run_id }}
 
 jobs:
   roundtrip-test:
@@ -103,14 +110,8 @@ jobs:
 
       - run: npm ci && npm run build
 
-      - name: Azure Login (OIDC)
-        uses: azure/login@v2
-        with:
-          client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-
-      - name: Run Round-Trip Test
+      - name: Resolve Workflow Settings
+        id: settings
         shell: pwsh
         run: |
           $logLevel = '${{ inputs.log_level }}'
@@ -119,61 +120,140 @@ jobs:
             throw "Invalid log_level '$logLevel'. Allowed values: Info, Verbose, Debug."
           }
 
+          $skuName = '${{ secrets.APIM_SKU }}'
+          if ([string]::IsNullOrWhiteSpace($skuName)) { $skuName = '${{ inputs.sku }}' }
+          if ([string]::IsNullOrWhiteSpace($skuName)) { $skuName = 'StandardV2' }
+
+          "logLevel=$logLevel" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
+          "skuName=$skuName" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
+
+      - name: Azure Login
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Run Round-Trip Phase 1 (Deploy)
+        id: phase1
+        shell: pwsh
+        run: |
           $params = @{
             SourceResourceGroup = '${{ env.SOURCE_RG }}'
             TargetResourceGroup = '${{ env.TARGET_RG }}'
-            SkuName            = '${{ inputs.sku }}'
+            SourceApimName     = '${{ env.SOURCE_APIM }}'
+            TargetApimName     = '${{ env.TARGET_APIM }}'
+            SourceSubscriptionId = '${{ secrets.AZURE_SUBSCRIPTION_ID }}'
+            TargetSubscriptionId = '${{ secrets.AZURE_SUBSCRIPTION_ID }}'
+            SkuName            = '${{ steps.settings.outputs.skuName }}'
             Location           = '${{ inputs.location }}'
-            LogLevel           = $logLevel
+            LogLevel           = '${{ steps.settings.outputs.logLevel }}'
             PublisherEmail     = '${{ secrets.APIM_PUBLISHER_EMAIL }}'
-            ExtractOutputDir   = './extracted-artifacts'
-            HardDelete         = $true
           }
+          ./tests/integration/all-resource-types/phases/run-phase1-deploy.ps1 @params
 
-          ./tests/integration/all-resource-types/run-roundtrip-test.ps1 @params
+      - name: Azure Login - Refresh Before Phase 2
+        if: success()
+        uses: azure/login@v2
+        with:
+          # Phase 1 can run for a long time while APIM activates; refresh login
+          # before extract/publish so apiops receives a fresh federated session.
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Run Round-Trip Phase 2 (Extract)
+        id: phase2
+        if: success()
+        shell: pwsh
+        env:
+          AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+          AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+        run: |
+          ./tests/integration/all-resource-types/phases/run-phase2-extract.ps1 `
+            -SourceSubscriptionId '${{ steps.phase1.outputs.sourceSubscriptionId }}' `
+            -SourceResourceGroup '${{ steps.phase1.outputs.sourceResourceGroup }}' `
+            -SourceApimName '${{ steps.phase1.outputs.sourceApimName }}' `
+            -LogLevel '${{ steps.settings.outputs.logLevel }}' `
+            -ExtractOutputDir './extracted-artifacts'
+
+      - name: Run Round-Trip Phase 3 (Validate Extract)
+        if: success()
+        shell: pwsh
+        run: |
+          $skuName = '${{ steps.phase1.outputs.skuName }}'
+          $extractOutputDir = '${{ steps.phase2.outputs.ExtractOutputDir }}'
+
+          ./tests/integration/all-resource-types/phases/run-phase3-validate-extract.ps1 `
+            -SkuName $skuName `
+            -LogLevel '${{ steps.settings.outputs.logLevel }}' `
+            -ExtractOutputDir $extractOutputDir
+
+      - name: Run Round-Trip Phase 4 (Create Overrides)
+        id: phase4
+        if: success()
+        shell: pwsh
+        run: |
+          $extractOutputDir = '${{ steps.phase2.outputs.ExtractOutputDir }}'
+
+          ./tests/integration/all-resource-types/phases/run-phase4-create-overrides.ps1 `
+            -TargetSubscriptionId '${{ steps.phase1.outputs.targetSubscriptionId }}' `
+            -TargetResourceGroup '${{ steps.phase1.outputs.targetResourceGroup }}' `
+            -LogLevel '${{ steps.settings.outputs.logLevel }}' `
+            -ExtractOutputDir $extractOutputDir
+
+      - name: Run Round-Trip Phase 5 (Publish)
+        if: success()
+        shell: pwsh
+        env:
+          AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+          AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+        run: |
+          $extractOutputDir = '${{ steps.phase2.outputs.ExtractOutputDir }}'
+
+          ./tests/integration/all-resource-types/phases/run-phase5-publish.ps1 `
+            -TargetSubscriptionId '${{ steps.phase1.outputs.targetSubscriptionId }}' `
+            -TargetResourceGroup '${{ steps.phase1.outputs.targetResourceGroup }}' `
+            -TargetApimName '${{ steps.phase1.outputs.targetApimName }}' `
+            -OverrideFile '${{ steps.phase4.outputs.overrideFile }}' `
+            -LogLevel '${{ steps.settings.outputs.logLevel }}' `
+            -ExtractOutputDir $extractOutputDir
+
+      - name: Run Round-Trip Phase 6 (Compare)
+        if: success()
+        shell: pwsh
+        run: |
+          ./tests/integration/all-resource-types/phases/run-phase6-compare.ps1 `
+            -SourceSubscriptionId '${{ steps.phase1.outputs.sourceSubscriptionId }}' `
+            -SourceResourceGroup '${{ steps.phase1.outputs.sourceResourceGroup }}' `
+            -SourceApimName '${{ steps.phase1.outputs.sourceApimName }}' `
+            -TargetSubscriptionId '${{ steps.phase1.outputs.targetSubscriptionId }}' `
+            -TargetResourceGroup '${{ steps.phase1.outputs.targetResourceGroup }}' `
+            -TargetApimName '${{ steps.phase1.outputs.targetApimName }}' `
+            -LogLevel '${{ steps.settings.outputs.logLevel }}'
 
       - name: Upload Extracted Artifacts
         if: always()
         uses: actions/upload-artifact@v4
         with:
-          name: extracted-artifacts-${{ inputs.sku }}
-          path: ./extracted-artifacts/
+          name: extracted-artifacts-${{ steps.phase1.outputs.skuName }}
+          path: ${{ steps.phase2.outputs.ExtractOutputDir || './extracted-artifacts/' }}
           if-no-files-found: ignore
 
-      - name: Emergency Teardown
-        if: failure()
+      - name: Run Round-Trip Phase 7 (Teardown)
+        if: always()
         shell: pwsh
         run: |
-          $sourceRg = '${{ env.SOURCE_RG }}'
-          $targetRg = '${{ env.TARGET_RG }}'
-          $location = '${{ inputs.location }}'
-
-          # Capture APIM names before RG deletion so we can purge soft-deleted services.
-          $sourceApimName = az apim list --resource-group $sourceRg --query "[0].name" -o tsv 2>$null
-          $targetApimName = az apim list --resource-group $targetRg --query "[0].name" -o tsv 2>$null
-
-          Write-Host "🚨 Emergency teardown — deleting resource groups..."
-          az group delete --name $sourceRg --yes --no-wait 2>$null
-          az group delete --name $targetRg --yes --no-wait 2>$null
-
-          Write-Host "⏳ Waiting for resource group deletions before APIM purge..."
-          $maxWaitSeconds = 900
-          $waited = 0
-          $interval = 30
-
-          while ($waited -lt $maxWaitSeconds) {
-            $srcExists = (az group exists --name $sourceRg -o tsv 2>$null) -eq 'true'
-            $tgtExists = (az group exists --name $targetRg -o tsv 2>$null) -eq 'true'
-            if (-not $srcExists -and -not $tgtExists) {
-              break
-            }
-            Start-Sleep -Seconds $interval
-            $waited += $interval
-          }
+          $sourceResourceGroup = '${{ steps.phase1.outputs.sourceResourceGroup }}'
+          if ([string]::IsNullOrWhiteSpace($sourceResourceGroup)) { $sourceResourceGroup = '${{ env.SOURCE_RG }}' }
 
-          foreach ($apimName in @($sourceApimName, $targetApimName)) {
-            if (-not [string]::IsNullOrWhiteSpace($apimName)) {
-              Write-Host "🗑️  Purging soft-deleted APIM: $apimName"
-              az apim deletedservice purge --service-name $apimName --location $location 2>$null
-            }
-          }
+          $targetResourceGroup = '${{ steps.phase1.outputs.targetResourceGroup }}'
+          if ([string]::IsNullOrWhiteSpace($targetResourceGroup)) { $targetResourceGroup = '${{ env.TARGET_RG }}' }
+
+          $location = '${{ steps.phase1.outputs.location }}'
+          if ([string]::IsNullOrWhiteSpace($location)) { $location = '${{ inputs.location }}' }
+
+          ./tests/integration/all-resource-types/phases/run-phase7-teardown.ps1 `
+            -SourceResourceGroup $sourceResourceGroup `
+            -TargetResourceGroup $targetResourceGroup `
+            -Location $location

.gitignore

@@ -39,11 +39,11 @@ Desktop.ini
 .local-extract*/
 
 # Files for integration tests
-tests/integration/all-resource-types/logs/**
-tests/integration/all-resource-types/extracted-artifacts*/**
-tests/integration/all-resource-types/target-apim.json
-tests/integration/all-resource-types/source-apim.json
-tests/integration/all-resource-types/source-apim-post-activation.bicep
+tests/integration/all-resource-types/**/logs/**
+tests/integration/all-resource-types/**/extracted-artifacts*/**
+tests/integration/all-resource-types/bicep/target-apim.json
+tests/integration/all-resource-types/bicep/source-apim.json
+tests/integration/all-resource-types/bicep/source-apim-post-activation.bicep
 
 # Environment variables
 .env
@@ -57,4 +57,3 @@ tests/integration/all-resource-types/source-apim-post-activation.bicep
 # Squad: SubSquad activation file (local to this machine)
 .squad-workstream
 *.d.ts.map
-tests/integration/all-resource-types/source-apim-post-activation.json

docs/reference/artifact-format.md

@@ -241,6 +241,7 @@ Example policy XML:
 - **Info file names** follow the pattern `{resourceType}Information.json`
 - **Policy files** are always named `policy.xml`
 - **API specifications** are named `specification.{ext}` (e.g., `specification.yaml`, `specification.json`, `specification.wsdl`)
+  - Specification files are not exported for API types that don't use OpenAPI/WSDL artifacts (for example: WebSocket, MCP, A2A).
 - **Wiki files** are named `wiki.md`
 
 ---

src/clients/apim-client.ts

@@ -586,7 +586,7 @@ export class ApimClient implements IApimClient {
    *   graphql-link          – GraphQL SDL blob        (type=graphql)
    *   wsdl-link             – WSDL blob               (type=soap)
    *   openapi-link          – OpenAPI 3.0 YAML        (type=http, default)
-   *   undefined             –                         (type=websocket — no spec; callers should skip)
+   *   undefined             –                         (type=websocket|a2a — no spec; callers should skip)
    *
    * SOAP APIs use wsdl-link so the exported specification can be re-imported
    * faithfully on publish (matches the Azure/apiops reference tool). APIM's
@@ -612,6 +612,7 @@ export class ApimClient implements IApimClient {
       case 'graphql':   return 'graphql-link';
       case 'soap':      return 'wsdl-link';
       case 'websocket': return undefined;
+      case 'a2a':       return undefined;
       default:          return 'openapi-link';
     }
   }
@@ -743,4 +744,3 @@ export class ApimClient implements IApimClient {
   }
 
 }
-

src/services/api-extractor.ts

@@ -358,6 +358,11 @@ async function extractApiSpecification(
     return false;
   }
 
+  if (apiType?.toLowerCase() === 'a2a') {
+    logger.debug(`Skipping spec export for A2A API "${getNamePart(apiDescriptor.nameParts, 0)}" — A2A APIs use JSON-RPC + agent card endpoints, not OpenAPI`);
+    return false;
+  }
+
   if (apiType?.toLowerCase() === 'graphql' && hasGraphQLSchema(extractedSchemas)) {
     logger.debug(
       `Skipping spec export for synthetic GraphQL API "${getNamePart(apiDescriptor.nameParts, 0)}" — schema is captured via ApiSchema`

src/services/api-publisher.ts

@@ -97,6 +97,11 @@ export async function publishApi(
  * Maps spec file format to APIM ContentFormat for inline import.
  */
 function getImportFormat(specFormat: string, _apiType?: string): string | undefined {
+  const apiType = _apiType?.toLowerCase();
+  if (apiType === 'a2a') {
+    return undefined;
+  }
+
   switch (specFormat) {
     case 'yaml':
       return 'openapi';
@@ -178,7 +183,7 @@ async function publishRootApi(
 
       // The `type` property from GET is read-only and ignored on PUT.
       // APIM uses `apiType` to determine the API kind during spec import.
-      // Always set it explicitly (valid values: http, soap, websocket, graphql, odata, grpc, mcp).
+      // Always set it explicitly (valid values include http, soap, websocket, graphql, odata, grpc, mcp, a2a).
       if (apiType) {
         cleanProps.apiType = apiType;
       }

src/templates/configs/filter-config.ts

@@ -47,7 +47,44 @@ export function generateFilterConfig(): string {
 #   - rate-limit-fragment
 #   - cors-fragment
 
-# Uncomment to extract ALL resources (default behavior if no filters specified)
-# Leave all sections commented to extract everything
+# Extract only specific gateways
+# gatewayNames:
+#   - default
+#   - internal-gateway
+
+# Extract only specific version sets
+# versionSetNames:
+#   - payments-v1
+
+# Extract only specific groups
+# groupNames:
+#   - administrators
+
+# Extract only specific subscriptions
+# subscriptionNames:
+#   - starter-subscription
+
+# Extract only specific schemas
+# schemaNames:
+#   - pet-schema
+
+# Extract only specific policy restrictions
+# policyRestrictionNames:
+#   - global-policy-restriction
+
+# Extract only specific documentations
+# documentationNames:
+#   - getting-started
+
+# Extract only specific workspaces
+# workspaceNames:
+#   - dev-workspace
+
+# Filter behavior:
+# - Leave a section commented out to include ALL resources of that type
+# - Set a section to an empty array ([]) to exclude ALL resources of that type
+#   Example:
+#   gatewayNames: []
+#   subscriptionNames: []
 `;
 }

tests/contract/.gitkeep

@@ -1,3 +1,5 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
 <#
 .SYNOPSIS
     Compares two Azure API Management instances via ARM REST API.