Scaffold a CI-wired project with the starter template

Starting a new automation project usually means copying a half-remembered Makefile from the last repo, then spending an afternoon re-wiring CI. OrchStep gives you two faster paths: orchstep init for a single runnable file, and the orchstep-starter GitHub template for a complete, CI-wired project you fork in one click.

orchstep init: one command, a runnable file

init scaffolds a real workflow — not an empty stub — with three templates to pick from:

orchstep init --list

Available templates:
  minimal  Hello-world starter with a verified assert (default)
  env      Environment-aware workflow (env_groups + environments, run with --env)
  ci       Build/test/package pipeline passing outputs between steps

The ci template is the interesting one — it scaffolds a build/test/package pipeline that actually passes data between steps:

orchstep init -t ci

Created orchstep.yml (template: ci)

Next steps:
  orchstep run ci                    # run the starter task
  orchstep menu                      # interactive task picker
  orchstep lint                      # check for anti-patterns

What you get is immediately runnable and lints clean — outputs flow from build into test and an assert gates on the result:

name: ci-pipeline
desc: Build, test and package - outputs flow from step to step
defaults:
  version: "0.1.0"
tasks:
  ci:
    steps:
      - name: build
        func: shell
        do: 'echo "built my-app:{{ vars.version }}"'
        outputs:
          artifact: '{{ result.output | regexFind "my-app:[0-9.]+" }}'
      - name: test
        func: shell
        do: |
          echo "testing {{ steps.build.artifact }}"
          echo "2 passed, 0 failed"
      - name: check_tests
        func: assert
        args:
          condition: '{{ steps.test.output | contains "0 failed" }}'
      - name: package
        func: shell
        do: 'echo "packaging {{ steps.build.artifact }}"'

Replace the echo lines with your real commands and you have a working pipeline. That is the whole loop: scaffold, swap in commands, run.

The starter template: a full project, CI included

For a real repo, the orchstep-starter template goes further: a top-level pipeline, auto-discovered task files, and a GitHub Actions workflow already wired. Click Use this template, install the CLI, and run.

name: starter
desc: A starter OrchStep project - build, test, and deploy
defaults:
  app_name: "my-app"
  version: "0.1.0"
  environment: "staging"

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

Run it locally

The top-level steps: are the default main pipeline; the tasks/ files are discovered automatically:

orchstep run

Discovered 3 task file(s) from tasks/ directory
Workflow: starter
Task: main
  Step: build
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
  Step: test
...
Result: success

orchstep list-tasks shows build, deploy, main (default), and test. Run any directly, or override variables — the same command CI runs:

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, in one action

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

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

Every push lints the workflow and runs the main pipeline; a manual Deploy job (Actions tab → Run workflow) runs the deploy task with production variables. The exact same orchstep run you use locally is what runs in CI — no second config to drift.

What you gained

The honest boundary

The starter scaffolds structure, not your build. Every task ships with echo placeholders precisely so it runs anywhere out of the box — the real work is swapping in your go build, npm test, or kubectl apply. And mind one YAML gotcha the template calls out: a do: value with a bare colon-space (do: echo "tests: ok") is read by YAML as a mapping — quote it or avoid the colon.

Where to go next

• Starter Template — the template repo, file by file
• CLI Reference — init, run, list-tasks, and every flag
• OrchStep in CI — the run-orchstep action's full input reference

Spinning up a new repo this week? orchstep init -t ci gets you a runnable pipeline before your coffee is cold.