ops.yml Reference Manual

This is the configuration reference for ops.yml files. On this page, you will find a description of the structure of a typical ops.yml file, as well as the meaning of each configuration option that you can specify in that file.

Default values are used for all options that are omitted from an ops.yml file.

Quick Reference

If you are new to the CTO.ai platform, you can skip ahead to the next section on this page. If you already have experience writing ops.yml files to define CTO.ai workflows, you might find the condensed reference YAML file below useful.

The file in the following code box documents the structure of an ops.yml file and every (non-legacy) key that may be present, as well as very brief description of the expected value for each key. Deeper explanations of every element can be found in the following sections of this page.

version: str

commands:
  - name: <name (str)>:<version (semver)> #required
  	description: str #required
    run: (str) shell command to run as container entrypoint #required
    env: #optional
      static: [ KEY=value, ... ]
      configs: [ KEY, ... ]
      secrets: [ KEY, ... ]
    help: #optional
      usage: string describing usage of this workflow via CLI
      arguments: #optional mapping of sub-commands
      	<arg_name>: description of <arg_name>
  - ... # optionally, define multiple Commands workflows

pipelines:
  - name: <name (str)>:<version (semver)> #required
  	description: string #required
    jobs:	#required
      - name: string_name:semver_version
      	description: str #required
        packages: [ <package_name>, ... ]
        steps:
          - single-line shell command
          - ...
      - ... #optionally, define multiple jobs
    env: #optional
      static: [ KEY=value, ... ]
      configs: [ KEY, ... ]
      secrets: [ KEY, ... ]
    events: #optional
      - "<origin_service>:<origin_repo>:<event_name>"
      - ... #optionally, define multiple events that should trigger this workflow
  - ... #optionally, define multiple pipelines

services:
  - name: <name (str)>:<version (semver)> #required
  	description: str #required
    run: (str) shell command to run as container entrypoint #required
    env: #optional
      static: [ KEY=value, ... ]
      configs: [ KEY, ... ]
      secrets: [ KEY, ... ]
    events: #optional
      - "<origin_service>:<origin_repo>:<event_name>"
      - ... #optionally, define multiple events that should trigger this workflow
    port: [ '<external_port>:<container_port>' ] #optional
    domain: fully-qualified domain name #optional
    trigger: #optional, accepted values are listed here
      - build
      - publish
      - start
  - ... # optionally, define multiple Services workflows

# If you are having trouble interpreting the definition above, it might be
# helpful to know that the two YAML documents below (separated by ---)
# are semantically identical to each other. Additionally, it is helpful
# to think of YAML syntax as a *superset* of JSON syntax.

keyA:
  keyB: value1
  keyC:
    - value2
    - value3
  keyD:
    - subkeyX: value4
      subkeyY:
        - value5
        - value6
---
keyA: { keyB: value1, keyC: [value2, "value3"], keyD: [{subkeyX: value4, subkeyY: [value5, value6]}] }

ops.yml Top-Level Keys

version: "1"
commands: # array of Commands workflow definitions
pipelines: # array of Pipelines workflow definitions
services: # array of Services workflow definitions

The following keys exist at the top level of the YAML file’s hierarchy.

version (required)

The syntax version of this ops.yml file itself. This is not the workflow’s version number.

commands

Array of YAML objects defining one or more individual Commands workflows.

pipelines

Array of YAML objects defining one or more individual Pipelines workflows.

services

Array of YAML objects defining one or more individual Services workflows.

Common Workflow Config

The configuration options shown in the box below are applicable to all three kinds of workflows offered by the CTO.ai platform: Commands, Pipelines, and Services.

{commands,pipelines,services}:
	- name:		  		# string to uniquely identify the workflow and its version
    description: 	# string describing the purpose of the workflow
    env:					# mapping of environment variable arrays
    	static:			# array of strings specifying static environment variables
      secrets:		# array of strings specifying which Secrets values to make available
      configs:		# array of strings specifying which Configs values to make available
    events: 			# array of strings specifying the events that trigger this workflow

name (required)

String uniquely identifying the workflow and its version. This setting is required.

The user-friendly name for a workflow and the workflow’s version should be separated by a colon (:). This value will be used to tag the container image built to run this workflow.

description (required)

String describing the intended purpose or usage of this workflow. This setting is required.

env

A mapping with three valid keys: static, secrets, and configs. Each of these keys can have under it an array of one or more strings specifying the environment variables to pass to the workflow.

For a detailed explanation of how this feature can be used, have a look at the Configuring Workflow Behavior with Environment Variables section on our ops.yml Overview page.

static

Array of strings defining environment variables to pass to the workflow’s runtime environment.

secrets

Array of strings specifying which keys from the team’s Secrets Store should have their value made available as environment variables in the workflow’s runtime environment. If a specified value doesn’t exist in the Secrets Store, the environment variable will be set with an empty string as its value.

configs

Array of strings specifying which keys from the team’s Configs Store should have their value made available as environment variables in the workflow’s runtime environment. If a specified value doesn’t exist in the Configs Store, the environment variable will be set with an empty string as its value.

events

Array of strings defining the events that should trigger this workflow to run. This setting is optional.

Self-Contained Workflow Config

The following configuration options are applicable to definitions for the two kinds of workflows offered by the CTO.ai platform that can be described as self-contained: Commands and Services.

{commands,services}:
	- # # #			# see above for the `name` option and other settings shared between types
		run:			# string containing shell command to run

run (required)

String containing the shell command to execute in the workflow container to initiate the workflow. This setting is required.

This value will be used as the ENTRYPOINT of the container image built for this workflow.

Services-Only Config

The configuration options in this section are applicable to definitions of Services workflows only.

services:
	- # # #			# see above for common options available to this workflow type
  	port:			# definition of the port used by your Service
    domain:		# string specifying the hostname pointed to this Service

port

The port used to access the application deployed by the Services workflow.

domain

The domain name optionally configured to serve the application deployed by the Services workflow, via CNAME records.

trigger

Array of strings defining which operations to perform on your Services workflow when an event occurs. Valid values are build, publish, and start.

Jobs Config

This section is applicable to the jobs defined by Pipelines workflows.

pipelines:
	- # # #			# see above for common options available to this workflow type
  	jobs:			#
    	-	name:					#
      	description:	#
        packages:			#
        steps:				#

Setting them apart from the other workflow types offered by the CTO.ai platform, Services workflows include their application logic in one or more Jobs that are executed in sequence.

jobs (required)

Array of one or more mappings that define the individual Jobs to be executed.

Many of these fields are identical to the expected fields for other types of individual workflows, including the name and description fields. The other fields that can be used to define a Job are described below.

packages

Array of package names to be installed by the system package manager.

steps

Array of strings defining the sequence of shell commands to execute within the Job’s runtime container.

Local Development Config

This section is only applicable to workflows running on your local machine, not running remotely on the CTO.ai platform. The configuration options described in this section are provided to help you more easily develop your workflows locally.

mountCwd (local-only)

Boolean value (default: false) that, if set to true, will bind the host’s current working directory to the /cwd path within the running workflow container.

mountHome (local-only)

Boolean value (default: false) that, if set to true, will bind the host’s home directory to the /root path within the running workflow container.

Legacy Config

public

Boolean value specifying whether a workflow should be made visible in our Public Registry. Defaults to false.

sourceCodeURL

Legacy setting that allows you to specify a link to a public GitHub repo or Markdown file, which will be used as the README for your workflow on our Public Registry.

remote

Boolean value specifying whether a workflow is allowed to run remotely (remote: true) or if it may only be run locally (remote: false). Defaults to true.

sdk

Legacy value specifying the version of the CTO.ai SDK to use. Defaults to 2. This option is deprecated.