Adding tasks

oren add techlite/analyze-commits

Copies the contract and all of its implementations into your project’s .oren/registry/:

✓ techlite/analyze-commits added
      .oren/registry/analyze-commits.task.yaml
      .oren/registry/analyze-commits-alpine.impl.yaml
      .oren/registry/analyze-commits-node.impl.yaml

This contract requires from your environment:
      low                source git-repository

2 implementations — which one?
      1) low                techlite/analyze-commits-alpine
      2) low                techlite/analyze-commits-node

All implementations come together deliberately, and the choice is yours: deciding for you would be choosing privilege on your behalf. When there is more than one, the command lists the cost of each and asks — in CI, use --impl <name>.

It writes the step into your oren.yaml

After the choice, the step is appended to the pipeline:

      - id: analyze-commits
        task: techlite/analyze-commits@^1.0.0
        implementation: techlite/analyze-commits-alpine
        dependencies:
          source: ""

Your file’s comments and formatting are preserved — it is edited, not rewritten. Dependencies come out empty: a disk path is yours, not Oren’s. oren validate points at what is left to fill in.

Use --no-step to only register the task, or --pipeline <name> when the file has more than one pipeline.

What it tells you before you use it

What the task requires from your environment, with the privilege of each dependency. That is the information you want before writing the step, not when the pipeline asks for authorisation.

Whether the task acts on the world. Tasks with effects: external — publishing, deploying, creating a remote tag — get a warning.

Whether the implementation builds from a local directory. In that case it only works while that path exists on your machine, and cannot go to CI.

The two sources

A published reference — namespace/name, with an optional range:

oren add techlite/version-bump
oren add techlite/version-bump@^1.0.0

A directory on disk — the path for whoever writes workers, whose implementation still has build pointing at a local Dockerfile:

oren add ../workers/version-bump

There is no prefix to tell them apart: anything the filesystem understands (starting with ., /, ~) is a path; the rest is a reference.

A published reference needs a registry configured; a directory needs nothing. See The portal.

Why a local registry exists

oren.yaml references tasks by name and version, not by path:

task: techlite/analyze-commits@^1.0.0
implementation: techlite/analyze-commits-alpine

That is what makes the pipeline portable — a disk path would not survive another machine, let alone a CI runner. The registry is what resolves that name to the actual contract.

For a published task, the local registry is a cache: oren install fetches what is missing, so deleting .oren/registry/ and running it again rebuilds it, like node_modules.

For a local task — one that came from a directory, whose implementation points at a Dockerfile on your machine — it is the SOURCE. That one does not exist published anywhere, so it must be committed.

Updating

oren add overwrites whatever is in the local registry. To update a task, run it again pointing at the new version, then:

oren install     # pins the new digests

If the new version asks for more privilege, Oren asks again on the next run — the previous authorisation is not inherited.

Publishing

Whoever writes workers publishes with oren publish, after authenticating once with oren login. Both are covered in The portal, together with organisations, roles and what a published version can never stop being.