fix: strip source-service tagId from ApiTagDescription PUT payloads

src/services/resource-publisher.ts

@@ -451,6 +451,13 @@ export async function publishResource(
       json = normalizeDiagnosticLoggerId(json, context, descriptor.workspace, config.envMapping);
     }
 
+    // Tag descriptions carry a read-only properties.tagId pointing at the
+    // SOURCE service; the tag is identified by the URL path, so drop it or
+    // APIM rejects the PUT with "Cross-service resource references are not allowed".
+    if (descriptor.type === ResourceType.ApiTagDescription) {
+      json = stripTagDescriptionTagId(json);
+    }
+
     if (descriptor.type === ResourceType.Api) {
       json = normalizeApiVersionSetId(
         json,
@@ -1323,6 +1330,23 @@ export function normalizeDiagnosticLoggerId(
   };
 }
 
+/**
+ * Drop the read-only `properties.tagId` from an ApiTagDescription payload.
+ * Extracted artifacts carry the SOURCE service's full tag ARM path; newer APIM
+ * api-versions validate it on PUT and reject cross-service references. The tag
+ * is already identified by the tagDescriptionId in the request URL.
+ */
+export function stripTagDescriptionTagId(
+  json: Record<string, unknown>
+): Record<string, unknown> {
+  const props = json.properties as Record<string, unknown> | undefined;
+  if (!props || !Object.hasOwn(props, 'tagId')) {
+    return json;
+  }
+  const { tagId: _omit, ...rest } = props;
+  return { ...json, properties: rest };
+}
+
 export function normalizeApiVersionSetId(
   json: Record<string, unknown>,
   context: ApimServiceContext,

tests/unit/services/resource-publisher.test.ts

@@ -10,6 +10,7 @@ import {
   resolveAssociationDeleteDescriptor,
   normalizeApiAuthenticationSettings,
   normalizeDiagnosticLoggerId,
+  stripTagDescriptionTagId,
   prefersLegacyAuthOverride,
 } from '../../../src/services/resource-publisher.js';
 import { ResourceType } from '../../../src/models/resource-types.js';
@@ -2069,6 +2070,66 @@ describe('resource-publisher', () => {
     });
   });
 
+  describe('stripTagDescriptionTagId', () => {
+    it('drops the source-service tagId from the payload', () => {
+      const json = {
+        name: 'billing-tag',
+        properties: {
+          tagId:
+            '/subscriptions/src-sub/resourceGroups/src-rg/providers/Microsoft.ApiManagement/service/src-svc/tags/billing-tag',
+          displayName: 'Billing Tag',
+          description: 'Operations related to billing.',
+        },
+      };
+
+      const result = stripTagDescriptionTagId(json);
+
+      const props = result.properties as Record<string, unknown>;
+      expect(props).not.toHaveProperty('tagId');
+      expect(props.displayName).toBe('Billing Tag');
+      expect(props.description).toBe('Operations related to billing.');
+    });
+
+    it('returns json unchanged when tagId is absent', () => {
+      const json = { name: 'tag-desc', properties: { description: 'd' } };
+      expect(stripTagDescriptionTagId(json)).toBe(json);
+    });
+
+    it('returns json unchanged when properties is missing', () => {
+      const json = { name: 'tag-desc' };
+      expect(stripTagDescriptionTagId(json)).toBe(json);
+    });
+
+    it('publishResource strips tagId from the ApiTagDescription PUT payload', async () => {
+      const client = createMockClient();
+      const store = createMockStore();
+      store.readResource.mockResolvedValue({
+        name: 'billing-tag',
+        properties: {
+          tagId:
+            '/subscriptions/src-sub/resourceGroups/src-rg/providers/Microsoft.ApiManagement/service/src-svc/tags/billing-tag',
+          displayName: 'Billing Tag',
+          description: 'Operations related to billing.',
+        },
+      });
+
+      const descriptor: ResourceDescriptor = {
+        type: ResourceType.ApiTagDescription,
+        nameParts: ['orders-api', 'billing-tag'],
+      };
+
+      const result = await publishResource(client, store, testContext, descriptor, testConfig);
+
+      expect(result.status).toBe('success');
+      expect(client.putResource).toHaveBeenCalledTimes(1);
+      const putPayload = client.putResource.mock.calls[0][2] as Record<string, unknown>;
+      const props = putPayload.properties as Record<string, unknown>;
+      expect(props).not.toHaveProperty('tagId');
+      expect(props.displayName).toBe('Billing Tag');
+      expect(props.description).toBe('Operations related to billing.');
+    });
+  });
+
   describe('normalizeApiAuthenticationSettings', () => {
     it('keeps collections and drops singular fields when collections are non-empty', () => {
       const json = {