Background/Situation
Starting with TeamCity 2026.2.2, the legacy HashiCorp Vault syntax %vault:PATH!/KEY% and %vault:<connection ID>:/PATH!/KEY% is deprecated (TW-105338). The documentation suggests replacing these references with remote HashiCorp Vault parameters and describes the conversion in the Kotlin DSL: "Update Legacy Parameters". If Kotlin DSL is not used in your projects, you can use REST API as a workaround.
The steps below were tested on TeamCity 2026.1 (build 222521) and 2026.2.2 (build 239308).
Question
How to convert legacy %vault:...% references to remote HashiCorp Vault parameters with the REST API, including references in build steps, templates, and recipes?
Answer
Where a legacy reference resolves
A legacy reference resolves only when a build parameter holds it: a parameter of the project, the template, or the build configuration, including password parameters. A reference that only a build step or a recipe holds reaches the step as the literal %vault:...% string, unless a parameter of the same build holds the same reference. Because of that, you should convert step references in the same change as the parameters that hold the same reference.
Convert a parameter
Each legacy value maps to the connection ID and the query of a remote parameter:
| Legacy value |
teamcity_hashicorp_vault_namespace (connection ID) |
teamcity_hashicorp_vault_vaultQuery (query) |
|---|---|---|
%vault:path!/key% |
empty | path!/key |
%vault:<connection ID>:/path!/key% |
<connection ID> |
path!/key, without the leading slash |
Replace the parameter with a remote parameter that has an empty value, with the call for the build configuration or template, or the call for the project:
PUT /app/rest/buildTypes/id:<build configuration or template ID>/parameters/<parameter name>
PUT /app/rest/projects/id:<project ID>/parameters/<parameter name>
Content-Type: application/json
{"name": "<parameter name>", "value": "", "type": {"rawValue": "remote remoteType='hashicorp-vault' teamcity_hashicorp_vault_namespace='<connection ID>' teamcity_hashicorp_vault_vaultQuery='<path>!/<key>'"}}
For a value with text around the reference, such as Bearer %vault:...%, create a remote parameter for the secret and replace the reference with %<remote parameter name>%. One value can reference several remote parameters, also from different connections.
Convert a build step parameter
- Create a remote parameter in the build configuration or template that owns the step.
-
Set the step parameter to
%<remote parameter name>%. The body is the new value as plain text, and the response is the stored value:PUT /app/rest/buildTypes/id:<build configuration or template ID>/steps/<step ID>/parameters/<parameter name> Content-Type: text/plain %<remote parameter name>%
GET /app/rest/buildTypes/id:<ID>/steps?fields=step(id,name,type,inherited) lists the step IDs. A step with inherited: true comes from a template and should be changed in the template. A PUT on the build configuration for an inherited step answers 200 with the old value and changes nothing (TW-87103).
Convert a recipe parameter
A recipe parameter cannot be a remote parameter: with a remote spec in the recipe definition, the step gets an empty value, and the build log shows no warning. Set the default value of the recipe parameter, or its value in the recipe step, to %<remote parameter name>%. Define the remote parameter in the project, the template, or the build configuration.
The REST API has no endpoint for recipes. Edit a private recipe on the Recipes page of the project settings: Edit a Private Recipe. It's also possible to edit the recipes directly on disk in <TeamCity Data Directory>/config/projects/<project ID>/pluginData/metaRunners. Keep in mind that TeamCity needs to reload the project from disk for the changes to take effect, and you might need to touch the project-config.xml file of the corresponding project to update its modification time and trigger the reload.
Vault queries that depend on another parameter
A Vault query cannot contain a parameter reference such as %env.STAGE%. TeamCity sends the query as written, and the build fails with Failed to fetch data for path '<query path>'. A build configuration also cannot override the query of a remote parameter that it inherits. Create one remote parameter, with its own name, for each Vault path.
Find the remaining legacy references
A build in which a build parameter holds a legacy reference gets the property teamcity.vault.legacy.references.used=true. For a connection with an ID, the property is teamcity.vault.<connection ID>.legacy.references.used=true. The property also covers password parameters, whose values the REST API does not return. References that only steps or recipes hold do not set it.
GET /app/rest/builds?locator=defaultFilter:false,affectedProject:(id:<project ID>),property:(name:teamcity.vault.legacy.references.used,value:true),count:1000&fields=count,build(id,buildTypeId,finishDate)
Without affectedProject, the call searches all builds of the server. In the build log, a legacy reference shows as [HashiCorp Vault] 1 reference to resolve: [vault:...], and a remote parameter as 1 remote parameter to resolve: [...].
Parameter level and dynamic secrets
It's best to keep each remote parameter at the level of the legacy parameter it replaces. In my tests, every build fetched each remote parameter it inherited, even if those parameters weren't actually used in the build's steps. That means a failed fetch would break such a build even though it didn't even need the parameter.
Convert both values of a dynamic secret, such as an AWS access key ID and its secret access key, in one change. Legacy and remote parameters that read the same dynamic secrets engine get separate credentials (Update Legacy Parameters).
Comments
0 comments
Please sign in to leave a comment.