Workflow Specification

In this section, you will find details about the workflow.yaml specification, including required and optional fields and how to use them in StackSpot Workflows.

Workflow Specification

A Workflow is created as a YAML file named workflow.yaml. See a manifest example below:

Manifest workflow.yaml specification
schema-version: v1
kind: workflow
metadata:
  name: workflow-name
  display-name: Workflow displayed to user
  description: Description of what workflow does
  version: 0.0.1
spec:
  type: deploy
  label: Deploy application
  repository: https://github.com/stack-spot/workflow?utm_source=stackspot
  targets: 
    - "app"
    - "infra"
  docs:
    pt-br: docs/pt-br/doc.md
    en-us: docs/en-us/doc.md
  inputs:
   - type: text
     name: text_input
     label: "Type some text:"
   - type: bool
     name: boolean_input
     label: "Do you want to run optional job?"
   - type: generated-connection
     name: some_s3_connection
     label: "Give an alias for generated S3 connection"
     connection-interface-type: aws-s3-conn
  computed-inputs:
    computed_input_name: "{{ text_input | upper }}"
  outputs:
    uppercase_text_output: "{{ computed_input_name | upper }}"
  portal-extensions:
    - id: widget_1
      name: Widget 1
      slug: teste-widget-workflow
    - id: widget_2
      name: Widget 2
      slug: widget-digital-store  
  jobs:
    - id: some_job
      label: Some job
      steps:
        - type: action
          name: studio/some_action@1
          id: some_action_execution
          label: Execution action
          workdir: .
          inputs:
            some_action_input: "fixed_value"
            other_action_input: "{{ inputs.text_input }}"
    - id: optional
      label: Optional job
      depends-on:
        - some_job
      when: "{{ boolean_input }}"
      steps:
        - type: plugin
          name: studio/optional_plugin@1
          id: apply_optional_plugin
          label: Apply optional plugin
          when: "{{ boolean_input }}"
          inputs:
            some_plugin_input: "fixed_value"
            other_plugin_input: "{{ text_input | lower }}"
            input_from_other_job: "{{ outputs.some_job.some_action_execution.some_action_output }}"

Workflow Attributes

Below are the details for each attribute in a Workflow specification:

Attribute	Description
`schema-version`	Contains the schema version. Fixed value `v1`.
`kind`	Contains the manifest type. Fixed value `workflow`.
`metadata`	Contains metadata information for the Workflow: name, description, and version.
`spec`	Contains the Workflow specification.
`spec.label`	Label displayed to the user to identify the Workflow.
`spec.repository`	URL for the Workflow source repository. Optional attribute.
`spec.type`	Workflow type. Can be `create`, `starter`, `deploy`, `rollback`, or `reusable`.
`spec.targets`	Required for Workflows of type `starter`, `deploy`, or `rollback`. Indicates whether the Workflow can be applied to `app`, `infra`, or both.
`spec.docs`	Workflow documentation in Portuguese and English. Optional attribute. Documentation must be in Markdown format.
`spec.inputs`	Lists the inputs requested from the user when running the Workflow, except for inputs that have the `scope: hidden` parameter configured.
`spec.computed-inputs`	Contains computed inputs derived from the values of other inputs, using Jinja expressions.
`spec.outputs`	Workflow output attributes, if any. Defined using Jinja expressions.
`spec.portal-extensions`	List of Portal Widget extensions associated with the Workflow.
`spec.portal-extensions[i].id`	Widget extension ID in the Portal. IDs must be unique within each Workflow version.
`spec.portal-extensions[i].name`	Name of the Portal Widget extension displayed to the user.
`spec.portal-extensions[i].slug`	Slug of the Portal Widget extension. The slug must be registered in the Portal at Workflow level.
`spec.jobs`	Groups of tasks (Jobs) that must be executed in the Workflow.
`spec.jobs[i].id`	Identifier for the Job, used for referencing within the Workflow. Must use `snake_case` format.
`spec.jobs[i].label`	Label shown to the user when the Job is running.
`spec.jobs[i].depends-on`	List of other Jobs that this Job depends on. Jobs with all dependencies resolved can run in parallel.
`spec.jobs[i].when`	Condition for the Job to run, defined by a Jinja expression that must return `true` (case insensitive).
`spec.jobs[i].steps`	List of steps that will be executed within the Job.
`spec.jobs[i].steps[i].type`	Step type. Can be `action`, `plugin`, `workflow`, `run`, or `suspend`.
`spec.jobs[i].steps[i].workdir`	Directory where the Step will be executed. Optional attribute.
`spec.jobs[i].steps[i].id`	Step ID for referencing within the Workflow. Must use `snake_case` format.
`spec.jobs[i].steps[i].label`	Label displayed in the Portal when the Step is shown.
`spec.jobs[i].steps[i].when`	Condition for the Step to execute, defined by a Jinja expression.
`spec.jobs[i].steps[i].inputs`	Mapping of input values to be passed to the Action, Plugin, or Workflow being called.
`spec.jobs[i].steps[i].name`	Indicates which Action, Plugin, or Workflow will be executed or applied.
`spec.jobs[i].steps[i].generated-connections`	Map of connections generated by the Plugin. The key is the connection alias and the value is the name provided by the user.
`spec.workflows`	Only for Workflows of type `starter`. Defines which Workflows will be automatically added to the `stk.yaml` file.