# Configuration<no value>
// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4

Updatecli requires a configuration file, or "manifest", which describes the update pipeline.
A manifest describes the "what", the "when", and the "where" of the update pipeline.

**What**

The "what" is the "source" and defines what piece of information we're looking for, such as the latest application release version, a docker image tag, etc.

**When**

The "when" is a "condition", if the condition is satisfied then the target is updated.

**Where**

The "where" is the "target" and defines where we want to update a piece of information like a value from a Dockerfile or YAML file.


== Manifest

=== Pipeline ID

By default, Updatecli treats each manifest file as an independent update pipeline.
For reproducibility, it automatically generates a deterministic pipeline ID based on the manifest’s content.
This ensures that the same manifest always gets the same pipeline ID across multiple runs.

Updatecli uses this ID in several places, such as the name of the temporary branch it creates when preparing pull requests.

If multiple manifest files share the same pipeline ID (either because they have identical content or because you explicitly set the same pipelineid), they will share the same temporary branch.

++++
<details><summary>updatecli.d/docker.yaml</summary>

<pre>
name: Update Golang Version in Dockerfile
pipelineid: go/version
...
</pre>
</details>
++++

++++
<details><summary>updatecli.d/gomod.yaml</summary>

<pre>
name: Update Golang Version in Go Mod
pipelineid: go/version
...
</pre>
</details>
++++

[IMPORTANT]
====
* By default, The generated pipelineID is a hash based on the content of the manifest file so this ID may change if the content of the manifest is changed.
* Since the pipelineid is used in the name of the temporary Git branch, avoid using / in the ID.
In Git, / is treated as a directory separator in branch names, which can make branch management confusing.
====

=== Manifest Order

When running multiple manifests, Updatecli can order them explicitly with the root keys `id` and `dependson`.

Use `id` to declare a manifest identifier, and `dependson` to list which manifest IDs must run first.
This affects manifest execution order only and does not replace `pipelineid`.

To learn more, see **link:/docs/core/order[manifest order]**.

=== File

Each Updatecli pipeline is defined in its own manifest file.
The manifest is split into different stages, "source", "conditions", "targets",
where every stage relies on a plugin to adapt the behavior.

A file can be of type "yaml" or "Go Template" using file extensions ".yaml",".yml", or ".tpl").

Manifests are given to the updatecli command using the global flag `--config <go_template_file>` and `--values <yaml_file>`.
It accepts either a single file or a directory.
If a directory is specified, then it runs recursively on all the go templates (or yaml files) in the directory.

IMPORTANT: Manifest files starting with an underscore `_` are considered as partial files and are not executed. More information on the partial section below.

=== Partial

Partials are named, reusable fragments of an Updatecli manifest, typically used to define repeatable logic for:

* Scms (e.g., Git repository details)
* Sources (e.g., version checks)
* Conditions
* Targets

These fragments are automatically available to pipelines within the same directory, helping keep your main manifests DRY (Don't Repeat Yourself) and maintainable.

A partial file must have a filename that starts with an underscore (`_`). Updatecli never loads these as standalone manifest files.

IMPORTANT: Partial files are concatenated into the main manifest during execution. If a `---` YAML document separator is present, the partial feature will be disabled, as the resulting content would be treated as multiple separate YAML documents.

++++
<details><summary>updatecli.yaml</summary>

<pre>
autodiscovery:
  groupby: {{ .groupby }}
#{{ if or (.scm.enabled) }}
  scmid: default
  actionid: default
# {{ end }}

  crawlers:
    golang/gomod:

</pre>
</details>

++++

++++
<details><summary>_scm.yaml</summary>

<pre>
# {{ if and (.scm.enabled) ( eq .scm.kind "gitea")) }}
actions:
    default:
        title: 'deps: bump HUGO to {{ source "hugo" }}'
        kind: "gitea/pullrequest"
        scmid: "default"

scms:
    default:
        kind: "gitea"
        spec:
            user: '{{ .scm.user }}'
            # {{ if .scm.email }}
            email: '{{ .scm.email }}'
            # {{ end }}
            owner: '{{ .scm.owner }}'
            repository: '{{ .scm.repository }}'
            token: '{{ .scm.token }}'
            username: '{{ .scm.username }}'
            branch: '{{ .scm.branch }}'
            # {{ if .scm.url }}
            url: '{{ .scm.url }}'
            # {{ end }}
# {{ end }}
</pre>
</details>

++++


=== Content

Using go templates allows us to specify generic values in a different YAML file, using `--values`.
We then reference those values from each go template.
Updatecli also provides a custom function called `requiredEnv` to inject an environment variable into the template example, `{{ requiredEnv "PATH" }}`. +
Additionally, all functions from the https://masterminds.github.io/sprig/[Sprig template library] are available.

More information on Go templates is https://golang.org/pkg/text/template/[here].

An example values file can contain:

++++
<details><summary>values.yaml</summary>
<pre>
{{<include "assets/code_example/docs/core/configuration/values.yaml">}}
</pre>
</details>
++++

That can used in a pipeline manifest as:

++++
<details><summary>updatecli.yaml</summary>
<pre>
{{<include "assets/code_example/docs/core/configuration/updatecli.yaml">}}
</pre>

</details>
++++

== Go Further

* To know more about Condition syntax **link:/docs/core/condition[condition]**
* To know more about Source syntax **link:/docs/core/source[source]**
* To know more about Target syntax **link:/docs/core/target[target]**
* To know more about manifest ordering **link:/docs/core/order[manifest order]**
* To know more about **link:/plugins/[Plugins]**
** More specifically about the **link:/plugins/source[source]**
** More specifically about the **link:/plugins/condition[condition]**
** More specifically about the **link:/plugins/target[target]**
** More specifically about the **link:/plugins/scm[SCM]**