feat: add {#[TOKEN_NAME]#} substitution step to publish pipelines (APIOps Toolkit parity) by Copilot · Pull Request #127 · Azure/apiops-cli

Copilot · 2026-06-09T19:00:58Z

Users migrating from APIOps Toolkit expect {#[TOKEN_NAME]#} placeholders in configuration.<env>.yaml to be substituted from pipeline secrets before publish runs. Previously the generated pipelines had no substitution step, so tokens were passed as literal strings to APIM.

Pipeline changes

Both GitHub Actions and Azure DevOps publish templates now include a dedicated substitution step before apiops publish, using the same tools APIOps Toolkit uses:

GitHub Actions — cschleiden/replace-tokens@v1.3:

- name: Substitute tokens in configuration.prod.yaml
  uses: cschleiden/replace-tokens@v1.3
  with:
    tokenPrefix: '{#['
    tokenSuffix: ']#}'
    files: '["configuration.prod.yaml"]'
  env:
    # MY_SECRET: ${{ secrets.MY_SECRET }}

Azure DevOps — replacetokens@6 (reads from variable groups automatically):

- task: replacetokens@6
  displayName: 'Substitute tokens in configuration.prod.yaml'
  inputs:
    sources: 'configuration.prod.yaml'
    tokenPrefix: '{#['
    tokenSuffix: ']#}'

The step is generated once per environment, scoped to configuration.<env>.yaml.

Documentation

docs/guides/token-substitution.md — new guide covering syntax, GitHub Actions setup (secret → env var mapping), Azure DevOps setup (variable group), Toolkit migration guide, and common examples
docs/ci-cd/github-actions.md / docs/ci-cd/azure-devops.md — updated pipeline step descriptions and added customization tips linking to the new guide

EMaher · 2026-06-09T19:21:00Z

+
+1. **Install the [Replace Tokens extension](https://marketplace.visualstudio.com/items?itemName=qetza.replacetokens)** in your Azure DevOps organization (if not already installed).
+
+2. **Add secret variables** to the `apim-<env>` variable group (e.g., `PROD_SECRET_VALUE`). Mark them as secret.


Add links to official documentation on how to add secrets to Azure DevOps.

Add example usage of a token value in a config overrides file.

EMaher · 2026-06-09T19:31:07Z

+         value: "{#[BACKEND_API_URL]#}"
+   ```
+
+2. **Store actual values** in your pipeline's secret store (GitHub Actions Secrets or Azure DevOps variable groups / Key Vault).


Why is Key Vault mentioned here?

EMaher · 2026-06-09T19:37:31Z

+
+## Azure DevOps Setup
+
+### Generated Step


Implementation details not needed.

EMaher · 2026-06-09T19:38:03Z

+
+The `replacetokens` task automatically reads from pipeline variables (including those from variable groups). Add your secret values as variables in the `apim-<env>` variable group:
+
+1. Go to **Pipelines → Library → apim-prod**


Shouldn't it be apim-<env>?

EMaher · 2026-06-09T19:44:54Z

+
+If you are migrating from APIOps Toolkit, your existing `configuration.<env>.yaml` files that use `{#[TOKEN_NAME]#}` placeholders work without modification. The same syntax is supported.
+
+The only difference is where secrets are stored and mapped:


Is the table necessary? table just shows everything is identity, which you've already stated.

EMaher · 2026-06-09T19:45:23Z

+| **Azure DevOps** | `qetza.replacetokens@6` | `replacetokens@6` (same extension) |
+| **Token prefix/suffix** | `{#[` / `]#}` | `{#[` / `]#}` (identical) |
+
+### Migration Steps


Remove this. We'll have an all-up migration doc elsewhere

EMaher · 2026-06-09T19:47:45Z

+
+## Security Notes
+
+- Tokens are replaced **in the pipeline runner's memory** — they are never committed to the repository.


Is this really true? We are using extensions, so how can we state their behavior? Are there links to extension documentation that state this?

EMaher

@copilot Please handle feedback.

Copilot · 2026-06-09T19:57:17Z

@copilot Please handle feedback.

All review feedback addressed in commit docs: address PR review feedback on token substitution docs:

docs/guides/token-substitution.md:

Removed Key Vault mention from "How It Works" intro
Removed the "Mapping Secrets to Tokens" implementation-detail section; kept the case-sensitivity note as a [!IMPORTANT] GitHub callout
Removed the "Generated Step" Azure DevOps section (implementation detail)
Converted the prerequisite note to [!IMPORTANT] GitHub callout
Fixed apim-prod → apim<env> (and in the step-by-step and example sections)
Removed the identity-mapping table from the Migration section
Removed the "Migration Steps" subsection
Revised Security Notes to remove unverifiable claims about extension internals

docs/ci-cd/azure-devops.md:

Removed the YAML task code block from "Using Token Substitution"
Added links to official Azure DevOps documentation for variable groups and secret variables, plus a concrete config file example
Renamed ## Related → ## Further Reading

Adds {#[TOKEN_NAME]#} substitution as a dedicated step in both GitHub Actions and Azure DevOps publish pipelines generated by `apiops init`, compatible with APIOps Toolkit configuration files. - GitHub Actions: cschleiden/replace-tokens@v1.3 with {#[ / ]#} - Azure DevOps: replacetokens@6 with {#[ / ]#} - Step runs before apiops publish so secrets are never committed - New docs/guides/token-substitution.md covering syntax, setup, migration from APIOps Toolkit, and common examples - Updated ci-cd/github-actions.md and ci-cd/azure-devops.md Closes #36

Copilot AI assigned Copilot and EMaher Jun 9, 2026

Copilot AI linked an issue Jun 9, 2026 that may be closed by this pull request

Enable pipeline token/placeholder substitution in publish pipeline (APIOps Toolkit parity) #117

Closed

6 tasks

Copilot started work on behalf of EMaher June 9, 2026 19:01 View session

Copilot AI changed the title ~~[WIP] Add pipeline token substitution in publish pipeline~~ feat: add {#[TOKEN_NAME]#} substitution step to publish pipelines (APIOps Toolkit parity) Jun 9, 2026

Copilot finished work on behalf of EMaher June 9, 2026 19:08

Copilot AI requested a review from EMaher June 9, 2026 19:08

EMaher requested changes Jun 9, 2026

View reviewed changes

Copilot started work on behalf of EMaher June 9, 2026 19:48 View session

Copilot finished work on behalf of EMaher June 9, 2026 19:49

Copilot AI requested a review from EMaher June 9, 2026 19:49

EMaher requested changes Jun 9, 2026

View reviewed changes

Copilot started work on behalf of EMaher June 9, 2026 19:51 View session

Copilot finished work on behalf of EMaher June 9, 2026 19:57

Copilot AI requested a review from EMaher June 9, 2026 19:57

Copilot AI and others added 6 commits June 10, 2026 02:43

Initial plan

c76bbcb

docs: address PR review feedback on token substitution docs

94bba5b

adding welcome message

ad8d121

fixing build warning in initialize pipeline

ae93a58

saving updates to workflow creation

89d547f

EMaher force-pushed the copilot/enable-pipeline-token-substitution branch from 966636d to 89d547f Compare June 10, 2026 02:44

EMaher added 2 commits June 10, 2026 05:40

fixes for azure devops pipelines

fb0ed59

adding automatic authorization of pipelines to environments

207bb40

EMaher approved these changes Jun 10, 2026

View reviewed changes

EMaher marked this pull request as ready for review June 10, 2026 05:51

adding instructions to install extension.

83a49e2

petehauge approved these changes Jun 10, 2026

View reviewed changes

petehauge merged commit bab1c32 into main Jun 10, 2026
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add {#[TOKEN_NAME]#} substitution step to publish pipelines (APIOps Toolkit parity)#127

feat: add {#[TOKEN_NAME]#} substitution step to publish pipelines (APIOps Toolkit parity)#127
petehauge merged 9 commits into
mainfrom
copilot/enable-pipeline-token-substitution

Copilot AI commented Jun 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

EMaher Jun 9, 2026

Uh oh!

Uh oh!

Uh oh!

EMaher Jun 9, 2026

Uh oh!

EMaher Jun 9, 2026

Uh oh!

EMaher Jun 9, 2026

Uh oh!

EMaher Jun 9, 2026

Uh oh!

EMaher Jun 9, 2026

Uh oh!

EMaher Jun 9, 2026

Uh oh!

EMaher left a comment

Uh oh!

Copilot AI commented Jun 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		1. Install the [Replace Tokens extension](https://marketplace.visualstudio.com/items?itemName=qetza.replacetokens) in your Azure DevOps organization (if not already installed).

		2. Add secret variables to the `apim-<env>` variable group (e.g., `PROD_SECRET_VALUE`). Mark them as secret.


		The `replacetokens` task automatically reads from pipeline variables (including those from variable groups). Add your secret values as variables in the `apim-<env>` variable group:

		1. Go to Pipelines → Library → apim-prod


		If you are migrating from APIOps Toolkit, your existing `configuration.<env>.yaml` files that use `{#[TOKEN_NAME]#}` placeholders work without modification. The same syntax is supported.

		The only difference is where secrets are stored and mapped:


		## Security Notes

		- Tokens are replaced in the pipeline runner's memory — they are never committed to the repository.

Conversation

Copilot AI commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pipeline changes

Documentation

Uh oh!

Uh oh!

EMaher Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

EMaher Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

EMaher Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

EMaher Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

EMaher Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

EMaher Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

EMaher Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

EMaher left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jun 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Jun 9, 2026 •

edited

Loading