cub changeworkflow update

Update a change workflow or multiple change workflows

Synopsis

Update a change workflow or multiple change workflows using bulk operations.

A workflow is edited in place rather than versioned. A change order takes a copy of its workflow when it is created and is promoted and released against that copy, so an edit applies to the change orders created after it and changes nothing about a rollout already under way. To move a change under the edited rules, create a new change order for it.

Single change workflow update:

  # Name the stages and gate each of them alike. A stage the workflow already has keeps its
  # other fields; one it does not have is added, and one not named is removed
  cub changeworkflow update --space workflows myapp-main-line \
    --stage dev --stage staging --stage prod --prerequisites Released

  # Change one stage: which spaces it selects, and what gates entry to it
  cub changeworkflow update --space workflows myapp-main-line \
    --stage-where-space "prod=Labels.Stage = 'prod' AND Labels.Region = 'us-east1'" \
    --stage-prerequisites 'prod=Released;Healthy;two-approvers'

  # Declare an attestation prerequisite and a custom one, and require them at the end
  cub changeworkflow update --space workflows myapp-main-line \
    --attestation-prerequisite two-approvers --attestation-prerequisite-count two-approvers=2 \
    --custom-prerequisite "code-freeze=cel:Space.Annotations['code-freeze'] != 'true'" \
    --final-prerequisites 'Released;Healthy'

  # Set any field by its path
  cub changeworkflow update --space workflows myapp-main-line \
    --set "Stages.?Name=prod.ReleasePrerequisites=release-manager"

  # Replace the whole workflow from a file
  cub changeworkflow update --space workflows myapp-main-line --filename workflow.yaml

Bulk update with --patch:

Update multiple change workflows at once based on search criteria. Requires --patch with no positional arguments.

Examples:

  # Label every workflow whose last stage gates on live status
  cub changeworkflow update --patch --where "Final.Prerequisites ? 'Healthy'" --label Gated=true

  # Patch specific workflows from JSON
  echo '{"Final": {"Prerequisites": ["Released"]}}' | cub changeworkflow update --patch \
    --changeworkflow myapp-main-line --from-stdin

cub changeworkflow update [<slug or id>] [options...] [flags]

Options

      --annotation strings                                     annotations in key=value format; can separate by commas and/or use multiple instances of the flag
      --attestation-prerequisite stringArray                   one attestation prerequisite of the ChangeWorkflow, as <name> (repeatable). On an update the ones named are the ones it has, in that order: one it had before keeps its other fields
      --attestation-prerequisite-allow-authors stringArray     AllowAuthors of one attestation prerequisite, as <name>=true|false (repeatable; <name>=- clears it). Count an attester who wrote a Revision of the change
      --attestation-prerequisite-count stringArray             Count of one attestation prerequisite, as <name>=<value> (repeatable; <name>=- clears it). How many distinct attesters must record a Pass on each Revision
      --attestation-prerequisite-description stringArray       Description of one attestation prerequisite, as <name>=<value> (repeatable; <name>=- clears it). What the requirement is for, in the author's words
      --attestation-prerequisite-distinct-groups stringArray   DistinctGroups of one attestation prerequisite, as <name>=true|false (repeatable; <name>=- clears it). Require an attester from each group of FromGroupIDs, which it requires
      --attestation-prerequisite-from-group-ids stringArray    FromGroupIDs of one attestation prerequisite, as <name>=<value>[;<value>...] (repeatable; <name>=- clears it). The Groups whose members' Attestations count, beside the Users FromUserIDs names
      --attestation-prerequisite-from-user-ids stringArray     FromUserIDs of one attestation prerequisite, as <name>=<value>[;<value>...] (repeatable; <name>=- clears it). The Users whose Attestations count
      --attestation-prerequisite-ignore-fail stringArray       IgnoreFail of one attestation prerequisite, as <name>=true|false (repeatable; <name>=- clears it). Count only passes
      --attestation-prerequisite-max-age stringArray           MaxAge of one attestation prerequisite, as <name>=<value> (repeatable; <name>=- clears it). How old an Attestation may be and still count, as a duration such as 72h
      --attestation-prerequisite-type stringArray              Type of one attestation prerequisite, as <name>=<value> (repeatable; <name>=- clears it). The Attestation Type that counts
      --changeworkflow strings                                 target specific change workflows by slug or UUID for bulk patch (can be repeated or comma-separated)
      --custom-prerequisite stringArray                        one custom prerequisite of the ChangeWorkflow, as <name>=<expression> (repeatable). On an update the ones named are the ones it has, in that order: one it had before keeps its other fields
      --custom-prerequisite-description stringArray            Description of one custom prerequisite, as <name>=<value> (repeatable; <name>=- clears it). What the gate checks, in the author's words
      --delete-gate strings                                    delete gates in key[=true] format; can separate by commas and/or use multiple instances of the flag
      --display-name string                                    friendly name for the entity, which need not be unique or URL-safe; an entity without one is shown by its slug
      --dry-run                                                report what the command would write, and write nothing
      --filename string                                        Read the ConfigHub entity's fields, as YAML or JSON, from file, URL (https://), or stdin (-), as --from-stdin does; mutually exclusive with --from-stdin
      --filter string                                          Filter entity to apply to the list. Specify as 'space/filter' for cross-space filters or just 'filter' for current space. Supports both slugs and UUIDs. The filter will be combined with any --where clause using AND logic. Examples: "production-filters/security-check", "my-filter-uuid", "validation-rules"
      --final-prerequisites string                             gates the last stage must satisfy for the rollout to read as completed, as <name>[;<name>...] (use '-' to clear)
      --from-backing-units                                     patch each ChangeWorkflow selected with what its backing Unit holds that it has not taken yet; the patch the other flags make is applied after it
      --from-stdin                                             Read the ConfigHub entity's fields, as YAML or JSON, from stdin; merged with command arguments on create, and merged with command arguments and existing entity on update. A field the entity does not have, or one only the server sets, is refused; cub <entity> explain lists the fields
  -h, --help                                                   help for update
      --hidden-reason string                                   hide the entity, giving the reason as a name such as Archived: lists and bulk operations leave it out unless --include-hidden names the reason (use '-' to clear, which shows the entity again)
      --include-hidden string[="*"]                            Also select hidden entities, to list or to act on: those hidden for the given HiddenReasons, comma-separated, as in --include-hidden=BackingUnit, or for any reason when given no value or "*". ConfigHub/YAML Units, which hold the configuration of other entities, are hidden with the reason BackingUnit. A --where naming entities by Slug or ID selects them whether hidden or not
      --label strings                                          labels in key=value format; can separate by commas and/or use multiple instances of the flag
  -o, --output string                                          Output format. One of: json, yaml, name, wide, mutations, jq=<expr>, yq=<expr>, custom-columns=<spec>
      --patch                                                  use patch API for individual or bulk operations
      --permission strings                                     permission in format Action:UserIDOrUsername, Action:group:GroupSlugOrID or Action:serviceaccount:ServiceAccountSlugOrID to add, or the same prefixed with - to remove (e.g., Manage:user@example.com, View:group:platform, View:serviceaccount:deploy-bot, -View:user@example.com, can be repeated)
      --prerequisites strings                                  gates given to every stage and to the final stage (can be repeated or comma-separated); requires --stage
      --quiet                                                  No default output.
      --replace                                                Replace entity instead of merging when using --from-stdin or --filename
      --set stringArray                                        set a field of the ChangeWorkflow by its path, as <path>=<value> (repeatable). A path is field names separated by dots; a list element is addressed as ?<key>=<value> or by position, as in Stages.?Name=prod.WhereSpace, and is added if it is not there. A list of plain values separates them with ';'; an object or a list of objects is given as YAML or JSON. A reference is given as it is elsewhere, by slug, <space>/<slug> or ID. With --patch, only a path with no list element in it
      --stage strings                                          name of one stage of the workflow (can be repeated or comma-separated), given in the order a change is promoted through them. The ones named are the stages the workflow has: one it had before keeps its other fields, one it did not have selects the Spaces labeled with its name, and one not named is removed
      --stage-prerequisites stringArray                        Prerequisites of one stage, as <name>=<value>[;<value>...] (repeatable; <name>=- clears it). The stage's entry gates, each naming a built-in check or one declared in CustomPrerequisites
      --stage-release-prerequisites stringArray                ReleasePrerequisites of one stage, as <name>=<value>[;<value>...] (repeatable; <name>=- clears it). Gates on publishing a Release for a change order in one of the stage's Spaces, each naming one declared in AttestationPrerequisites
      --stage-where-space stringArray                          WhereSpace of one stage, as <name>=<value> (repeatable; <name>=- clears it). Selects the stage's Spaces: a where expression over Spaces, intersected with the change order's InScopeSpaceIDs
      --unset stringArray                                      clear a field of the ChangeWorkflow by its path, or remove the list element the path ends at (repeatable)
      --verbose                                                Detailed output, additive with default output
      --where string                                           Filter expression using SQL-inspired syntax. Supports conjunctions with AND. String operators: =, !=, <, >, <=, >=, LIKE, NOT LIKE, ILIKE, ~~, !~~, ~, ~*, !~, !~*. Pattern matching with LIKE/ILIKE uses % and _ wildcards. Regex operators (~, ~*, !~, !~*) support POSIX regular expressions. A related entity is referenced by prefix, as in "UpstreamUnit.Slug = 'base'"; when the reference names a list, a * segment matches any element, as in "FromLink.*.Slug = 'upgrade-app'". Examples: "Slug LIKE 'app-%'", "DisplayName ILIKE '%backend%'", "Slug ~ '^[a-z]+-[0-9]+$'". 'cub <entity> explain --where' lists the attributes an entity's expressions can name
      --with-backing-units                                     give each ChangeWorkflow the bulk operation writes a backing Unit if it has none: a ConfigHub/YAML Unit holding its configuration, kept in step with it

Options inherited from parent commands

      --component string   the Component of --variant, when that names the variant alone; --variant <component>/<variant> says the same in one flag
      --context string     The context to use for this command
      --debug              Debug output
      --space string       space to operate in, by slug or UUID. Omitted, a list or bulk operation spans the organization and a single entity is named as <space>/<slug>; "*" means the same as omitting it
      --variant string     variant to operate in, as <component>/<variant>, or as <variant> with --component: the space naming that Component whose Variant label is <variant>. The same scope as --space, named by what it is rather than by the space's slug; the two cannot be combined

cub changeworkflow update