Configuring convey is done via a file named
`convey.yml`. This file defines
the tasks as well as the plans. This document explains how that file is
structured and what options are available.
There are a handful of examples in the [
examples/](
examples/) directory with a
README.md that describes which each is showing.
The complete reference for convey.yml can be found below.
The
`required-version` field lets you specify a required version of convey
to run your
`convey.yml`. Ranges are supported according to the semantics
defined [
here](
https://github.com/blang/semver#ranges). If a
`required_version` is not specified, convey will always attempt to run the
The options section lets you fine tune a few things about your configuration.
`default-plan` is the name of the plan that should be run by default. When not
set, this defaults to
`default`.
You can specify a list of SSH key fingerprints that are required for your run.
This is done by using the
`ssh-identities` attribute which is a list of SSH
key fingerprints with an option checksum prefix. You can also specify
`*` to
allow any key that's been added to the
`ssh-agent`.
`ssh-identities` are also supported in your override file. However, any
`ssh-identities` specified in your
`convey.yml` will be overridden by the
values in the override file; they will not be merged.
**NOTE** If running on docker4mac, there is an
[
issue](
https://github.com/docker/for-mac/issues/483) with xhyve (the
hypervisor that the Docker daemon runs in) where you can't volume mount the
`ssh-agent` socket. You can use this
[
workaround](
https://hub.docker.com/r/uber/ssh-agent-forward/) to expose the
`ssh-agent` via an alternative method.
- ivZaDYamb5xdguIUUVT7DXvXwvE9JLsOkOkR3XAfzeI
- SHA256:Efrocgd+rvwjDAnHt2jZAcwDqeka0s8Vv7N3m08cVnA
When using
`*` you have to quote it because
`*` treated specially in
`yaml`.
The extends option allows you to define a base configuration file. The filepath
is relative to the current configuration file.
The current file will inherit the options, tasks, and plans of the base
configuration file. If an option is supplied, or a task or plan with the same
name is defined in the current file, it replaces the inherited item.
The tasks section defines each task. By defining them separately from the
plan the tasks can be reused in multiple plans.
There are many tasks types which can be chosen by the value of the
`type`attribute. See the links below for detailed information on each category of
* [
convey](
intrinsic/README.md)
* [
docker](
docker/README.md)
* [
kubectl](
kubectl/README.md)
The environment section defines a list of environment variables to set for the
It should be specified in a
`NAME` or
`NAME=VALUE` format. If no value is
provided, the value of the variable from the host will be provided if it is
Since there are multiple places where environment variables can be set, they
must all be merged together before being passed to a task.
Environment variables can be set at the
`global-base`,
`global`,
`global-override`,
`plan`,
`stage`,
`task`, and command line levels. The are
merged in that order, with the last one taking precedence over the previous.
In the following example, when the
`env1` task is run, the
`FOO` environment
variable will be set to
`baz`, but when the
`env2` task is run, the
`FOO`environment variable will be set to bar
In the next example, the stage is overriding the global value. So
`env1` still
has a value of
`baz` for the environment variable
`FOO`, while
`env2` has a
The plans sections defines your execution plans which tie everything together
by organizing
`tasks` into
`stages` into the order that they will be executed.
Each plan is defined by a name in the plans section.
Plans themselves are pretty straight forward. They group
`stages` with an
| Name | Required | Description |
| ----------- | -------- | ----------- |
| environment | | A list of environment variables to set. The should be specified in a
`NAME` or
`NAME=VALUE` format. If no value is provided, the value of the variable from the host will be provided if it is available. These environment variables will be applied on top of any that were set at the top-level. |
| stages | Yes | A list of
`stages` to be run as part of this
`plan` in the order that they should be run in. |
| merge | | Whether or not to attempt to merge with a plan defined in the parent config file. |
If a plan of the same name exists in a parent config file and merge is not set,
it will replace the plan in its entirety. If merge is set, then the stages
defined in this plan will overwrite stages of the parent plan with the same
name. This behavior also applies to environments. It is an error to attempt to
merge a stage that does not exist in the parent and new stages cannot be added
as their order would not be well defined.
Stages group
`tasks` together into a logical unit. They can be run
sequentially or concurrently.
| Name | Required | Default | Description |
| ----------- | -------- | ------- | ----------- |
| always | | false | (Deprecated, used run instead) Whether or not this stage should be run if a previous stage has failed. |
| enabled | | true | Whether or not to run the stage at all. |
| concurrent | | false | Whether or not the tasks should be run at the same time. |
| environment | | | A list of environment variables to set. The should be specified in a
`NAME` or
`NAME=VALUE` format. If no value is provided, the value of the variable from the host will be provided if it is available. These environment variables will be applied on top of any that were set at the top-level and the plan level. |
| name | | stageN | A name to give the stage.
| run | No | on-success | When a stage should be run. Possible values are
`on-success`,
`on-failure`, or
`always`. Defaults to
`on-success`. |
| tasks | Yes | | A list of task names to be run as part during this stage. If running sequentially they are run in the order that they are provided. |
Meta plans are used to group plans together and run them in serial. This is
also possible via the command line by specifying multiple plans to run.
There is currently no support for nesting meta plans.
Meta plans contain a single attribute which is the list of
`plans` to run.
| Name | Required | Description |
| ----------- | -------- | ----------- |
| plans | Yes | A list of
`plans` to run in the order they should be run in. |
