First pipeline

The path for whoever is going to use tasks — the common case. If you are writing a new task, see Creating tasks.

mkdir my-project && cd my-project
oren init

✓ project created
      oren.yaml
      .gitignore
      .oren/registry/

That is all: an empty pipeline and a place for tasks to live. No code, no Dockerfile — the work comes from outside.

Bring in a task

oren add techlite/analyze-commits

✓ 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

Notice that it shows what the task will ask for before you use it, and brings in every available implementation — choosing for you would be deciding privilege on your behalf.

Where the task comes from

A published reference (namespace/name) needs a registry configured — see The portal. A directory path works with no registry at all: oren add ../workers/analyze-commits. That is how a worker is used before it is published.

Write the step

oren.yaml

apiVersion: oren.sh/v1
kind: Pipeline
pipelines:
  dev:
    steps:
      - id: analyse
        task: techlite/analyze-commits@^1.0.0
        implementation: techlite/analyze-commits-alpine
        inputs:
          defaultChange: minor
        dependencies:
          source: "."

oren add writes that step for you, preserving the file’s comments. The dependencies come out empty — the paths are yours.

Run it

oren run dev

[1/1] analyse · analyze-commits
      │ analysing commits since v1.0.0
      │ 1 commits analysed
      │ classification: patch
      ✓ 3.7s

Reading the output

│ analysing commits... — what the worker printed. stdout and stderr are free for logging; they carry no data: what a step produces is the output JSON, validated against the contract. Output outside the declared format fails the step even with exit code zero.

Seeing input and output

They do not show by default — in a real pipeline they fill the screen with JSON nobody reads. Use -v:

oren run dev -v

      input {"defaultChange":"minor","tagPattern":"v[0-9]*.[0-9]*.[0-9]*"}
      output {"change":"patch","major":false,"minor":false,"patch":true,...}

tagPattern appears without being in the pipeline: it came from the default declared in the contract.

Nothing is lost without the flag. Both are kept under .oren/runs/<id>/steps/<step>/, and the input of the step that fails is printed alongside the error — which is when it stops being noise and becomes the first thing you look at.

Pin the versions

oren install

Writes oren.lock with the exact digest of every image. Commit it — it is what makes everyone run the same code. See Reproducibility.

Check without running

oren validate

Resolves contracts and implementations, checks dependencies and validates the literal inputs — without starting a single container. Takes about a second, and is what you want in a commit hook.