Escaping variables is not documented

[sodul]

Describe your use-case which is not covered by existing documentation.

We have a Tools script that we install through CasC. Somehow after upgrading from configuration-as-code:1775.v810dc950b_514 to configuration-as-code:1810.v9b_c30a_249a_4c all of our ${var} entries got replaced with empty values, even though the embedded scripts look fine under ~/casc_configs.

After fixing the scripts and dumping them from the CasC config page we noticed that these ${var} entries are escaped with ^${var}.

We did find a bug from 2020 which mention this is well documented but we could not find any reference to this in the documentation.

Reference any relevant documentation, other materials or issues/pull requests that can be used for inspiration.

https://plugins.jenkins.io/configuration-as-code/

https://github.com/jenkinsci/configuration-as-code-plugin/issues/1429

[timja]

As mentioned in the linked comment its documented in the secrets documentation as its the secrets engine that replaces the placeholders: https://github.com/jenkinsci/configuration-as-code-plugin/blob/ebadef8587127ae274940c118763b738a7251152/docs/features/secrets.adoc#passing-secrets-through-variables

if you'd like to propose an enhancement that would we welcome

[sodul]

In our case we are not passing secrets in CasC, but a shell script to be used under the Tools configuration. The odd thing is that we did not change our CasC for the tools in several month but after upgrading to the latest LTS and plugins, the Tools Scripts got all the ${blah} entries swallowed. So something has changed in recent weeks, but it looks like the variables should have been escaped.

It is good to see that the docs for passing secrets does mention "^${some_var}" but it should probably be mentioned on the main page of the plugin since this is not something specific to secrets but to any variable that might be used in CasC.