Starter Template

The fastest way to start a real project is the orchstep-starter template repository. It is a complete, runs-out-of-the-box OrchStep project: a workflow, auto-discovered task files, and GitHub Actions CI already wired up. Click one button, replace the placeholder commands with your own, and you have a working pipeline - locally and in CI.

Use the template

1. Open orchstep/orchstep-starter and click Use this template -> Create a new repository.
2. Install the CLI:

   curl -fsSL https://orchstep.dev/install.sh | sh

   COPY
3. Run the pipeline:

   orchstep run

   COPY
4. Push - the included workflow lints, builds, and tests on every commit.

What you get

A small, idiomatic project that demonstrates the patterns you will actually use - defaults:, a top-level main pipeline, task files, and CI via the official action. Click through it:

name: starter
desc: A starter OrchStep project - build, test, and deploy

# Definition variables. Override any of them with --var key=value.
defaults:
  app_name: "my-app"
  version: "0.1.0"
  environment: "staging"

# Top-level steps are the default "main" pipeline that ties the
# discovered tasks together.
steps:
  - name: build
    task: build
  - name: test
    task: test

Run it locally

orchstep run

Discovered 3 task file(s) from tasks/ directory
Task: main
Task: build
  $ echo "building my-app v0.1.0"
building my-app v0.1.0
  $ echo "artifact my-app-0.1.0 is ready"
artifact my-app-0.1.0 is ready
Task: test
  $ echo "running tests for my-app"
running tests for my-app
Result: success

orchstep list-tasks shows build, deploy, main (default), and test. Run any of them directly, or override variables:

orchstep run deploy --var environment=production --var version=1.2.3

  $ echo "deploying my-app v1.2.3 to production"
deploying my-app v1.2.3 to production
Result: success

The CI, explained

The workflow uses the official orchstep/run-orchstep action, which installs the CLI and runs your workflow in a single step - no separate setup needed:

- uses: actions/checkout@v4
- uses: orchstep/run-orchstep@v1
  with:
    workflow: orchstep.yml   # no task runs the main build + test pipeline

On every push it lints the workflow and runs the main pipeline. A manual Deploy job (Actions tab -> Run workflow) runs the deploy task with production variables. See OrchStep in CI for the full action input reference.

Make it yours

• Real commands: replace each echo ... in tasks/*.yml with your build, test, and deploy commands.
• Add a task: drop a new tasks/<name>.yml file - it is callable instantly.
• Watch the colon: a do: value with a bare colon-space (do: echo "tests: ok") is read by YAML as a mapping and the file is skipped. Quote it or avoid the colon.
• env is reserved: it is the environment-variable namespace, so this template uses environment for the deploy target.

Where to go next

• Task Files - the tasks/ directory in depth.
• CLI Reference - every orchstep command and flag.
• OrchStep in CI - the action's full input reference.