YAML update step does not support escaping special characters

[yafanasiev]

Checklist

• [x] I've searched the issue queue to verify this is not a duplicate bug report.
• [x] I've included steps to reproduce the bug.
• [x] I've pasted the output of kargo version.
• [x] I've pasted logs, if applicable.

Description

When trying to update YAML key that has dots in it, it is not possible to escape them, thus, not possible to update the key itself. Initially, I followed the instructions the docs reference (https://github.com/tidwall/sjson?tab=readme-ov-file#path-syntax), but that does not seem to work.

Screenshots

Steps to Reproduce

1. Set up an arbitrary YAML file to update with Kargo that has dots in the key names:

metadata:
  annotations:
    example.com/version: "v.1.0.0."

2. Set up a promotion step that tries to update it:

        - uses: yaml-update
          as: update-image
          config:
            path: "./repo/example.yaml"
            updates:
              - key: 'metadata.annotations.example\.com/version'
                value: 'v2.0.0'

3. Observe error during promotion: error mutating bytes: error finding key metadata.annotations.example\.com/version: key path not found

Version

Client Version: v1.8.3
Server Version: v1.8.3

Logs

{
  "level": "ERROR",
  "ts": "2025-11-06T12:38:03Z",
  "caller": "promotions/promotions.go:362",
  "msg": "error executing Promotion",
  "namespace": "<redacted>",
  "promotion": "production.01k9cjs2ynyfvcrdx8qkvn935h.78c7e6e",
  "stage": "production",
  "freight": "78c7e6e9e5312be4d8effc89c1540ec419d8df39",
  "error": "step \"update-image\" met error threshold of 1: error running step \"update-image\": values file update failed: error updating image references in values file \"./repo/<redacted>\": error mutating bytes: error finding key metadata.annotations.example\\.com/version: key path not found",
  "stacktrace": "github.com/akuity/kargo/pkg/controller/promotions.(*reconciler).Reconcile.func3\n\tgithub.com/akuity/kargo/pkg/controller/promotions/promotions.go:362\ngithub.com/akuity/kargo/pkg/controller/promotions.(*reconciler).Reconcile\n\tgithub.com/akuity/kargo/pkg/controller/promotions/promotions.go:364\nsigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller[...]).Reconcile\n\tsigs.k8s.io/[email protected]/pkg/internal/controller/controller.go:216\nsigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller[...]).reconcileHandler\n\tsigs.k8s.io/[email protected]/pkg/internal/controller/controller.go:461\nsigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller[...]).processNextWorkItem\n\tsigs.k8s.io/[email protected]/pkg/internal/controller/controller.go:421\nsigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller[...]).Start.func1.1\n\tsigs.k8s.io/[email protected]/pkg/internal/controller/controller.go:296"
}

[krancour]

@fykaa when you're back please research whether there is syntax that accommodates this.