Convey is a pipeline for running containers and protecting the host as much as possible.
It does this by creating a volume and making it available to each item in the pipeline.
Convey is build around a concept that I call a build container. A build container is a container that has all of the dependencies to turn an input into something else. This could be source code or even just data processing. For example the
`convey/go-build` image is a simple wrapper around the
`golang` image that just builds a project instead of installing it.
Convey is built around this concept to allow you to build/process anything on any platform while at the same time protecting the host from a malicious config. This protection is provided by not exposing dangerous options like volume mounts or port forwards while running containers. This is accomplished by creating a volume a data volume at the start of the build plan and volume mounting it into containers as they are run. This allows you to pass state between modular tasks that can be reused between multiple plans.
Once built, convey can build itself entirely. This is done by using an import task to copy the source code into the workspace. Once that stage is complete, it runs another stage that builds for linux-x86_64, windows-x86_64, and darwin-x86_64 in parallel. The final stage will take those compiled binaries and export them back to the hosts file system.
Of course you don't have to export back to the host file system. Since these are just containers, you could instead upload them to your staging environment, packagecloud.io, bintray.com, whatever. Of you could export to the host and create another plan that will import the artifacts and then publish them.
usage: convey [<flags>] [<plan>]
--help Show context-sensitive help (also try --help-long and --help-man).
-f, --config=convey.yml The config file name to use
-e, --env=ENV ... Set environment variables
-v, --verbose Be more verbose
-S, --force-sequential Don't run anything concurrently
--color Enable colorized output
-g, --graphviz Output a graphviz diagram of the config file
-L, --list-tasks List the supported tasks
[<plan>...] The plan or list of plans to run in specified order
There are a handful of examples in the [
examples/](
examples/) directory.
This example shows how the always stage attribute works and how it can be used to run a stage to report a build status, run clean up, or whatever.
This example shows how to use the convey/bitbucket-upload image to upload files to a Bitbucket repository's downloads section.
This example shows how environment substitution works in your config file.
This example shows how environment substitution overriding works and uses a -override.yml file as well.
This example shows how to use the script attribute of a run task.
Configuration is done via a file named
`convey.yaml`. This file defines the tasks as well as the plans. There are three top level-items: environment, plans, and tasks.
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 that you can use by setting the
`type` attribute. However if the
`type` attribute is not set, it default to
`run`.
A build task will build a docker image.
| Name | Required | Default | Description |
| ---------- | -------- | ------- | ----------- |
| dockerfile | Yes | | The dockerfile to use while building |
| files | | | A list of files that should be made available for the build |
| tag | Yes | | The tag to apply to the image |
A clean task will remove files from the host relative and limited to the working directory of convey.
| Name | Required | Default | Description |
| --------- | -------- | ------- | ----------- |
| files | Yes | | A list of filenames relative to the convey working directory to remove. |
An export task copies files from the volume to the host.
| Name | Required | Default | Description |
| ----- | -------- | ------- | ----------- |
| files | Yes | | A list of files to copy from the workspace to the host. Files can be specified in one of two forms which can be mixed. The first is
`source:destination` and the other is
`filename` where filename will be used for both the host and the volume. |
- binary:binary-linux-x86_64
An import task copies files from the host to the volume. It has one required attribute named sources. This is a list of files relative to the directory that convey was run from that will be copied into the volume.
| Name | Required | Default | Description |
| ----- | -------- | ------- | ----------- |
| files | Yes | | A list of files to copy from the host to the workspace. Files can be specified in one of two forms which can be mixed. The first is
`source:destination` and the other is
`filename` where filename will be used for both the host and the volume. |
A login task will run docker login to login to a registry.
| Name | Required | Default | Description |
| -------- | -------- | ------- | ----------- |
| username | Yes | | The username to login with. |
| password | Yes | | The password to login with. |
| server | | | The server to login to. If omitted docker hub is used. |
A logout task will log you out from a Docker registry.
| Name | Required | Default | Description |
| ------ | -------- | ------- | ----------- |
| server | | | The server to logout from. If omitted docker hub is used. |
server: registry.my.domain:5000
A pull task pulls an image.
| Name | Required | Default | Description |
| ------ | -------- | ------- | ----------- |
| image | | | The name including the tag and registry of the image to pull. |
| images | | | A list of images as described above. |
At least one image must be supplied by either the
`image` or
`images` attribute. If both are
supplied,
`image` is inserted to the front of
`images`.
image: gliderlabs/alpine:edge
A push task pushes an image.
| Name | Required | Default | Description |
| ------ | -------- | ------- | ----------- |
| image | | | The name including the tag and registry of the image to push. |
| images | | | A list of images as described above. |
At least one image must be supplied by either the
`image` or
`images` attribute. If both are
supplied,
`image` is inserted to the front of
`images`.
- registry.my.domain:5000/newimage:master-latest
- registry.my.domain:5000/newimage:master-deadbeef
A remove task removes an image.
| Name | Required | Default | Description |
| ------ | -------- | ------- | ----------- |
| image | | | The name including the tag and registry of the image to remove. |
| images | | | A list of images as described above. |
At least one image must be supplied by either the
`image` or
`images` attribute. If both are
supplied,
`image` is inserted to the front of
`images`.
- registry.my.domain:5000/newimage:master-latest
- registry.my.domain:5000/newimage:master-deadbeef
A run task runs an image.
| Name | Required | Default | Description |
| ----------- | -------- | ---------- | ----------- |
| command | | | The command to run in the container. This is only necessary if the image does not provide a command by default. |
| entrypoint | | | The entrypoint to use for the container. This is only necessary if the image does not provide one by default. |
| 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. |
| image | Yes | | The image including the registry and tag to run. |
| workdir | | | The working directory to use in the container. |
| workspace | | /workspace | The path inside the container to mount the workspace volume. |
A tag task will tag an existing image.
| Name | Required | Default | Description |
| ----------- | -------- | ---------- | ----------- |
| source | | | The source image, including registry and tag, to tag. |
| destination | | | The destination tag, including registry and tag, to tag. |
source: registry.my.domain:5000/newimage:latest
destination: registry.my.domain:5000/newimage:development
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.
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 a
`stages` with an optional
`environment`.
| 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. |
Stages group
`tasks` together into a logical unit. They can be run sequentially or concurrently.
| Name | Required | Default | Description |
| ----------- | -------- | ------- | ----------- |
| always | | false | Whether or not this stage should be run if a previous stage has failed. |
| 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.
| 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. |
