Yaml

“appendtoarray” appends the value as a new entry of the yaml sequence selected by “key”.

compatible:

• target

default: false

remark:

• appending is skipped when the sequence already holds the value, so running it twice changes nothing.
• combined with “createmissingkey”, a missing sequence is created with the value as its only entry.
• “key” must select the sequence itself, not one of its entries.
• not supported by the “yamlpath” engine.

example:

• key: $.allowedTags appendtoarray: true

“comment” defines a comment added after the value.

compatible:

• target

default: empty

remark:

• the comment is only added when Updatecli changes the value.

“createmissingkey” creates the key when the yaml document does not hold it yet.

compatible:

• target

default: false

remark:

• missing intermediate keys are created as nested maps.
• the key is only ever created, never removed, and existing keys are left untouched.
• a missing sequence index such as $.agents[0].name cannot be created.
• a key selecting several nodes, such as $.agents[*].tag or $..tag, is rejected because the key cannot be created under each selected node.
• not supported by the “yamlpath” engine.
• the yaml file itself must already exist.

example:

• key: $.image.tag createmissingkey: true

“documentindex” defines the index of the document to use in a multi document yaml file.

compatible:

• source
• condition
• target

default: empty

remark:

• when unset in a source, the value is retrieved from the first document matching the query.
• when unset in a condition or a target, every document is evaluated by the query.

example:

• documentindex: 0
• documentindex: 1

“engine” defines the library used to manipulate the yaml file.

No single Go library handles yaml well in every case, and each has its own strengths, so Updatecli lets you pick the one that suits your file.

default: go-yaml

remark:

• accepted values are “yamlpath”, “go-yaml”, “default” or empty.
• “go-yaml”, “default” and empty are equivalent.

“file” defines the path of the yaml file to use.

compatible:

• source
• condition
• target

remark:

• “file” and “files” are mutually exclusive.
• the schemes “https://”, “http://” and “file://” are supported in a source or a condition.

“files” defines the list of yaml file paths to use.

compatible:

• condition
• target

remark:

• “file” and “files” are mutually exclusive.
• the schemes “https://”, “http://” and “file://” are supported in a condition.

“key” defines the yaml key path.

compatible:

• source
• condition
• target

remark:

• “key” is a simpler version of yamlpath.
• in a target, a key that a document does not hold is an error, so that a manifest never reports success for an update it did not make. The same rule applies to a wildcard such as $.agents[*].name: every position it selects must hold the key, otherwise the target fails instead of updating only some of them. Set “searchpattern” to update the positions holding the key and ignore the others.
• a recursive selector such as $..name cannot report a partial match: it searches for the key itself, so it only selects the positions already holding it and never fails on the others.
• a field path filtering on a key and value is not supported yet, see https://github.com/goccy/go-yaml/issues/290

example:

• key: $.name
• key: $.agent.name
• key: $.agents[0].name
• key: $.agents[*].name
• key: $.‘agents.name’
• key: $.repos[?(@.repository == ‘website’)].owner (requires engine “yamlpath”)

“keyonly” checks only that the key exists, whatever its value.

compatible:

• condition

default: false

“keys” defines several yaml key paths to update with the same value.

compatible:

• target

remark:

• “key” and “keys” are mutually exclusive.
• each entry accepts the same syntax as “key”.
• every key is updated with the same value.

example:

• keys:
  • $.image.tag
  • $.sidecar.tag
• keys:
  • $.agents[0].version
  • $.agents[1].version

“searchpattern” treats “file” and “files” as path patterns instead of exact paths.

The pattern must match the whole path, not just a substring.

The pattern syntax is:

    pattern:
        { term }
    term:
        '*'         matches any sequence of non-Separator characters
        '?'         matches any single non-Separator character
        '[' [ '^' ] { character-range } ']'
                    character class (must be non-empty)
        c           matches character c (c != '*', '?', '\\', '[')
        '\\' c      matches character c

character-range:
        c           matches character c (c != '\\', '-', ']')
        '\\' c      matches character c
        lo '-' hi   matches character c for lo <= c <= hi

compatible:

• condition
• target

default: false

remark:

• in a target, it also relaxes the requirement that the key exists: a file that does not hold it is ignored instead of failing the target, and a wildcard key updates the positions holding it instead of failing on the others.

“value” defines the value associated with the yaml key.

compatible:

• condition
• target

default: in a condition or a target, the output of the associated source.