Modules Overview

Reusable, versioned workflow components distributed over Git

A module is a packaged, versioned collection of OrchStep tasks distributed via Git. Instead of copying the same deploy, notification, or validation steps into every project, you package them once and import them by name and version.

modules:
  - name: greeter
    source: "github.com/orchstep/test-module-single"
    version: "^1.0.0"

tasks:
  main:
    steps:
      - name: hi
        module: greeter        # call a task exported by the module
        task: hello
        with:
          name: "OrchStep"

Anatomy of a module

Every module is a directory with two required files:

my-module/
├── orchstep-module.yml    # manifest: metadata, permissions, config schema, exports
├── orchstep.yml           # the tasks themselves
└── README.md              # optional

orchstep-module.yml — declares the module's identity (metadata:), what it's allowed to do (permissions:), the config it accepts (config.schema:), and the tasks it exposes (exports:).
orchstep.yml — a normal OrchStep workflow whose tasks: implement the exported tasks.

See Creating Modules for the full manifest format.

Three ways to source a module

OrchStep resolves a module from its source:, fetches it into a local cache, and makes its exported tasks callable. There are three source forms:

Source form	Example	Repo layout	Tag format
Built-in scope	`@orchstep/<name>`, `@community/<name>`, `@ai/<name>`	`modules/@<scope>/<name>/` in the OrchStep registry repo	`<name>/vX.Y.Z`
Full Git URL (single-module repo)	`github.com/org/repo`	module files at the repo root	`vX.Y.Z`
Custom registry (your own monorepo)	`@yourscope/<name>` + a `registries:` block	`modules/@<scope>/<name>/`	`<name>/vX.Y.Z`

All three are covered in detail — with runnable examples — in Using Modules.

# Built-in official/community/ai scope (no config needed)
modules:
  - name: clone
    source: "@community/github_action_git-checkout"
    version: "^1.0.0"

# A single-module repo (the whole repo is the module)
modules:
  - name: greeter
    source: "github.com/orchstep/test-module-single"
    version: "^1.0.0"

# Your own monorepo hosting several modules under one scope
registries:
  mycompany:
    url: github.com/orchstep/monorepo-multi-modules
modules:
  - name: greet
    source: "@mycompany/module1"
    version: "^1.0.0"

Registry tiers

The built-in scopes correspond to three trust tiers, all hosted in the public OrchStep registry repo (github.com/orchstep/orchstep) under modules/@<scope>/<name>/:

Scope	Tier	Maintained by	Published via
`@orchstep`	Official	The OrchStep team	Direct push
`@community`	Verified	Human contributors	PR → review → merge
`@ai`	AI-generated	LLM agents	`orchstep module submit`

See Registry & Scopes for how the tiers and custom registries resolve.

Versioning

Modules are versioned by git tags and selected with semver constraints:

Constraint	Matches
`1.2.3`	exactly 1.2.3
`^1.2.0`	`>=1.2.0 <2.0.0` (latest compatible 1.x)
`~1.2.0`	`>=1.2.0 <1.3.0` (patch updates only)
`>=1.2.0`	1.2.0 or higher
`*`	the highest available version

Pin exact resolutions for reproducible builds with orchstep module lock.

A note on private repositories

Module fetching currently uses anonymous Git access — there is no token or SSH-key auth wired into the resolver yet, so modules in private repos can't be fetched through @scope or github.com/... sources. Use public repos for shared modules, or the Pro @private/ scope (a local private registry populated with orchstep module publish) for internal modules.

Next steps

Using Modules — import, install, version, and call modules (with runnable examples)
Creating Modules — author and publish your own
Registry & Scopes — how scopes, tiers, and custom registries resolve

< prompt Using Modules >