Modules Overview

A module is a packaged, versioned collection of OrchStep tasks distributed via Git. Modules let teams share deployment patterns, operational runbooks, and infrastructure automation.

What is a Module?

Modules are reusable workflow packages that encapsulate common automation patterns. Instead of writing the same deployment, notification, or testing steps in every project, you package them once as a module and share them across your organization.

Module Structure

my-module/
  orchstep-module.yml    # Module metadata and configuration
  orchstep.yml           # Module workflow (tasks and steps)
  README.md              # Documentation (optional)

Module Tiers

OrchStep modules are organized into three tiers:

@orchstep (Official)

Maintained by the OrchStep team. These modules follow strict quality standards, have comprehensive tests, and are guaranteed to work with the latest OrchStep version.

@community

Created and maintained by the community. These modules are reviewed for basic quality and safety but are maintained by their authors.

@ai

Generated by AI agents. These modules are scaffolded from natural language descriptions and may need refinement before production use.

Using Modules

Install a Module

orchstep module install github.com/your-org/ci-cd-module@v1.2.0

Search the Registry

orchstep module search ci-cd

List Installed Modules

orchstep module list

Reference in Your Workflow

name: my-app-pipeline

modules:
  - name: ci-cd
    version: "^1.2.0"
    source: "github.com/your-org/ci-cd-module"
    config:
      registry_url: "registry.example.com"
      app_name: "my-app"
      replicas: 3

Module Definition

The orchstep-module.yml file defines module metadata and the configuration schema:

name: ci-cd
version: "1.2.0"
description: "CI/CD pipeline module with build, test, and deploy tasks"
author: "your-org"
license: "MIT"

config:
  required:
    - name: registry_url
      type: string
      description: "Docker registry URL"
    - name: app_name
      type: string
      description: "Application name"
  optional:
    - name: replicas
      type: integer
      default: 2
      description: "Number of deployment replicas"

exports:
  tasks:
    - build
    - test
    - deploy
    - rollback

dependencies:
  - name: docker-utils
    version: "^1.0.0"
    source: "github.com/orchstep-modules/docker-utils"

Versioning

Modules use semantic versioning (semver):

Version Constraint	Meaning
1.2.3	Exact version
^1.2.0	Compatible with 1.x.x (major locked)
~1.2.0	Compatible with 1.2.x (minor locked)
>=1.2.0	Minimum version

Next Steps

• Creating Modules — How to build and publish your own modules
• Module Registry — Search and install modules from the registry