Workflows as code

Workflows allow you to run sequential actions and increase efficiency across development workflows. With Workflows as code, you can treat Workflows like other production asset; this feature allows you to manage Workflows through GitOps. Each Workflow has its own YAML file. When GitOps is enabled, changes made to Workflows will appear in GitOps logs.

Managing Workflows in both GitOps and the Cortex UI

When you enable GitOps editing for Workflows, it only affects Workflows that are backed by a YAML file. You can still create and delete Workflows via the Cortex UI, and you can still edit a Workflow via the UI if it’s not managed via GitOps.

Step 1: Configuring GitOps editing for Workflows

Users with the Edit Workflows permission can configure GitOps editing in Cortex.

Enabling GitOps editing for Workflows only affects Workflows backed by a YAML file. You can still create and delete Workflows via the Cortex UI.

From the main sidebar, click your avatar in the bottom-left corner.
Click Settings.
From the Settings menu, locate the Workspace section, then click GitOps.
Select the Workflows tab.
Toggle on Enable GitOps for Workflows editing.
Optionally, under Workflow GitOps repository allowlist, specify which repositories to import Workflows from. See configuring an allowlist for more information.
Select the the Entities tab.
Under Processing, toggle on Cortex YAML processing.

Step 2: Creating a YAML file for the Workflow

Prerequisites

You must have the Edit Workflows permission.
An existing Workflow. If you haven’t yet created a Workflow, refer to Creating a Workflow and Configuring Workflow settings.

Workflow YAML files must be stored in their own repository, separate from catalog entities, under .cortex/workflows at the repository root. You can organize the files into subdirectories, which Cortex searches recursively. The Workflow YAML uses the same data structure as Cortex’s Workflow API. For the fields each block takes, see the Workflow block configuration reference. For complete definitions you can start from, see Example Workflow definitions. You can create a Workflow configuration from scratch, or you can start in the Cortex UI and export the Workflow to a YAML file. GitOps editing applies only to Workflows that are backed by a YAML file, so you can continue to create, edit, and delete other Workflows in the Cortex UI. For more information, refer to Using both the UI and GitOps. To export a Workflow to a YAML file in Cortex:

From the main sidebar, select Workflows.
Do one of the following:
- Select the All tab to search and filter across all of your organization’s Workflows.
- Select the Mine tab to search and filter only the Workflows you own.
- Note that Cortex saves your selection and restores it the next time you open this page.
Locate the Workflow, then click the overflow menu icon next to it.
Select Edit Workflow.
At the top of the Workflow, click the Overflow menu.
Select Export Workflow YAML.
The YAML is downloaded and saved to your computer.
Add the YAML file to your Git repository within .cortex/workflows.

Example Workflow YAML

A nested form input is a NESTED_FORM_FIELD on a USER_INPUT action under schema.inputs. When the data type is a single value, the item is described by a nested element object: set its type (for example, NUMBER_FIELD) and, for numbers, a format of INTEGER or DECIMAL, along with optional per-item min, max, placeholder, and defaultValue. The field’s top-level itemType summarizes the item type. The outer min and max set the number of items the runner can enter ( min defaults to 1 and also serves as the default count) while element.min and element.max bound each individual value. Other item types use the same structure with a different element.type and itemType. Example YAML (single value, number / integer)

name: Provision replicas
tag: provision-replicas
description: null
isDraft: true
filter:
  type: GLOBAL
isRunnableViaApi: false
actions:
- name: Get deployments
  slug: get-deployments
  schema:
    inputs:
    - name: Replica counts
      description: null
      key: replica-counts
      required: false
      disabled: false
      element:                 # describes each item (present for "Single value")
        name: Replica counts
        description: null
        key: replica-counts
        required: false
        disabled: false
        defaultValue: null
        placeholder: null
        format: INTEGER        # INTEGER or DECIMAL (NUMBER_FIELD only)
        min: null              # per-item minimum value
        max: null              # per-item maximum value
        type: NUMBER_FIELD     # item value type
      min: 1                   # min number of items (element count); also the default count
      max: null                # max number of items (element count)
      itemType: INTEGER        # summary of the item type
      type: NESTED_FORM_FIELD
    inputOverrides: []
    jsValidatorScript: ""
    type: USER_INPUT
  outgoingActions: []
  isRootAction: true
runRestrictionPolicies: []
iconTag: null
variables: []

A note about the example Workflow YAML

itemType sets the item type. It defaults to OBJECT; other values (for example STRING or INTEGER) make each item a single value.
With itemType: OBJECT, the nested form is a sub-form. Define one or more sub-inputs per row.
With a single-value itemType, the item is described by the nested element object—its type and type-specific options such as format for numbers or validationRegex for text. There is no separate inputs list on the field.
min and max are optional element-count limits and apply to every itemType. min defaults to 1 and also acts as the default number of rows.
name, description, key, and required apply to the field for every itemType. inputOverrides and jsValidatorScript are set at the schema level, not on the field.

Item type reference

Value type	element.type	itemType
Text	`INPUT_FIELD`	`STRING`
Paragraph	`TEXTAREA_FIELD`	`STRING`
Number (Integer)	`NUMBER_FIELD` + `format: INTEGER`	`INTEGER`
Number (Decimal)	`NUMBER_FIELD` + `format: DECIMAL`	`DECIMAL`
Toggle	`TOGGLE_FIELD`	`BOOLEAN`
Date	`DATE_FIELD`	`STRING`

element also carries type-specific keys, i.e. NUMBER_FIELD adds format (INTEGER/DECIMAL) plus min/max; text types add validationRegex. For the default Object data type, the field uses a list of sub-field definitions instead of a single element.

Example Run Workflow block YAML

A Run Workflow block uses type: RUN_WORKFLOW under schema. inputs maps each of the child Workflow’s variable slugs to a value or a template, and waitForCompletion makes the block wait for the child run to finish.

- name: Run approval
  slug: run-approval
  schema:
    type: RUN_WORKFLOW
    workflowId: approval-workflow
    waitForCompletion: true
    inputs:
      app-id: "{{actions.form.outputs.appId}}"
      count: 5

Values keep the child variable’s type, so count: 5 is passed as a number. If the child Workflow has no variables, set inputs: {}.

Editing GitOps-managed Workflows in Cortex

Users with the Edit Workflows permission can duplicate and edit Workflows in Cortex. GitOps-managed Workflows are read-only in the Cortex UI. To modify one, create a duplicate, edit the copy, and use it as your primary Workflow going forward. The UI displays a link to the Workflow’s YAML file in your repository:

The 'Repo' icon in the upper-right corner of a Workflow.

From the main sidebar, select Workflows.
Do one of the following:
- Select the All tab to search and filter across all of your organization’s Workflows.
- Select the Mine tab to search and filter only the Workflows you own.
- Note that Cortex saves your selection and restores it the next time you open this page.
Locate the Workflow, then click the overflow menu icon next to it.
Select Duplicate Workflow.
Click Duplicate workflow. The Workflow is duplicated and a copy is added to the main Workflows page.
To edit the new Workflow, do one of the following:
1. Click Edit Workflow in the toast notification that appears in the bottom-right corner.
2. Locate the Workflow, click the Overflow menu next to it, then select Edit Workflow.
Make any necessary changes.
Save the Workflow.

A Git icon next to a Workflow’s name indicates that it’s managed via GitOps:

Cortex

Get Started

Connect data

Standardize

Improve

Streamline

Configure

Resources

Workflows as code

Managing Workflows in both GitOps and the Cortex UI

Step 1: Configuring GitOps editing for Workflows

Step 2: Creating a YAML file for the Workflow

Example Workflow YAML

Example Run Workflow block YAML

Editing GitOps-managed Workflows in Cortex

​Managing Workflows in both GitOps and the Cortex UI

​Step 1: Configuring GitOps editing for Workflows

​Step 2: Creating a YAML file for the Workflow

​Example Workflow YAML

​Example Run Workflow block YAML

​Editing GitOps-managed Workflows in Cortex

Managing Workflows in both GitOps and the Cortex UI

Step 1: Configuring GitOps editing for Workflows

Step 2: Creating a YAML file for the Workflow

Example Workflow YAML

Example Run Workflow block YAML

Editing GitOps-managed Workflows in Cortex