Updatecli Policies

The official collection of reusable Updatecli policies, published as OCI artifacts to ghcr.io/updatecli/policies.

Instead of copying the same update manifest into every repository you own, you pull a versioned policy from a registry and point it at your project.

→ Browse the full policy catalogue

---

What is an Updatecli policy?

An Updatecli policy is a bundle — one or more Updatecli manifests plus their values and secrets files — described by a Policy.yaml file and published to an OCI registry such as ghcr.io, Docker Hub, or Quay. Despite the container-shaped reference, a policy is not a container image: it is an OCI artifact where each layer holds one of the bundled files.

If you are new to the concept, read this first:

📖 Updatecli Policy — share and reuse

That page explains the Policy.yaml schema, how versioning works, and how to publish your own policies. This repository is the reference implementation of everything described there.

Why use a shared policy instead of a local manifest?

• Write once, run everywhere. Enforce the same Golang version across an entire GitHub organisation without duplicating a manifest per repository.
• Versioned and upgradable. Policies follow semantic versioning, so consuming projects can adopt changes at their own pace rather than being broken by an edit to a shared file.
• Parameterisable. The same policy can run with different values on different schedules — patch updates weekly, major updates monthly — by overriding values at runtime.
• Auditable. A policy reference is a single line in your repository. What it does is inspectable before you run it (see Inspect before you run).

---

Requirements

• Updatecli installed locally, or the updatecli-action in CI.
• A Docker-compatible login to ghcr.io. Updatecli does not manage registry credentials itself — it reads your local Docker configuration, so you must authenticate before any registry operation:

  docker login ghcr.io

---

Quick start

A note on flags. A policy reference is passed as the last positional argument, never with --config. That flag is for local manifest files and directories only. updatecli compose is separate again and takes --file.

updatecli diff ghcr.io/updatecli/policies/autodiscovery/golang:0.13.1  # ✅
updatecli diff --config ghcr.io/updatecli/policies/autodiscovery/golang:0.13.1  # ❌
updatecli diff --config ./updatecli/updatecli.d  # ✅ local manifest

Inspect before you run

A policy will modify files in your repository and may open pull requests. Read it first:

updatecli manifest show ghcr.io/updatecli/policies/autodiscovery/golang:0.13.1

See what would change

diff performs no writes. This is the command to reach for while evaluating a policy:

updatecli diff ghcr.io/updatecli/policies/autodiscovery/golang:0.13.1

Apply it

updatecli apply ghcr.io/updatecli/policies/autodiscovery/golang:0.13.1

---

Pinning versions

Policy tags are mutable. A published version can be overwritten, so :0.13.1 today is not guaranteed to be byte-identical to :0.13.1 tomorrow, and :latest will silently move underneath you.

For anything running unattended in CI, pin to a digest:

updatecli apply ghcr.io/updatecli/policies/autodiscovery/golang:0.13.1@sha256:<digest>

Resolve the digest for a tag with:

docker buildx imagetools inspect ghcr.io/updatecli/policies/autodiscovery/golang:0.13.1

Guidance by context:

Context	Recommended reference
Local experimentation	:latest
Everyday CI	:0.13.1 (explicit semver)
Regulated / high-trust CI	:0.13.1@sha256:... (digest)

---

Running several policies together

updatecli compose runs a set of policies from a single file. Create updatecli-compose.yaml:

policies:
  - name: Keep Go toolchain and modules up to date
    policy: ghcr.io/updatecli/policies/autodiscovery/golang:0.13.1
  - name: Keep npm dependencies up to date
    policy: ghcr.io/updatecli/policies/autodiscovery/npm:0.14.1

Then:

# Preview
updatecli compose diff --file updatecli-compose.yaml
 
# Apply
updatecli compose apply --file updatecli-compose.yaml

Values supplied at runtime override the bundle defaults. See each policy's own README — linked from POLICIES.md — for the values it accepts.

Full reference: Compose documentation.

---

Running in GitHub Actions

name: Updatecli
on:
  schedule:
    - cron: "0 6 * * 1"
  workflow_dispatch:
 
permissions:
  contents: write
  pull-requests: write
 
jobs:
  updatecli:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7.0.1
      - uses: updatecli/updatecli-action@v3.4.0
      - run: updatecli compose apply --file updatecli-compose.yaml
        env:
          UPDATECLI_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          UPDATECLI_GITHUB_ACTOR: ${{ github.actor }}

Grant the smallest token scope the policy actually needs. A policy that only opens pull requests does not need push access to protected branches.

---

Developing a policy locally

Policies live under updatecli/policies/<name>/. To render one from source without publishing it:

updatecli manifest show \
  --config ./updatecli/policies/<name>/updatecli.d \
  --values ./updatecli/policies/<name>/values.yaml

Render its dependency graph:

updatecli manifest show \
  --config ./updatecli/policies/<name>/updatecli.d \
  --values ./updatecli/policies/<name>/values.yaml \
  --graph --graph-flavor mermaid

Repository-level tasks:

make help       # list available targets
make test       # validate that every policy is publishable
make e2e-test   # run end-to-end tests

---

Publishing

CI publishes a policy automatically when the version field in its Policy.yaml changes on main. Versions must be semver-compliant without a leading v.

When changing a policy:

1. Bump version in the policy's Policy.yaml.
2. Update the policy's CHANGELOG.md and README.md.
3. Regenerate POLICIES.md and commit it.
4. Make sure CI validation passes.

---

Contributing

Contributions are welcome — a new policy is often only a Policy.yaml and a manifest away. See CONTRIBUTING.adoc for the full guidelines.

Before opening a pull request:

• Open an issue first for anything non-trivial.
• Bump Policy.yaml version if behaviour changes.
• Update the policy README, changelog, and example values.
• Make sure CI passes. New policy directories should follow the naming convention <category>/<subject>[/<action>], matching the existing autodiscovery/* policies.

By participating you agree to the Code of Conduct.

---

FAQ

Why a monorepo? It keeps discovery, CI, and publishing in one place. Splitting into multiple repositories remains an option if the catalogue outgrows it.

Can I publish my own policies? Yes — to any OCI registry you control. See share and reuse.

A policy proposed a change I didn't expect. Run updatecli manifest show <policy> to see exactly what it does, and open an issue with the output. Always use diff before apply on a new policy.

---

Getting help

• 💬 Matrix chat
• 🐛 Issues
• 📖 Updatecli documentation
• 📦 Published packages

Thanks to all the contributors ❤️

License

Apache-2.0