Configuration

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.

Environment

The environment section defines a list of environment variables to set for the run.

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 available.

Example

environment:
  - BUILD=development
  - SECRET_TOKEN

Stacking

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 config-file, plan, stage, task, and command line levels. They are merged in that order, with the last one taking precedence over the previous.

Examples

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

environment:
  - FOO=bar
tasks:
  env1:
    type: podman/run
    image: docker.io/alpine:edge
    environment:
      - FOO=baz
  env2:
    type: podman/run
    image: docker.io/alpine:Edge
plans:
  default:
    stages:
      - tasks:
          - env1
          - env2

In the next example, the stage is overriding the config-file value. So env1 still has a value of baz for the environment variable FOO, while env2 has a value of qux.

environment:
  - FOO=bar
tasks:
  env1:
    type: podman/run
    image: docker.io/alpine:edge
    environment:
      - FOO=baz
  env2:
    type: podman/run
    image: docker.io/alpine:Edge
plans:
  default:
    stages:
      - environment:
        - FOO=qux
        tasks:
          - env1
          - env2

---

Plans

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.

Example

plans:
  plan1:
    ...
  plan2:
    ...

---

Plan

Plans themselves are pretty straight forward. They group stages with an optional environment.

Attributes

Name	Required	Description
environment		A list of environment variables to set. They 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 config-file level or a meta-plan that contains this plan.
stages	Yes	A list of stages to be run as part of this plan in the order that they should be run in.

---

Stages

Stages group tasks together into a logical unit. They can be run sequentially or concurrently.

Attributes

Name	Required	Default	Description
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		the index of the stage	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.
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. If you are just specifying a single task, you can just pass its name as a single value (not as a list).

---

Meta Plans

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.

Meta plans contain a single attribute which is the list of plans to run.

Attributes

Name	Required	Description
environment		A list of environment variables to set. They 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 config-file level.
plans	Yes	A list of plans to run in the order they should be run in.

Example

meta-plans:
  world:
    environment:
      - BUILD_TYPE=production
    plans:
      - plan1
      - plan2
      - plan3

Tasks

The documentation for the available task types can be found below:

• Convey
• Docker (deprecated)
• Podman
• Script