Docs

Compose

Description

The updatecli compose feature allows specifying a list of updatecli policies to enforce. This is useful when applying the same policies on multiple repositories.

By default, it relies on a file named updatecli-compose.yaml in the current directory, overridable with the --file (-f) flag, such as in the follow example:

updatecli-compose.yaml
policies:
  - name: Local Updatecli Website Policies
    config:
      - updatecli/updatecli.d/

  - name: Handle Nodejs version in githubaction
    policy: ghcr.io/updatecli/policies/policies/nodejs/githubaction:latest
    values:
      - updatecli/values.d/scm.yaml
      - updatecli/values.d/nodejs.yaml

  • Running updatecli compose apply would enforce the state defined in each of the policies

  • Running updatecli compose diff would show the targeted state defined in each of the policies

  • Running updatecli compose show would show the manifest generated by each of the policies

Note
update-compose.yaml is the deprecated former default filename. Updatecli still picks it up, with a warning, when no updatecli-compose.yaml exists.

Parameters

NameTypeDescriptionRequired
env_filesarray

Env_files contains a list of environment files

Example:

  • env_file1.env
  • env_file2.env
environmentsobject

Environment contains a list of environment variables

Example: ENV_VAR1: value1 ENV_VAR2: value2

includearrayInclude contains a list of compose files to include
namestringName contains the compose name
policiesarrayPolicies contains a list of policies
    configarrayConfig contains a list of Updatecli config file path
    idstringID contains the policy ID, it can be used to filter policies to execute
    namestringName contains the policy name
    policystringPolicy contains the policy OCI name
    secretsarraySecrets contains a list of Updatecli secret file path
    valuesarrayValues contains a list of Updatecli config file path
    valuesinlineobject

ValuesInline contains a list of inline values for Updatecli config A deep merge will be performed between global inline values and policy inline values if both are defined.

Example: key1: value1 key2: value2

secretsarraySecrets contains a list of Updatecli secret file path This is the default secret file that will be applied to all policies if not overridden by the policy secret file.
valuesarrayValues contains a list of Updatecli config file path This is the default values file that will be applied to all policies if not overridden by the policy values file.
valuesinlineobject

ValuesInline contains a list of inline values for Updatecli config This is the default inline values that will be applied to all policies if not overridden by the policy inline values. A deep merge will be performed between global inline values and policy inline values if both are defined.

Example: key1: value1 key2: value2

⚠ This table is generated from the Updatecli codebase and may contain inaccurate data. Feel free to report them on github.com/updatecli/updatecli

Values precedence

A policy pulled from a registry ships its own values and secrets files. The compose file can add more, at two levels: the root keys values, valuesinline, and secrets apply to every policy, while the same keys under an individual policy apply to that policy only.

They are combined rather than replaced, in this order, later winning over earlier:

  1. values and secrets shipped by the policy itself

  2. root level values, then the policy’s own values

  3. root level secrets, then the policy’s own secrets

  4. root level valuesinline, then the policy’s own valuesinline

The merge is recursive, so two files can contribute different keys to the same nested object, and only conflicting leaves are overridden.

Note
Paths in values and secrets are resolved relative to the compose file, not to the current working directory.

Environment variables

The root keys environments and env_files set environment variables before the policies are evaluated, which is how you feed {{ requiredEnv "…​" }} in a policy without exporting anything in your shell.

environments:
  UPDATECLI_GITHUB_OWNER: updatecli

env_files:
  - .env

policies:
  - name: Local policies
    config:
      - updatecli/updatecli.d/

The two keys do not behave the same way:

  • environments sets each variable unconditionally, overriding whatever the shell already exported.

  • env_files reads dotenv files and never overrides an existing variable, which makes it suitable for defaults rather than for forcing a value.

Important

  • These variables are set in the Updatecli process itself, so they apply to every policy of the run, not only to the ones declared after them.

  • Unlike values and secrets, env_files paths are resolved relative to the current working directory, not to the compose file.

Splitting a compose file

The root key include loads other compose files, whose policies are appended to the run. Circular includes are detected and skipped, so a file is never loaded twice.

include:
  - compose/golang.yaml
  - compose/container.yaml

Included paths are resolved relative to the file declaring them.

Selecting policies

Give a policy an id to be able to run a subset of the compose file:

policies:
  - name: Handle Nodejs version in githubaction
    id: nodejs
    policy: ghcr.io/updatecli/policies/policies/nodejs/githubaction:latest
# Only run the policies with these ids
updatecli compose diff --only-policy-ids=nodejs

# Run everything but these ones
updatecli compose diff --ignored-policy-ids=nodejs
Important
With --only-policy-ids, policies without an id are skipped, since they cannot be selected.

Examples

Updatecli

The repository updatecli/policies contains a list of common updatecli policies published on GitHub Registry.

Go Further

  • To know more about how a policy is built and published, see Updatecli policy

  • To know more about filtering the pipelines inside those policies, see labels

Last updated on July 30, 2026
Prev
Quick Start
Next
Gitea Branch