refactor: remove all token injection from manual identity guides

Manual guide markdown files are now fully static with generic
'for each environment' instructions. No more dynamic rendering —
the identity-guide-service just returns the template content as-is.
This makes the guides easier to maintain.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: EMaher

src/services/identity-guide-service.ts

@@ -2,73 +2,26 @@
 // Licensed under the MIT license.
 /**
  * Identity setup guide generator
- * Step-by-step instructions for service principal, RBAC, federated credentials,
- * pipeline secrets/service connections. Optional az CLI automation per FR-021.
+ * Returns the static manual guide content for the selected CI provider.
  */
 
 import {
   azureDevOpsIdentityGuideTemplate,
   githubActionsIdentityGuideTemplate,
 } from '../templates/generated/embedded-markdown.js';
-import { renderTemplate } from '../lib/render-template.js';
 
 export interface IdentityGuideService {
-  generateGitHubActionsGuide(
-    subscriptionId: string,
-    resourceGroup: string,
-    environments: string[]
-  ): string;
-
-  generateAzureDevOpsGuide(
-    environments: string[]
-  ): string;
+  generateGitHubActionsGuide(): string;
+  generateAzureDevOpsGuide(): string;
 }
 
 class IdentityGuideServiceImpl implements IdentityGuideService {
-  generateGitHubActionsGuide(
-    subscriptionId: string,
-    resourceGroup: string,
-    environments: string[]
-  ): string {
-    const federatedCredentialRows = environments.map((env) =>
-      `| \`${env}\` | \`github-env-${env}\` | \`repo:<your-github-org>/<your-github-repo>:environment:${env}\` |`
-    ).join('\n');
-
-    const environmentSecrets = environments.map((env) => `### ${env} environment
-- Create a GitHub environment named \`${env}\` in **Settings** → **Environments**
-- Add environment secret \`AZURE_SUBSCRIPTION_ID\` with the subscription ID used for ${env}
-- Add environment secret \`APIM_RESOURCE_GROUP_${env.toUpperCase()}\` with the APIM resource group for ${env}
-- Add environment secret \`APIM_SERVICE_NAME_${env.toUpperCase()}\` with the APIM service name for ${env}
-`).join('\n');
-
-    const environmentAzureAccessNotes = environments.map((env) =>
-      `- **${env}** — assign **Reader** on the resource group you will store in \`APIM_RESOURCE_GROUP_${env.toUpperCase()}\`, then assign **API Management Service Contributor** on the APIM instance you will store in \`APIM_SERVICE_NAME_${env.toUpperCase()}\`.`
-    ).join('\n');
-
-    return renderTemplate(githubActionsIdentityGuideTemplate, {
-      SUBSCRIPTION_ID: subscriptionId,
-      RESOURCE_GROUP: resourceGroup,
-      FEDERATED_CREDENTIAL_ROWS: federatedCredentialRows,
-      ENVIRONMENT_SECRET_SECTIONS: environmentSecrets,
-      ENVIRONMENT_AZURE_ACCESS_NOTES: environmentAzureAccessNotes,
-    });
+  generateGitHubActionsGuide(): string {
+    return githubActionsIdentityGuideTemplate;
   }
 
-  generateAzureDevOpsGuide(
-    environments: string[]
-  ): string {
-    const serviceConnectionRows = environments.map((environment) =>
-      `| \`${environment}\` | \`AZURE_SERVICE_CONNECTION_${environment.toUpperCase()}\` | Azure Resource Manager → Workload identity federation → subscription that contains the ${environment} APIM instance |`
-    ).join('\n');
-
-    const variableGroupRows = environments.map((environment) =>
-      `| \`${environment}\` | \`apim-${environment}\` | \`AZURE_SERVICE_CONNECTION\`, \`AZURE_SUBSCRIPTION_ID\`, \`APIM_RESOURCE_GROUP\`, \`APIM_SERVICE_NAME\`, \`APIM_RESOURCE_GROUP_${environment.toUpperCase()}\`, \`APIM_SERVICE_NAME_${environment.toUpperCase()}\` |`
-    ).join('\n');
-
-    return renderTemplate(azureDevOpsIdentityGuideTemplate, {
-      SERVICE_CONNECTION_ROWS: serviceConnectionRows,
-      VARIABLE_GROUP_ROWS: variableGroupRows,
-    });
+  generateAzureDevOpsGuide(): string {
+    return azureDevOpsIdentityGuideTemplate;
   }
 }
 

src/services/init-service.ts

@@ -35,10 +35,6 @@ import { generateIdentitySetupPrompt } from '../templates/copilot/identity-setup
 import { generateConfigureFilterPrompt } from '../templates/copilot/configure-filter-prompt.js';
 import { generateConfigureOverridesPrompt } from '../templates/copilot/configure-overrides-prompt.js';
 
-/** Placeholder values used in generated identity setup guides */
-const PLACEHOLDER_SUBSCRIPTION_ID = '<your-subscription-id>';
-const PLACEHOLDER_RESOURCE_GROUP = '<your-resource-group>';
-
 export interface GeneratedFiles {
   pipelines: string[];
   configs: string[];
@@ -453,19 +449,11 @@ class InitServiceImpl implements InitService {
    * Save identity setup guide to file and tell user where to find it
    */
   private async outputIdentityGuide(config: InitConfig, generatedFiles: GeneratedFiles): Promise<void> {
-    // Use placeholder values for the guide — users replace these with their actual Azure details
-    const subscriptionId = PLACEHOLDER_SUBSCRIPTION_ID;
-    const resourceGroup = PLACEHOLDER_RESOURCE_GROUP;
-
     let guide: string;
     if (config.ciProvider === 'github-actions') {
-      guide = identityGuideService.generateGitHubActionsGuide(
-        subscriptionId,
-        resourceGroup,
-        config.environments
-      );
+      guide = identityGuideService.generateGitHubActionsGuide();
     } else {
-      guide = identityGuideService.generateAzureDevOpsGuide(config.environments);
+      guide = identityGuideService.generateAzureDevOpsGuide();
     }
 
     // Save guide to file

src/templates/identity/identity-guide-azure-devops.md

@@ -55,31 +55,31 @@ Use **Access control (IAM)** on each resource group and APIM instance to create
 
 > 📖 [Create an Azure Resource Manager service connection using workload identity federation](https://learn.microsoft.com/azure/devops/pipelines/library/connect-to-azure)
 
+For each environment, do the following steps:
+
 1. In **Azure DevOps**, open **Project settings** → **Service connections** → **New service connection**.
 2. Choose **Azure Resource Manager**.
 3. Select **Workload identity federation**.
 4. Use the app registration from Step 2.
-5. Create one service connection per environment using the exact names below unless you also plan to edit the generated pipeline YAML and variable-group values:
-
-| Environment | Required service connection name | Scope guidance |
-|---|---|---|
-{{SERVICE_CONNECTION_ROWS}}
-
+5. Name the service connection `AZURE_SERVICE_CONNECTION_<ENV>` (replace `<ENV>` with the upper-case environment name) unless you plan to edit the generated pipeline YAML.
 6. Complete the validation flow in Azure DevOps so the service connection can issue the issuer and subject values required for federation.
 7. If Azure DevOps asks you to finish the federated credential in Azure, follow the linked experience or copy the issuer/subject into the app registration's **Federated credentials** blade in the Azure portal.
 
 ## Step 5: Create variable groups in Azure DevOps
 
 > 📖 [Add and use variable groups in Azure Pipelines](https://learn.microsoft.com/azure/devops/pipelines/library/variable-groups)
 
-1. Go to **Pipelines** → **Library** → **+ Variable group**.
-2. Create one variable group per environment:
-
-| Environment | Variable group name | Required variables |
-|---|---|---|
-{{VARIABLE_GROUP_ROWS}}
+For each environment, do the following steps:
 
-3. Include both the non-suffixed variables used by the extractor pipeline and the environment-suffixed APIM variables used by the publish pipeline.
+1. Go to **Pipelines** → **Library** → **+ Variable group**.
+2. Name the variable group `apim-<environment>` (e.g. `apim-dev`, `apim-prod`).
+3. Add the following variables:
+   - `AZURE_SERVICE_CONNECTION` — the service connection name from Step 4
+   - `AZURE_SUBSCRIPTION_ID` — the Azure subscription ID for that environment
+   - `APIM_RESOURCE_GROUP` — the resource group containing the APIM instance
+   - `APIM_SERVICE_NAME` — the APIM service name
+   - `APIM_RESOURCE_GROUP_<ENV>` — same value, upper-case environment suffix (used by the publish pipeline)
+   - `APIM_SERVICE_NAME_<ENV>` — same value, upper-case environment suffix (used by the publish pipeline)
 4. Authorize each variable group for pipeline use when Azure DevOps prompts you.
 
 ## Step 6: Create Azure DevOps environments and approvals

src/templates/identity/identity-guide-github-actions.md

@@ -6,8 +6,7 @@
 
 ## Before you start
 
-- Azure subscription: `{{SUBSCRIPTION_ID}}`
-- Resource group containing an APIM instance: `{{RESOURCE_GROUP}}`
+- An Azure subscription with an API Management instance
 - GitHub repository admin access
 - Permission in Microsoft Entra ID to create or manage app registrations
 
@@ -44,11 +43,12 @@ Helpful documentation:
 
 > 📖 [Assign Azure roles using the Azure portal](https://learn.microsoft.com/azure/role-based-access-control/role-assignments-portal)
 
-1. In the **Azure portal**, open your API Management service.
+For each environment, do the following steps:
+
+1. In the **Azure portal**, open the resource group that contains the APIM instance for that environment.
 2. Go to **Access control (IAM)** → **Add role assignment**.
-3. For every environment configured by `apiops init`, assign access to the app registration or service principal:
-{{ENVIRONMENT_AZURE_ACCESS_NOTES}}
-4. If you are starting with a single shared APIM resource in resource group `{{RESOURCE_GROUP}}` and subscription `{{SUBSCRIPTION_ID}}`, those placeholders are the first values to replace.
+3. Assign **Reader** on the resource group to the app registration.
+4. Open the APIM service itself and assign **API Management Service Contributor** to the app registration.
 5. Wait a few minutes for RBAC changes to propagate before you test the workflow.
 
 ## Step 4: Add federated credentials in Azure portal
@@ -64,18 +64,17 @@ Helpful documentation:
    - **Entity type**: **Branch**
    - **Branch name**: `main`
    - **Credential name**: `github-main-branch`
-4. Add one credential for each GitHub environment used by publish workflows:
-
-| GitHub environment | Suggested credential name | Subject value |
-|---|---|---|
-{{FEDERATED_CREDENTIAL_ROWS}}
+4. For each environment, add one additional federated credential:
+   - **Entity type**: **Environment**
+   - **Environment name**: the GitHub environment name (must match what you create in Step 5)
+   - **Credential name**: `github-env-<environment>`
 
 ## Step 5: Create GitHub environments in the web UI
 
 > 📖 [Using environments for deployment](https://docs.github.com/actions/deployment/targeting-different-environments/using-environments-for-deployment)
 
 1. In GitHub, go to **Settings** → **Environments**.
-2. Create an environment for each deployment target used by `apiops init`.
+2. For each environment, create a GitHub environment with the same name used during `apiops init`.
 3. Add protection rules such as required reviewers for production environments if your process needs approvals.
 
 ## Step 6: Add repository and environment secrets in GitHub
@@ -86,9 +85,10 @@ Helpful documentation:
 2. Under **Repository secrets**, create:
    - `AZURE_CLIENT_ID` — the Application (client) ID from the app registration
    - `AZURE_TENANT_ID` — the Directory (tenant) ID from the app registration
-3. Then configure the environment secrets below:
-
-{{ENVIRONMENT_SECRET_SECTIONS}}
+3. For each environment, add the following **environment secrets**:
+   - `AZURE_SUBSCRIPTION_ID` — the Azure subscription ID for that environment
+   - `APIM_RESOURCE_GROUP_<ENV>` — the resource group containing the APIM instance (replace `<ENV>` with the upper-case environment name)
+   - `APIM_SERVICE_NAME_<ENV>` — the APIM service name (replace `<ENV>` with the upper-case environment name)
 
 ## Step 7: Verify the workflow end to end
 

tests/unit/services/identity-guide-service.test.ts

@@ -9,143 +9,86 @@ import { identityGuideService } from '../../../src/services/identity-guide-servi
 
 describe('identity-guide-service', () => {
   describe('generateGitHubActionsGuide', () => {
-    it('should include subscription ID in guide', () => {
-      const guide = identityGuideService.generateGitHubActionsGuide(
-        'sub-12345',
-        'my-rg',
-        ['dev', 'prod']
-      );
-      expect(guide).toContain('sub-12345');
-    });
-
-    it('should include resource group in guide', () => {
-      const guide = identityGuideService.generateGitHubActionsGuide(
-        'sub-12345',
-        'my-rg',
-        ['dev']
-      );
-      expect(guide).toContain('my-rg');
+    it('should return static GitHub Actions guide content', () => {
+      const guide = identityGuideService.generateGitHubActionsGuide();
+      expect(guide).toContain('APIOps GitHub Actions identity setup guide');
     });
 
     it('should mention the Copilot prompt file and UI flow', () => {
-      const guide = identityGuideService.generateGitHubActionsGuide(
-        'sub-12345',
-        'my-rg',
-        ['dev']
-      );
+      const guide = identityGuideService.generateGitHubActionsGuide();
       expect(guide).toContain('.github/prompts/apiops-setup-workflow-identity.prompt.md');
       expect(guide).toContain('Azure portal');
       expect(guide).toContain('GitHub web UI');
     });
 
     it('should explain the GitHub identity distinction', () => {
-      const guide = identityGuideService.generateGitHubActionsGuide(
-        'sub-12345',
-        'my-rg',
-        ['dev']
-      );
+      const guide = identityGuideService.generateGitHubActionsGuide();
       expect(guide).toContain('GITHUB_TOKEN');
       expect(guide).toContain('only for Azure and APIM access');
     });
 
     it('should include portal-based Azure access steps', () => {
-      const guide = identityGuideService.generateGitHubActionsGuide(
-        'sub-12345',
-        'my-rg',
-        ['dev']
-      );
+      const guide = identityGuideService.generateGitHubActionsGuide();
       expect(guide).toContain('API Management Service Contributor');
       expect(guide).toContain('Access control (IAM)');
       expect(guide).toContain('Federated credentials');
     });
 
     it('should include documentation links', () => {
-      const guide = identityGuideService.generateGitHubActionsGuide(
-        'sub-12345',
-        'my-rg',
-        ['dev']
-      );
+      const guide = identityGuideService.generateGitHubActionsGuide();
       expect(guide).toContain('https://learn.microsoft.com/');
       expect(guide).toContain('https://docs.github.com/');
     });
 
-    it('should include environment-specific secrets for each environment', () => {
-      const guide = identityGuideService.generateGitHubActionsGuide(
-        'sub-12345',
-        'my-rg',
-        ['dev', 'staging', 'prod']
-      );
-      expect(guide).toContain('dev environment');
-      expect(guide).toContain('staging environment');
-      expect(guide).toContain('prod environment');
-      expect(guide).toContain('APIM_RESOURCE_GROUP_DEV');
-      expect(guide).toContain('APIM_RESOURCE_GROUP_STAGING');
-      expect(guide).toContain('APIM_RESOURCE_GROUP_PROD');
+    it('should describe environment secrets generically', () => {
+      const guide = identityGuideService.generateGitHubActionsGuide();
+      expect(guide).toContain('APIM_RESOURCE_GROUP_<ENV>');
+      expect(guide).toContain('APIM_SERVICE_NAME_<ENV>');
+      expect(guide).toContain('For each environment');
     });
 
     it('should include security notes', () => {
-      const guide = identityGuideService.generateGitHubActionsGuide(
-        'sub-12345',
-        'my-rg',
-        ['dev']
-      );
+      const guide = identityGuideService.generateGitHubActionsGuide();
       expect(guide).toContain('Security Notes');
       expect(guide).toContain('least-privilege');
     });
 
-    it('should create federated credential for each environment', () => {
-      const guide = identityGuideService.generateGitHubActionsGuide(
-        'sub-12345',
-        'my-rg',
-        ['dev', 'prod']
-      );
-      expect(guide).toContain('github-env-dev');
-      expect(guide).toContain('github-env-prod');
-      expect(guide).toContain('environment:dev');
-      expect(guide).toContain('environment:prod');
-    });
-
-    it('should render all template placeholders', () => {
-      const guide = identityGuideService.generateGitHubActionsGuide(
-        'sub-12345',
-        'my-rg',
-        ['dev']
-      );
-      expect(guide).not.toContain('{{');
-      expect(guide).not.toContain('}}');
+    it('should not contain any template placeholders', () => {
+      const guide = identityGuideService.generateGitHubActionsGuide();
+      expect(guide).not.toMatch(/\{\{[^}]+\}\}/);
     });
   });
 
   describe('generateAzureDevOpsGuide', () => {
+    it('should return static Azure DevOps guide content', () => {
+      const guide = identityGuideService.generateAzureDevOpsGuide();
+      expect(guide).toContain('Identity setup guide for APIOps extract and publish Azure DevOps Pipelines');
+    });
+
     it('should mention the Copilot prompt file and UI flow', () => {
-      const guide = identityGuideService.generateAzureDevOpsGuide(['dev', 'prod']);
+      const guide = identityGuideService.generateAzureDevOpsGuide();
       expect(guide).toContain('.github/prompts/apiops-setup-pipeline-identity.prompt.md');
-      expect(guide).toContain('Azure DevOps web portal');
+      expect(guide).toContain('Azure DevOps');
       expect(guide).toContain('Azure portal');
     });
 
     it('should explain the Azure DevOps identity distinction', () => {
-      const guide = identityGuideService.generateAzureDevOpsGuide(['dev', 'prod']);
+      const guide = identityGuideService.generateAzureDevOpsGuide();
       expect(guide).toContain('Build Service identity');
       expect(guide).toContain('separate from the Azure app registration');
       expect(guide).toContain('Create pull request');
     });
 
-    it('should include environment-specific service connections and variable groups', () => {
-      const guide = identityGuideService.generateAzureDevOpsGuide(['dev', 'prod']);
-      expect(guide).toContain('AZURE_SERVICE_CONNECTION_DEV');
-      expect(guide).toContain('AZURE_SERVICE_CONNECTION_PROD');
-      expect(guide).toContain('apim-dev');
-      expect(guide).toContain('apim-prod');
-      expect(guide).toContain('AZURE_SERVICE_CONNECTION');
-      expect(guide).toContain('APIM_RESOURCE_GROUP_DEV');
-      expect(guide).toContain('APIM_SERVICE_NAME_PROD');
+    it('should describe service connections and variable groups generically', () => {
+      const guide = identityGuideService.generateAzureDevOpsGuide();
+      expect(guide).toContain('AZURE_SERVICE_CONNECTION_<ENV>');
+      expect(guide).toContain('apim-<environment>');
+      expect(guide).toContain('For each environment');
     });
 
-    it('should render all template placeholders', () => {
-      const guide = identityGuideService.generateAzureDevOpsGuide(['dev']);
+    it('should not contain any template placeholders', () => {
+      const guide = identityGuideService.generateAzureDevOpsGuide();
       expect(guide).not.toMatch(/\{\{[^}]+\}\}/);
     });
-
   });
 });