YAML migrations using yq and selector syntax/operators. It can simplify DevOps administration of CI files written in YAML.
- Need to upgrade hundreds of CircleCI configs with complex logic? - Get yizzy.
- Want apply multiple changes consistently to all GitHub Workflows on your machine? - Get yizzy.
- Prefer awk/sed and bash scripting? - Don't get yizzy.
Latest binary releases are available via GitHub Releases.
If you prefer homebrew, I got you.
brew install jimschubert/tap/yizzy
or:
brew tap jimschubert/tap
brew install yizzy
$ yizzy -h
Usage:
yizzy [OPTIONS]
Application Options:
-f, --file=FILE The file to process
-d, --dir= The directory where migrations reside
--in-place Writes a file in place
-v, --version Display version information
Help Options:
-h, --help Show this help message
A migration document holds the list of operations and environments we intend to apply to a target file. The document applies one or more expressions as supported by yq against a YAML document.
An operation consists of:
value_type
: an optional, defining the YAML type which will be applied byvalue
oreval
value
: a scalar or literal value which does not require document traversal or evaluationeval
: an expression requiring traversal or yq operations evaluated in the context defined byselector
(or the document root by default)selector
: a yq expression targeting one or more nodes on which to operate contextually when applying thevalue
oreval
result
The env
node is a simple map of keys representing the environment variable to be set during evaluation of each operation,
and an expression to apply whenever that environment variable is referenced via yq's env variable operators.
NOTE A literal reference defined within the YAML document must result in an expression wrapped in quotes. In YAML, this will be the following syntax:
LITERAL_ENV: '"Jim Schubert"'
This creates an expression of "Jim Schubert"
. One set of single/double quotes would result in an unquoted expression Jim Schubert
,
which would cause a parser error in yq.
Create a directory called migrations
, and create a dated YAML file within this directory. For example: 2021-03-05.yml
:
env:
FIRST_NAME: .bill-to.given
LAST_NAME: .bill-to.family
operations:
- selector: .ship-to
eval: '.full_name = strenv(FIRST_NAME) + " " + strenv(LAST_NAME)'
value_type: '!!str'
A migration document contains an optional map named env
, a key/value mapping of environment variable names which will
be passed to each operation, and a selector evaluated against the input document prior to operations. These operations are
applied in declaration order.
See testdata for examples of migrations and their expectations once applied to the YAML 1.2 specification's invoice.yaml
.
Build a local distribution for evaluation using latest goreleaser.
goreleaser release --skip-publish --snapshot --rm-dist
This will create an executable application for your os/architecture under dist
:
dist
├── yizzy_darwin_amd64
│ └── yizzy
├── yizzy_linux_386
│ └── yizzy
├── yizzy_linux_amd64
│ └── yizzy
├── yizzy_linux_arm64
│ └── yizzy
├── yizzy_linux_arm_6
│ └── yizzy
└── yizzy_windows_amd64
└── yizzy.exe
Build and execute locally:
- Get dependencies
go get -d ./...
- Build
go build -o yizzy cmd/main.go
- Run
./yizzy --help
- Install golangci-lint.
- Run it:
golangci-lint run ./...
This project is licensed under Apache 2.0.