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

== Description

As the number of updatecli policies increases, more and more, we realize that we need the ability to scale updatecli.
Somewhere between what we have now, duplicated manifest(s) for each Git repository, and the Autodiscovery feature.

We want to reuse updatecli policies across many projects.
We want to write updatecli policies once and reuse them everywhere.

___

For example:

. Enforcing the same Golang version used at the GitHub organization.
. Automate custom tooling updates for a GitLab organization.
. Reusing the same updatecli manifest but with different parameters based on schedules such as for minor and patch updates every week and major updates every month.
___

Updatecli allows publishing any updatecli policy to any OCI registry such as **link:https://ghcr.io[ghcr.io]**, **link://https://hub.docker.com/[dockerhub]**, **link:https://quay.io/[quay.io]**, etc..

== Policy

An updatecli policy is described by a `Policy.yaml` file.

An updatecli policy, is a "bundle" composed of "updatecli manifest", "values file", "secrets files". This bundle is identified by a reference such as:

=> `ghcr.io/updatecli/policies/policies/npm/autodiscovery:latest`.


=== Policy.yaml

{{< policymetadataparameters >}}

=== Version

An Updatecli policy is versioned using the semantic versioning specification.
When we publish a policy to a registry, the version is automatically fetched from the `version` value defined in the `Policy.yaml` file.

**latest**

When using a policy, it's possible to use the version "latest" to always use the latest available version of the policy using semantic versioning rule.

**digest**

An updatecli policy version is mutable, we can override it.
So we can use a digest to pin a specific version of the policy.

`ghcr.io/olblak/policies/rancher/docusaurus/kubewarden:0.0.5@sha256:81488900553174be2348b859f88f35c6ff0a6cab7342d8d4142bfec372fddb95`

== Examples

=== Updatecli

The repository **link:https://github.com/updatecli/policies[updatecli/policies]** contains a list of common Updatecli policies published on **link:https://github.com/orgs/updatecli/packages?tab=packages&q=policies[GitHub Registry]**.


== Share & Reuse

IMPORTANT: Currently, updatecli doesn't handle OCI registry authentication but instead relies on the local docker configuration. Therefore you must first run `docker login` before any registry operation.

**Share**

To share updatecli configuration files we run the following command:

```
  updatecli manifest push --config updatecli/updatecli.d/updatecli.yaml -t ghcr.io/updatecli/policies/golang --policy Policy.yaml .
```

As you can notice `ghcr.io/updatecli/policies/policies/npm/autodiscovery:latest` looks like a container but isn't.
It's an OCI artifact where each layer represents one of the manifest/config/values/secrets files

Using OCI registries for other things than docker/container isn't a new concept, a lot of projects like **link:https://www.kubewarden.io/[Kubewarden]**, link:https://www.conftest.dev/sharing/[Conftest], or link:https://helm.sh/[Helm] already use OCI registry to store artifacts such as WASM binaries, files, etc.

**Reuse**

To reuse this policy, run:

```
updatecli pipeline diff ghcr.io/updatecli/policies/policies/npm/autodiscovery:latest
```

**Show**

To show the content of this policy, run:

```
updatecli manifest show ghcr.io/updatecli/policies/policies/npm/autodiscovery:latest
```

Every command accepting a manifest also accepts a single policy reference as a positional argument,
in the form `NAME[:TAG|@DIGEST]`.

**Compose**

A command only accepts one policy reference at a time.
Once more than one policy is involved, declare them in an
link:/docs/core/compose/[updatecli-compose.yaml] file instead, which also lets you attach values,
secrets, and environment variables to each of them.

== Remarks

Depending on how we write the policy we can override the default value using environment variables with the Go template function `env` or just provide a new values.yaml or secrets.yaml

This approach scales better, allows policy versioning, allows retrieving the right set of files, allows signing using cosign, etc.