Quick Start

Introducing a very basic updatecli workflow.

Updatecli is a command-line tool to update your files. You specify in a manifest how you expect your files to be updated and then you run updatecli to apply the update.

This quickstart requires three components:

  1. Updatecli binary installed.

  2. The test data file to update is in this guide.

  3. The updatecli manifest is also in this guide.

Installation

Updatecli is a standalone binary available on GitHub with packages for Windows, Linux, and OSX.

If you don’t have a local installation, please follow the installation guide at Installation →

Scenario

We will update a data file, if an update is needed according to our specified condition.

Data file

We need a sample data file that we want to update (if needed). We are using a YAML file defining the "latest" Jenkins Docker image tag running in our infrastructure.

# data.yaml
container:
  image: jenkinsci/jenkins
  tag: 2.275

Updatecli Pipeline

Updatecli needs at least one manifest to know what update pipeline to apply.

In this manifest, we introduce three important concepts of an updatecli manifest.

  1. A Source definition describes where a piece of information is coming from. In the current example, we’re looking for the latest Jenkins weekly version.

  2. A Target definition describes what we want to update based on a source output. In our example, we want to update the key "container.tag" in the file "data.yaml" to the version retrieved from the source, the latest Jenkins weekly version.

  3. A Condition definition defined conditions required to update the target. In this example, we want to test that the docker image "jenkinsci/jenkins:<latest Jenkins weekly version>" exists on DockerHub.

Updatecli Pipeline
# manifest.yaml
name: QuickStart example

# Defines how to get "source" information such as Jenkins version
sources:
  jenkinsVersion:
    name: Get the latest Jenkins weekly version
    kind: jenkins
    spec:
      release: weekly
# Defines "conditions" required to update targets
conditions:
  dockerimage:
    name: Is Jenkins weekly tag published on DockerHub
    kind: dockerimage
    spec:
      image: jenkins/jenkins

# Defines "targets" which need to be updated if different than "source" information.
targets:
  dataFile:
    name: Bump Jenkins Docker Image Tag
    kind: yaml
    spec:
      key: container.tag
      file: data.yaml

Source, Condition, and Target behave differently based on the plugin used, which is defined by the key "kind".

Updatecli Execution

Now that we have a data file and an updatecli manifest, describing how to update our file, let’s see how to use updatecli.

So for doing so, please execute the following command:

  1. To see what would change: updatecli diff --config manifest.yaml

  2. To apply the change: updatecli apply --config manifest.yaml

  3. To see that nothing needs to be changed anymore: updatecli apply --config manifest.yaml

Video

INFO: You can improve this video by contributing to updatecli/demo-terminal

Conclusion

Using this example, we saw how updatecli works with a simple pipeline. There are many improvements possible for this pipeline, such as automatically publishing updated files to a git repository, using the GitHub pull-request workflow, transforming the source value, not retrieving the latest version, and others.

The real power of updatecli is to combine different plugins to easily implement a customized update pipeline.

Go Further

Core

Understand how the different core concepts work. Core →

Plugins

Understand how to combine the different plugins. Plugins →

Continuously Update Everything

Learn how to continuously run updatecli to apply updates. CI →

Contributing

Find out how to contribute to Updatecli. Contributing →

Help

Get some help. Help →

Last modified on July 2, 2024
Edit this page on GitHub
← Introduction
Installation →