configSubstitution: Substitute values in JSON and .NET XML configuration files

• targets
  One or more groups, each pairing a set of file patterns with the substitutions that apply only to those files.

  Grouping exists so that XML paths are never applied to JSON files and vice versa. In Version 1.0 a given file must be matched by exactly one group; overlapping groups are rejected during validation, before any file is read or any credential resolved.

  Array / List of Nested Object
  • files : Array / List of String
    Ant-style patterns, relative to the workspace. Absolute paths and patterns that traverse outside the workspace are rejected.

    Examples:

    • **/web.config - every web.config, including one at the workspace root
    • src/**/appsettings.json - only under src
    • src/*.json - directly in src, not in subdirectories

    Patterns in one group form a union and duplicate matches are collapsed, so a file matched by two patterns in the same group is still processed once.
  • substitutions
    The replacements to apply to the files matched by this group, and to no others.

    A path may not appear twice within one group. Substitutions are validated in full before any file is modified.

    Array / List of Nested Object
    • path : String
      The property to replace. The syntax depends on the group's format.

      JSON - dotted navigation, with quoting for keys that contain dots:

      • Logging.LogLevel.Default - three nested objects
      • Serilog.'MinimumLevel.Default' - a literal key containing dots
      • Services[0].Url - zero-based array index

      XML - the two .NET configuration collections only:

      • appSettings.ApiUrl - the value attribute of the matching entry
      • appSettings.BankApi:Key - colons and dots are literal here, never navigation
      • connectionStrings.Default - the connection string
      • connectionStrings.Default.@providerName - the provider name instead

      Matching is exact and case-sensitive. Only entries directly inside the top-level appSettings or connectionStrings element are considered; entries inside <location> and external files referenced by file= are not.

    • credentialsId : String (optional)
      A Secret Text credential supplying the replacement value. Use this rather than a literal for anything sensitive.

      The credential is resolved on the controller, in this job's context, so folder-scoped credentials work. Its value never appears in the build log, in exception messages, in the returned result or in persisted build metadata.

      It does appear in the file you are writing - that is the purpose of the step. Substitute as late as possible, after any archive, stash or packaging step, and be aware that the value crosses the agent channel in the clear: confidentiality depends on that channel being encrypted and the agent being trusted, exactly as it does for any other Jenkins credential used on an agent.

    • type : String (optional)
      How the replacement is written into the file.

      Automatic matches the type already present: a JSON string stays a string, a number stays a number, a boolean stays a boolean. This is almost always what you want, and it prevents a value silently changing a property's meaning.

      Choose an explicit type to change one deliberately, for example writing 8443 as a string. A value that currently holds null has no type to infer, so it requires an explicit choice.

      XML targets are always text, so only Automatic and String apply. Credentials are always written as strings; to point one at a non-string JSON value you must select String explicitly, as an acknowledgement that the property's type is changing.

    • value : String (optional)
      The replacement, as a literal.

      Do not hard-code a secret here. A literal written into the step configuration is persisted with the build and shown by Pipeline visualisation, so it is readable by anyone who can read the job.

      Referring to a credential through an environment variable is safe, and is a good option when one credential supplies more than one value:

      withCredentials([usernamePassword(credentialsId: 'my-secret',
                                        usernameVariable: 'MY_USER',
                                        passwordVariable: 'MY_PASS')]) {
          configSubstitution(targets: [[files: ['*.json'], format: 'json',
              substitutions: [
                  [path: 'user', value: env.MY_USER, type: 'string'],
                  [path: 'pass', value: env.MY_PASS, type: 'string']
              ]]])
      }

      Inside withCredentials the value is masked in the build log, and Pipeline replaces it with ${MY_PASS} before storing the step arguments, so it is not persisted. For a single Secret Text, the credential field below is simpler.

      Always written as text here; how it is emitted into the file is decided by the value type.

  • format : String (optional)
    Which path language applies to this group's substitutions.

    Setting this explicitly is recommended. Path syntax and the permitted value types both depend on the format, so with automatic detection those checks cannot run until the files have been found on the agent.

    Automatic detection uses the file extension (.json, .xml, .config) and falls back to inspecting the first non-whitespace character. A group that ends up containing both JSON and XML files is rejected.

• acknowledgeSecretLifecycle : boolean (optional)
  Suppress the repeated security notice printed when substitutions use credentials.

  This changes nothing about how secrets are handled. It silences one log line and nothing else: no error, warning, protection or result field is affected.

  Enable it only once you have confirmed that the files written by this step are not archived, stashed, fingerprinted, cached, uploaded or baked into an image layer afterwards. Workspace cleanup cannot retract a copy that has already been taken.

• dryRun : boolean (optional)
  Validate everything and report what would change, without writing anything.

  A dry run resolves file patterns, parses each file, resolves property paths, checks value types and confirms credentials are available. It does not create temporary files and does not modify content, permissions, timestamps or attributes. Useful as a deployment gate.

• missingPathBehavior : String (optional)
  What to do when a property path does not exist in a matched file.

  Missing paths never create new properties. This plugin only ever replaces values that are already there.

  Warn and continue does not mark the build unstable. If you need the build to react, use Fail the build or inspect substitutionsMissing in the returned result.

• noMatchBehavior : String (optional)
  What to do when a target group's patterns collectively match no files.

  Fail the build is the default and is usually what you want: a group matching nothing almost always means a mistyped pattern or a build that did not produce the files yet.

  This applies to the group as a whole. An individual pattern that matches nothing while other patterns in the same group do match is reported as a note in the log and in the result details, but is not itself an error.