DOCSEARCHbyAlgolia
Submit Docs

updatecli

repository·main·Indexed 21 days ago

https://github.com/updatecli/updatecli

A universal, declarative update policy engine designed to automate the process of keeping files, container images, and software dependencies up-to-date. It utilizes a three-stage workflow consisting of Sources (fetching new versions), Conditions (verifying prerequisites), and Targets (applying changes), with the ability to automatically open pull requests via SCM integration. Updatecli supports managing policies locally or via OCI registries and provides a scaffold bundle for publishing reusable policies.

Tokens
88.6K
Snippets
305
Records
376
Agent score
75%

What's inside updatecli

  1. How Updatecli works: The three-stage update policy

    main

    Updatecli is a declarative update policy engine. You define an update strategy in a YAML (or Go template) file, which the engine processes through three distinct stages:

    1. Sources: Fetches the new value to be applied (e.g., the latest Docker image tag, a new Helm chart version, or a GitHub release).
    2. Conditions (Optional but recommended): Verifies that specific prerequisites are met before any changes are made (e.g., checking if a specific Docker image architecture is available).
    3. Targets: Applies the fetched change to the intended file or service. If a Source Control Management (SCM) is configured, Updatecli can automatically open a pull request with the changes.

    This workflow allows you to automate the detection and application of updates across various file formats, container registries, package managers, and cloud services.

    ## updatecli.yaml
name: Update Jenkins Version

scms:
  default:
    kind: github
    spec:
      # ... SCM configuration

sources:
  jenkins:
    kind: jenkins
    spec:
      release: weekly

conditions:
  docker:
    kind: dockerimage
    spec:
      image: jenkins/jenkins

targets:
  bumpJenkins:
    kind: yaml
    spec:
      file: charts/jenkins/values.yaml
      key: $.jenkins.controller.imageTag

actions:
  default:
    kind: github/pullrequest
    target:
      - bumpJenkins

  2. Publish an Updatecli policy bundle to an OCI registry

    main

    To publish a bundle, use the updatecli manifest push command. The version tag applied to the registry will be controlled by the version field in your Policy.yaml file.

    Note: Replace <policy-name> with your desired registry path.

    updatecli manifest push \
  --config updatecli.d \
  --values values.yaml \
  --policy Policy.yaml \
  --tag "$OCI_REGISTRY/<policy-name>" \
  .

  3. Use the Updatecli scaffold bundle to publish reusable policies

    main

    The scaffold bundle provides a starting point for creating and publishing reusable Updatecli policies. It includes a Policy.yaml for metadata, values.yaml for default inputs, and updatecli.d/default.yaml for pipeline and SCM configuration.

    Requirements

    • updatecli CLI installed.
    • Access to an OCI registry (set the OCI_REGISTRY environment variable).
    • Optional: docker or another OCI client for registry operations.

    Setup

    Before use, you must update the following files to match your environment:

    1. Policy.yaml: Update policy metadata and the version field.
    2. values.yaml: Define your default policy inputs.
    3. updatecli.d/default.yaml: Configure pipeline settings and SCM settings.

  4. Verify Updatecli installation integrity

    main

    To ensure the security of your installation, you should verify the checksum signatures and the integrity of the downloaded assets.

    1. Verify the checksum file signature

    Use cosign to verify the signature of the checksums.txt.sig file against the official identity.

    2. Verify asset integrity

    Once the signature is verified, use sha256sum to check the integrity of your downloaded binary against the checksums.txt file.

    3. Verify Container signature

    If using the container image, use cosign to verify the image signature.

    ### Verify File Checksum Signature
```bash
cosign verify-blob --certificate-identity-regexp "https://github.com/updatecli/updatecli" --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' --bundle checksums.txt.sig checksums.txt

    Verify File Checksum Integrity

    sha256sum --ignore-missing -c checksums.txt

    Verify Container signature

    cosign verify --certificate-identity-regexp "https://github.com/updatecli/updatecli" --certificate-oidc-issuer "https://token.actions.githubusercontent.com" ghcr.io/updatecli/updatecli:v0.119.0

  5. Run Updatecli tests

    main

    Updatecli uses three levels of testing:

    1. Unit Tests: Fast tests (under 2s) that use mocks and have no external dependencies. Run with: make test-short

    2. Integration Tests: Standard Go tests that may include more complex logic. Run with: make test

    3. End-to-End (e2e) Tests: Requires OVH's Venom CLI and a GitHub Personal Access Token (PAT).

      • Set GITHUB_TOKEN to your PAT.
      • Set GITHUB_ACTOR to your GitHub username.
      • Run with: make test-e2e
      • Logs are written to ./e2e/venom.log.
    export GITHUB_TOKEN=your_token_here
export GITHUB_ACTOR=your_username
make test-e2e

  6. Manage Updatecli policies locally and from a registry

    main

    You can inspect, validate, and apply Updatecli policies either from your local filesystem or directly from an OCI registry.

    Local Operations

    Use the --config flag to point to your configuration directory and --values to provide input values. Any --values file provided at runtime will override the defaults in the bundle.

    Registry Operations

    To interact with policies stored in a registry, use the registry path and version tag (e.g., $OCI_REGISTRY/<policy-name>:v1.0.0).

    # Show the policy (local)
updatecli manifest show --config updatecli.d --values values.yaml

# Show the policy (registry)
updatecli manifest show $OCI_REGISTRY/<policy-name>:v1.0.0

# Validate / dry-run (local)
updatecli diff --config updatecli.d --values values.yaml

# Apply / enforce (local)
updatecli apply --config updatecli.d --values values.yaml

  7. Create a new Updatecli plugin

    main

    Plugins define how automation works for specific use cases and are located in pkg/plugins. Follow these steps to implement a new plugin:

    1. Directory Structure

    Create a new directory under pkg/plugins/ named after your package. A standard plugin contains:

    • source.go / source_test.go
    • condition.go / condition_test.go
    • target.go / target_test.go
    • spec.go
    • main.go / main_test.go

    2. Define Configuration (Spec)

    In spec.go, define a Spec struct. Capitalized fields are unmarshalled from configuration.yaml. Use yaml and jsonschema tags for validation and documentation generation.

    Important: Use specific comment formats in spec.go to enable documentation generation for the website and IDEs. Use sections like compatible, default:, remarks:, and example: within your field comments.

    type Spec struct {
    /*
    A short one-line description of the parameter

    compatible
        * source
        * condition
        * target

    default:
        A short explanation of the default value.
    */
    Field1 string `yaml:",omitempty" jsonschema:"required"`
}

    3. Implement the Resource Interface

    Your package must implement the Resource interface by providing the following methods:

    StageInterfaceDescription
    SourceSource(workingDir string, resultSource *result.Source) errorRetrieves the version to be passed to subsequent stages.
    ChangelogChangelog() stringRetrieves the changelog for a specific source.
    ConditionCondition(source string, scm scm.ScmHandler) (pass bool, message string, err error)Defines a condition that must pass to proceed.
    TargetTarget(source string, scm scm.ScmHandler, dryRun bool, resultTarget *result.Target) errorDefines how a target file is updated.

    4. Register the Plugin

    Bind the resource kind to your package in the Unmarshal function using mapstructure.Decode.

    # Example usage in configuration.yaml
sources:
  default:
    kind: packageName
    spec:
      field1: "value"

  9. Build Updatecli from source

    main

    To build the project locally, ensure you have golang, GNU Make, and goreleaser installed. You can build using make build or via Docker to target specific architectures/OSs.

    To build for Windows (386) using Docker, use the following command:

    docker run --rm -v "$PWD":/usr/src/updatecli -w /usr/src/updatecli \
  -e GOOS=windows -e GOARCH=386 golang:1.24 go build -v \
  -buildvcs=false \
  -o updatecli.exe

  11. Use the Updatecli CLI

    main

    Updatecli is a declarative dependency manager command line tool. It uses manifests to ensure target files are kept up to date through a three-stage process:

    1. Source: Retrieve a value from a third location (e.g., a file, an API, etc.).
    2. Condition: Ensure conditions are met based on the value retrieved during the source stage.
    3. Target: Update the target based on the value retrieved from the source stage.

    Commonly used commands include apply to execute updates, diff to preview changes, and prepare to prepare the environment.

    updatecli

  12. Use glob patterns for YAML files

    main

    By setting searchpattern: true, you can use glob-style patterns in the file or files fields to match multiple files. The pattern must match the entire filename, not just a substring.

    Supported Syntax:

    • *: Matches any sequence of non-separator characters.
    • ?: Matches any single non-separator character.
    • [ ]: Character classes (e.g., [a-z], [^0-9]).
    • \: Escape character.
    searchpattern: true
file: "configs/*.yaml"