Skip to content
Using Oya packs containing reusable boilerplate & scripts, you can bootstrap easy to work with, deployable projects
Branch: master
Clone or download
Latest commit c6c3093 May 17, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Install node modules on CI Apr 24, 2019
cmd oya init PROJECT_NAME May 17, 2019
docs Fixed link for Documentation in footer May 10, 2019
features Add project name as oya init argument May 16, 2019
install install script Mar 20, 2019
pkg Add project name as oya init argument May 16, 2019
script Move to Mar 1, 2019
testutil Move to Mar 1, 2019
.gitignore ignore compiled jekyll site May 9, 2019
.go-version Implement `$Task.taskName()` for Oyafiles. Feb 5, 2019
LICENSE Add oya init cli command. Nov 12, 2018
Oyafile Merge branch 'master' into bdymowski/oya-version Apr 24, 2019 update readme doc May 16, 2019 Configure Markdown linter for cleaner documentation Apr 24, 2019
go.mod Fix args reset after invoking `set` (bug in gosh). Apr 8, 2019
go.sum Import install deps May 7, 2019
oya_test.go Propagate exit code. Apr 29, 2019
package-lock.json fix tempaltes May 9, 2019
package.json fix tempaltes May 9, 2019 Remove letfover gherking tags. Jan 31, 2019

layout permalink



Install oya and its dependencies:

$ curl | bash

Initialize project.

$ oya init OyaExample

Define a task you can run:

# ./Oyafile
build: echo "Hello, world"

View tasks

$ oya tasks

Run the task:

$ oya run build
Hello, world

The task in the above example is called "build" but there's nothing special about the name. In fact, a task name is any camel case identifier as long as it starts with a lower-case letter. You can have as many different tasks as you like.


  • Oyafile - is a yaml formatted fileontaining Oya configuration and task definitions.
  • Oya project - is a directory with Oyafile inside and Project: name defined. Project is a set of tasks and files.
  • Oya task - tasks are bash scripts defined in Oyafiles under name like task: |.

Install Oya

$ curl | bash

This will install latest version of oya. It’s also possible to specify which version should be installed

$ curl | bash -s v0.0.7
$ oya --version

Oya Project

You can create Oyafile by hand or with init command.

$ oya init OyaExample
$ cat Oyafile
Project: OyaExample


Oya task is a bash script defined as a Oyafile key. Tasks in Oyafile are defined as a yaml keys, with pipe at the beginning line and bash code in following.

$ cat Oyafile
Project: OyaExample
build: |
  go build app.go
start: |

To list available tasks use tasks command:

$ oya tasks
# in ./Oyafile
oya run build
oya run start

Execute task

$ oya run build
$ oya run start

*.oya files

Inside a project you can have many files with named *.oya they will be read as a Value files, expected syntax is a pair of key: value.

$ cat values.oya
fruit: banana
$ cat Oyafile
Project: OyaExample
eat: |
  echo ${Oya[fruit]}
$ oya run eat


You can also store all values inside Oyafile.

$ cat Oyafile
Project: OyaExample
  fruit: banana
eat: |
  echo ${Oya[fruit]}


You can also store confidential data using Oya secrets. Oya uses SOPS ( to help with secrets management. First you need to configure SOPS for encryption method, check For our example we can use PGP key.

$ export SOPS_PGP_FP="317D 6971 DD80 4501 A6B8  65B9 0F1F D46E 2E8C 7202"

Oya secrets commands:

$ oya secrets --help
  edit        Edit secrets file
  encrypt     Encrypt secrets file
  view        View secrets

First run:

First you need to create secrets.oya file. with key: value in each line. And encrypt it. (You can also go straight to edit with $ oya secrets edit secrets.oya).

$ cat secrets.oya
magical_spell: hokus pokus czary mary
$ oya secrets encrypt secrets.oya

Done your secrets are safe. Check how secrets.oya looks like.

$ cat secrets.oya
        "data": "ENC[AES256_GCM,data:XXXX=,tag:XXXX==,type:str]",
        "sops": {
                "pgp": [...],

We can see only sops metadata, our data are safe and encrypted.

To view or edit use:

$ oya secrets view secrets.oya
magical_spell: hokus pokus czary mary
$ oya secrets edit secrets.oya

You can access secret value with ${Oya[magical_spell]} from task.

$ cat Oyafile
Project: OyaExample
spell: |
  echo ${Oya[magical_spell]}
$ oya run spell
hokus pokus czary mary


Oya can also render a template files or even whole directory. Oya uses Plush templating system You can find out more here

$ cat template/index.html
<h1><%= title %></h1>

Let’s add our title under Value:

$ cat Oyafile
Project: OyaExample

  title: Hello from Oya

Render output into public/ dir so our server can see it.

$ oya render template/index.html
$ cat index.html
<h1>Hello from Oya</h1>

Recursive oya

It’s possible to organize oya project into directories with separated logic.

We can separate it into backend/ and frontend/.

$ tree
├── Oyafile
├── backend
│   ├── Oyafile
└── frontend
    ├── Oyafile

2 directories, 3 files

Each of them will have own Oyafile, and thanks to recursive tasks each file can have task with the same name in our case build.


Here is how our backend Oyafile looks like (note that there is no Project: for subdirectories):

$ cat ./backend/Oyafile
build: |
  echo "Compiling server"
  go build -o ../build/server app.go


$ cat ./frontend/Oyafile
  title: Hello from Oya
build: |
  echo "Rednering template"
  oya render template/index.html -o ../build/public

Our frontend holds only template file and Values necessary to render it.

Project Oyafile

$ cat Oyafile
Project: OyaExample
build: |
  echo "Preparing build/ folder"
  rm -rf build/ && mkdir -p build/public

Recursive run

Now let’s see what tasks we have. To do it for whole project including subdirectories we need to use -r or --recurse flag.

$ oya tasks -r
# in ./Oyafile
oya run build

# in ./backend/Oyafile
oya run build

# in ./frontend/Oyafile
oya run build

As you can see we have three build tasks one per Oyafile. We can now run them all.

$ oya run -r build
Preparing build/ folder
Compiling server
Rendering template.html

And now we can start the app with $ oya run start.


Pack is a Oya project with general purpose tasks which can be easily shared and used inside other projects. Oya installs pack in your home ~/.oya directory. Each time you rune oya command dependencies will be resolved and installed.

$ oya import
$ cat Oyafile
Project: OyaExample
Require: v0.0.6

Import will add importing pack under Import:, key of imported pack is his alias and can be accessed by this name, (you can change it if needed).

Packs versioning

Import will automatically resolve dependencies with newest versions and add them under Require:.

Imported pack added bunch of new commands into our project

$ oya tasks
# in ./Oyafile
oya run build
oya run
oya run docker.generate
oya run
oya run docker.stop
oya run docker.version
oya run start

We can easily generate Dockerfile, update it, and build our project.

Pack development - sharing oya’s

Each oya project is a pack itself, all you need to do is push it to git and tag it version name/v0.0.1. Import it as before with $ oya import oya should automatically resolve newest version and add Require to your Oyafile.

Tests PGP keys

To have all tests passing successfull it's require to have our pgp key for secrets

$ gpg --import testutil/pgp/private.rsa


  1. Install go 1.11 (goenv is recommended, example: goenv install 1.11.4).
  2. Checkout oya outside GOHOME.
  3. Install godog: go get -u
  4. Run acceptance tests: godog.
  5. Run tests: go test ./....
  6. Run Oya: go run oya.go.
You can’t perform that action at this time.