Versions and the developer loop

weikio run publishes and deploys in one step while you develop. For everything else the two steps are apart: weikio apply publishes a version, and weikio deploy runs a version in an environment.

Publish a version#

$ weikio apply -f ./finance/

Target: https://hub.example, project finance (from finance/project.yaml), environment devtest (context)
project finance unchanged
variable finance/erp-url unchanged
variable production/finance/erp-url updated
integration finance/erp-invoice-export created (version 1.0.0, built in 20.8 s)

Nothing new is running yet. To run it:
  weikio deploy finance/erp-invoice-export --env devtest

A version is immutable, like a package published with npm publish. Applying the same files again prints unchanged. Changing the files without raising the version is refused, and the error says what to type:

$ weikio apply -f ./finance/erp-invoice-export

Target: https://hub.example, project finance (from finance/project.yaml)
integration finance/erp-invoice-export refused: Version '1.0.0' is already published.
    Set another with --version <version>, or bump it with --bump patch.

--bump patch, --bump minor or --bump major raises the version in integration.yaml the way npm version does, and publishes it:

$ weikio apply -f ./finance/erp-invoice-export --bump minor

Target: https://hub.example, project finance (from finance/project.yaml), environment devtest (context)
integration.yaml updated to 1.1.0
Uploading 2/9 files, building...
integration finance/erp-invoice-export updated (version 1.1.0, built in 17.3 s)

Nothing new is running yet. To run it:
  weikio deploy -f ./finance/erp-invoice-export --env devtest

An integration whose integration.yaml has no version: line starts at 0.1.0 and gets the next patch version on each apply that changes it. weikio init writes no version line, so your first integrations stay on that path until you add one.

What the build does#

The CLI sends only the files the hub doesn’t have yet, by their content hash, so a later version uploads only what changed. The hub then builds the version once:

1. On Camel 4.22.1 it validates the YAML routes with Camel, so a route Camel refuses fails during the apply with Camel’s own message.
2. It resolves the jars of the integration’s Camel line, the components the routes use and the dependencies integration.yaml lists.
3. It compiles the Java beans with javac.
4. It adds the jars every integration needs for logging and OpenTelemetry, and stores every file and jar in the project’s store by its SHA-256 hash, with a manifest of the whole set.

Most of a first build goes to resolving Camel’s libraries, measured at about 15 seconds. A build that changes only configuration is done in a second or two. The agents fetch only the files they don’t already have, so moving from 1.1.0 to 1.2.0 with one changed route fetches that one file. Two agents on one version run the same jars.

What a version contains#

$ weikio get versions finance/erp-invoice-export

VERSION          CAMEL    CREATED                BY                 NOTE                DEPLOYED IN
1.1.0 (latest)   4.22.1   2026-09-16 14:31 UTC   anna@example.com   invoice mapper v2   -
1.0.0            4.22.1   2026-09-15 09:12 UTC   anna@example.com   -                   devtest, production

weikio describe version finance/erp-invoice-export 1.1.0 prints one version in full: the source and bundle digests, the exact Camel version and the kamelets version, the dependencies, the kamelets with their source, every jar with its digest, the variable and secret names the routes use, and applied from <repository>@<commit> when a pipeline published it. The build log is kept with the version, so you can read what the builder printed months later.

weikio version compare finance/erp-invoice-export 1.0.0 1.1.0 prints every file that differs between two versions as a unified diff. The Versions section of the integration’s page in the admin UI shows the same.

Run it on your machine first#

weikio dev run runs the folder on your machine with Camel JBang, on the integration’s Camel line, with the environment’s values and the project’s and the platform’s kamelets:

$ weikio dev run ./erp-invoice-export --env devtest

The CLI finds the variable names in the folder itself, so the integration doesn’t have to be applied first. Secret values stay out of the run unless you add --with-secrets, which reveals them and records each reveal in the audit log. The kamelets that publish and read events get local stand-ins. --reload turns on Camel’s own reloading, so a saved route reloads in the running process.

Check before you apply#

weikio validate checks the files before anything is built: the fields of each document, the names, the manifest and the placeholders. A pipeline runs it to fail early.

$ weikio validate -f ./finance
$ weikio diff -f ./finance --env devtest
$ weikio apply -f ./finance --env devtest --dry-run

weikio diff and weikio apply --dry-run show what an apply would do: which versions it would create, which variables change, which deployments move and what it would refuse. A route step Camel doesn’t know passes validate and diff. On Camel 4.22.1 the build of the apply finds it, so a pipeline catches it in its devtest job.