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.

1. From the main sidebar, click your avatar in the bottom-left corner.

2. Click Settings.

3. From the Settings menu, locate the Workspace section, then click GitOps.

4. Select the Workflows tab.

5. Toggle on Enable GitOps for Workflows editing.

6. Optionally, under Workflow GitOps repository allowlist, specify which repositories to import Workflows from. See configuring an allowlist for more information.

7. Select the the Entities tab.

8. Under Processing, toggle on Cortex YAML processing.

Step 2: Creating a YAML file for the Workflow

Prerequisites

1. You must have the Edit Workflows permission.

2. 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, at the repository's root directly within .cortex/workflows.

The Workflow YAML uses the same data structure as Cortex's Workflow API.

You can create a Workflow configuration from scratch, or you can start in the Cortex UI and export the Workflow to a YAML file.

To export a Workflow to a YAML file in Cortex:

1. From the main sidebar, select Workflows.

2. Locate the Workflow, then click the Overflow menu next to it.

   
3. Select Edit Workflow.

4. At the top of the Workflow, click the Overflow menu.

5. Select Export Workflow YAML.

   
6. The YAML is downloaded and saved to your computer.

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

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:

1. From the main sidebar, select Workflows.

2. Locate the Workflow, then click the Overflow menu next to it.

3. Select Duplicate Workflow.

4. Click Duplicate workflow. The Workflow is duplicated and a copy is added to the main Workflows page.

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

6. Make any necessary changes.

7. Save the Workflow.

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