Timoni modules are distributed as Open Container Initiative
(OCI) artifacts. When publishing a module version to a container registry,
the version number is used as the OCI artifact tag.
The container images declared in the module’s images.cue file are recorded
in the sh.timoni.images annotation as a comma-separated list of image
references, sorted alphabetically. Each reference is composed from the image
default values in the repository[:tag][@digest] format, where the tag and
digest are included only when set to non-empty values.
Modules without an images.cue file carry no sh.timoni.images annotation,
and the annotation can be overridden with --annotation sh.timoni.images=<LIST>.For reproducible builds, Timoni preserves explicit creation, source and
revision annotations, then uses SOURCE_DATE_EPOCH or the Git commit time for
the creation date. Git source and revision metadata are added when available.
The version is required and becomes the manifest version annotation and local
reference name. Use --format=oci-layout for directory output.
Local outputs are unsigned; existing output paths are rejected.The archive produced by mod build can be pushed to a registry with
timoni mod push without re-packaging the source module. The version is read
from the archive manifest, so it must not be passed again:
timoni mod build ./modules/my-app -v 1.0.0 -o ./my-app-1.0.0.oci.tartimoni mod push ./my-app-1.0.0.oci.tar oci://ghcr.io/org/modules/app
Annotations and symlink resolution are fixed at build time, so
--annotation and --resolve-symlinks are not supported when pushing a
pre-built archive.
Timoni offers a command for publishing a module version
by packaging a local module as an OCI artifact and pushing
the artifact to a container registry.When publishing a module with timoni mod push,
the version number must be specified using the --version flag.
The --latest flag is used to mark a stable release as the latest version.
When --latest is set to true, Timoni will push the version tag,
then it will tag the version as latest in the container registry.
ImmutabilityNote that a Timoni module version should be immutable.
The only tag that is suppose to be mutable, is the latest one.
Overriding an existing version tag in the container registry should be avoided,
some registries allow enforcing immutability for semver tags but this is not guranteed by default.
Timoni modules can contain files that are not meant to be published.
To exclude files from the module artifact, you can add a timoni.ignore file
in the module root directory.The timoni.ignore file must contain rules in the
.gitignore pattern format.It is recommended to exclude Git, Go and CUE tools related files, for example:
When packaging a module, Timoni skips symbolic links by default.
To include the link targets in the artifact as regular files and
directories, run timoni mod push or timoni mod build with the
--resolve-symlinks flag:
timoni mod push ./path/to/module oci://docker.io/org/app-module \ --version=1.0.0 \ --resolve-symlinks
The same flag applies when building the module artifact locally:
timoni mod build ./path/to/module -v 1.0.0 -o ./app-module-1.0.0.oci.tar \ --resolve-symlinks
This allows sharing files between modules in a monorepo, for example
by symlinking the vendored CUE schemas under cue.mod/gen.The timoni.ignore rules apply to the resolved content at its
in-module path, the same as for regular files and directories.The timoni artifact push and timoni artifact build commands take the
same flag for packaging the symlink targets found in the given directory.
Local modulesWhen building a module from a local path, timoni build, timoni apply
and timoni mod vet read the module files in place from the source
directory, following symbolic links the same way as the operating system.
Note that a module which relies on symlinked files builds locally but
is published incomplete unless pushed or built with --resolve-symlinks.
Timoni offers a command for listing all the versions available in a
container registry for a particular module.The timoni mod list oci://<module-url> prints a table with the versions order
by semver and the OCI digest corresponding to each version. The newest 100 versions
are listed by default, use --limit 0 to list all of them or --limit <n> to
change the number of versions shown. Pass --with-digest=false to skip the
digest lookups when only the version list is needed.Example:
$ timoni mod list oci://ghcr.io/stefanprodan/modules/podinfoVERSION DIGEST latest sha256:ddf8be195f69ad767b40d5c3fec3a8a85482bf6bf469d949a462cb4fd27df580 6.14.1 sha256:ddf8be195f69ad767b40d5c3fec3a8a85482bf6bf469d949a462cb4fd27df580 6.14.0 sha256:32082e8ac0bba9ee2a3f95534f52c94f5a41dc642bb396c73b04fa18aff147d7 6.13.0 sha256:37312e975dc9bc6c1f4ebccc90f55caf2d35ce15f1b0f59794348924fa0193e9 6.12.0 sha256:99bdcbc42933bd0d14c0c5496541059063f0c111393f5b773cd0e2bbf6bed435 6.11.2 sha256:12b1fa57fdf554110a1ec3519d02f69a6896515967d652029bc953a7e988ff29
