Building and Using Workflows

This page provides an explanation of how Commands, Pipelines, and Services workflows are built as container images encapsulating your custom code, how your workflow containers are published to the CTO.ai registry, and how you can run these workflows—both locally and on the CTO.ai platform.

If you’re new to using workflows on the CTO.ai platform, we recommend checking out our Workflows Overview document before you begin.

Build a Workflow (ops build)

The ops.yml file is what actually defines your workflow and how it is run, bringing together all the components in a number of important ways:

• When you build your workflow, the Dockerfile in your working directory is used to build a new container image that encapsulates your workflow. Any dependencies that your custom workflow code needs to run should be installed in the container image using the appropriate package managers.
• The name and version used to tag the new container image are taken from the name key specified in the ops.yml file.
• When you run your workflow, the shell command specified under the run key (in your ops.yml) is executed in a container built from your Dockerfile.

From within a workflow’s directory (which contains the ops.yml file, the Dockerfile, and other supporting code), we can build the container image that will run our workflow:

ops build .

The CLI will use the Dockerfile to build the container image for your workflow, with output that looks something like this:

🛠  Building: example-workflow:0.1.0

Step 1/6 : FROM registry.cto.ai/official_images/...
#
# OUTPUT TRUNCATED
#
Successfully built 66269fdbbb1f
Successfully tagged registry.cto.ai/your-team/example-workflow:0.1.0

The container image built by our CLI will have a fully-qualified tag applied, including the registry URL, your CTO.ai team, and the individual workflow’s name and build version. The fully-qualified tag has the format [Registry URL]/[Team Name]/[Image Name], where:

• Registry URL is the CTO.ai Registry: registry.cto.ai
• Team Name is the name of your team on the CTO.ai platform that is active in the current CLI context.
• Image Name is the name and version of the container image, as specified in your ops.yml file.

Run a Workflow Locally (ops run)

After the container image that encapsulates our workflow has been built, you can run it locally with the ops run command:

Run a workflow from your team or the registry.

USAGE
  $ ops run [NAMEORPATH]

ARGUMENTS
  NAMEORPATH  Name or path of the workflow you want to run.

OPTIONS
  -B, --batch  Runs the workflow in non-interactive batch mode.
  -b, --build  Builds the workflow before running. Must provide a path to the workflow.
  -h, --help   show CLI help
  --nocache    Do not use cache when building the image

We can run our workflow by specifying the name or path of the workflow to run. If you are within the workflow’s directory (which contains the ops.yml file), you can pass . as the path argument to run the local workflow:

ops run .

To make it easier to build and test your workflow iteratively, you can also pass the -b flag to ops run to rebuild your workflow container before running it locally:

ops run -b .

Using the -b flag will cause the CLI to first build your workflow container before running it, as if you had run an ops build command beforehand.

Publish a Workflow (ops publish)

To run your workflow on the CTO.ai platform, to share it with your team, or to make it accessible to the world via our public registry, you can use the ops publish command:

Publish a workflow to your team.

USAGE
  $ ops publish PATH

ARGUMENTS
  PATH  Path to the workflow you want to publish.

OPTIONS
  -c, --changelog=changelog  Provide a publish changelog
  -h, --help                 show CLI help
  -o, --ops=workflows        Provide the list of workflows that you want to publish.
  --nocache                  Do not use cache when building the image

We can publish our workflow by specifying the path of the workflow to upload. If you are within the workflow’s directory (which contains the ops.yml file, you can pass . as the path argument to publish the current workflow:

ops publish .

For ops.yml configs that define multiple workflows, you can also pass the names of individual workflows you with to publish, using the -o/--ops option. Passing workflow names to the --ops flag will also cause your workflow container image to be rebuilt before publishing.

When you run the ops publish command, it will prompt you for a changelog message, unless you pass one to the command using the -c/--changelog flag.

✓ Initial publish. added!
🔋 Creating release registry.cto.ai/your-team/da2fd289-4e20-48c7-a7af-f53f7bf2d12d:0.1.0...

Waiting: 5ea622fbce9b
Waiting: 30fba150e428
#
# OUTPUT TRUNCATED
#
Pushing: 66269fdbbb1f
Pushed: 66269fdbbb1f

🙌 registry.cto.ai/your-team/da2fd289-4e20-48c7-a7af-f53f7bf2d12d:0.1.0 has been published!
🖥  Visit your registry page here: https://cto.ai/registry/your-team/example-workflow

The output of this operation (example above) should show that the container image has been uploaded to the CTO.ai platform, and it includes the URL you can use to access your workflow’s registry page.

Run a Workflow in the Cloud (ops run)

To run a workflow that you have published to the CTO.ai platform, you can use the ops run command with the name of the Command to run passed as the only argument:

ops run example-workflow

Names that match both a local and cloud workflow will cause the CLI to prompt you to choose where your workflow should be run:

Use the arrow keys to select the workflow to run, then press your $inline[key,↵] (Enter) key to execute it:

Trigger a Workflow Non-Interactively (ops start)

To trigger a workflow to run on the CTO.ai platform—without any interactivity for the user who initiates—you can use the ops start command:

Start a service, pipeline or command on our cloud.

USAGE
  $ ops start [NAMEORPATH]

ARGUMENTS
  NAMEORPATH  Name or path of the workflow you want to run.

OPTIONS
  -h, --help  show CLI help

Run ops start with the name of the workflow you wish to run passed as the only argument:

ops start example-workflow

The only output you should see in response to using the ops start command should include the resulting status of the action and a link to view the logs for this run of your workflow:

🙌 Success, example-command has been started.
👉 View the logs here: https://cto.ai/home/teams/your-team/commands/d379f12b-444b-4ab5-a730-a166da95f836/68144b62-2214-4cb8-94b8-639fff6198c0

Remember that the ops start command can’t be used to run workflows interactively. For example, when we use ops start to run a Commands workflow that expects user input, we can see on the CTO.ai dashboard that the Commands workflow gets stuck indefinitely while waiting for a response to the first prompt:

You should use ops run instead to trigger your ChatOps-style workflows that expect user input (such as Commands workflows).