Version: v1.0.0

Workflow and Steps Types

Workflow types define the purpose of their execution, with each type exhibiting specific behaviors during and after the execution of its Jobs.

Types

`create` type Workflow

The create type Workflow is responsible for invoking the Starter so that it applies Plugins to create an Application or Infrastructure in the StackSpot EDP Portal. This functionality is available both through the STK CLI and the StackSpot EDP Platform Portal.

See below an example of a workflow.yaml of type create that also invokes other types of Workflows:

schema-version: v1
kind: workflow
metadata:
  name: create-app-node-nest-api
  display-name: Create Node/Nest API
  description: "Orchestrates the creation of an API using Node.js 22 and NestJS."
  version: 1.0.0
spec:
  type: create
  label: "Create Node API"
  targets:
    - app
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md

  inputs:
    - label: "Squad Name"
      scope: default
      name: squad_name
      type: select
      help: "Enter the name of the squad responsible for the resource."
      items:
        - alpha
        - beta
        - gamma
        - delta

    - label: "Project Context (kebabcase)"
      scope: default
      name: project_context
      type: text
      required: true
      pattern: '^[a-z0-9]+(-[a-z0-9]+)*$'
      help: "Enter the project context. Example: my-project-api"

    - label: "Add MongoDB?"
      scope: default
      name: add_mongodb
      type: bool
      required: true
      default: false
      help: "Adds MongoDB dependencies."

    - label: "Add PostgreSQL?"
      scope: default
      name: add_postgresql
      type: bool
      required: true
      default: false
      help: "Adds PostgreSQL dependencies."

    - label: "Add Redis?"
      scope: default
      name: add_redis
      type: bool
      required: true
      default: false
      help: "Adds Redis dependencies."

  jobs:
    - id: job_create_app_code
      label: "Create application code"
      steps:
        - id: step_create_code
          name: fictitious-org/starter-node-nest-api@1.0.0
          type: workflow
          inputs:
            add_redis: "{{ add_redis }}"
            add_mongodb: "{{ add_mongodb }}"
            add_postgresql: "{{ add_postgresql }}"
            squad_name: "{{ squad_name }}"
            project_context: "{{ project_context }}"

    - id: job_create_app_repository
      label: "Create application repository"
      depends-on:
        - job_create_app_code
      steps:
        - id: create_git_repository
          name: fictitious-org/reusable-create-git-repo@0.0.1
          type: workflow
          inputs:
            project_id: "{{var.PROJECT_ID}}"
            project_name: "{{var.PROJECT_NAME}}"
            repository_name: "{{squad_name}}-api-{{project_context}}"

    - id: job_commit_app_code
      label: "Commit application code"
      depends-on:
        - job_create_app_repository
      steps:
        - id: step_commit_code
          name: fictitious-org/reusable-commit-git-repo@0.0.1
          type: workflow
          inputs:
            source_branch_name: "main"
            commit_message: "Automatic commit performed by StackSpot."
            repository_url: "{{ outputs.job_create_app_repository.create_git_repository.repository_url }}"

    - id: job_deploy_app
      label: "Deploy application"
      depends-on:
        - job_commit_app_code
      steps:
        - id: step_print_info
          label: "Important Information"
          type: run
          script: |
            echo "------------------------------------------- ATTENTION -------------------------------------------"
            echo " "
            echo " The application deployment must be performed through your CI/CD provider pipelines!"
            echo " "
            echo "-------------------------------------------------------------------------------------------------"

Deploy-type Workflow

A deploy Workflow is executed after all Jobs have completed within the deployment scope. In StackSpot, this scope ensures that all Plugins have been applied, Actions executed, and templates processed, generating the application code ready for deployment.

In this mode, certain parameters, such as the environment, are mandatory. Additionally, actions like Declarative Hooks from Actions and Plugins have already been executed and will not be triggered again during the deployment process. The targets field defines the type of resource that will be deployed.

See below an example below of the deploy type:

schema-version: v1
kind: workflow
metadata:
  name: deploy-app-node-nest
  display-name: Deploy App Node/Nest
  description: "Workflow to deploy a Node.js application with NestJS."
  version: 1.0.0
spec:
  type: deploy
  label: Deploy Node/Nest Application
  targets:
    - app
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  inputs:
    - label: "Deployment Environment Name"
      scope: default
      name: deployment_env
      type: select
      required: true
      items:
        - dev
        - staging
        - production
      help: "Select the environment where the deployment will be performed."
    - label: "Application Version"
      scope: default
      name: app_version
      type: text
      required: true
      pattern: '^[0-9]+\.[0-9]+\.[0-9]+$'
      help: "Enter the application version. Example: 1.0.0"
    - label: "S3 Bucket for Deployment"
      scope: default
      name: s3_bucket_name
      type: text
      required: true
      help: "Name of the S3 bucket where the artifacts will be stored."
  jobs:
    - id: job_prepare_deploy
      label: "Prepare Deployment Artifacts"
      steps:
        - id: step_build_artifacts
          type: action
          label: "Build Application"
          name: fictitious-org/build-app-action@1.0.0
          inputs:
            app_version: "{{ app_version }}"
    - id: job_upload_s3
      label: "Upload Artifacts to S3"
      depends-on:
        - job_prepare_deploy
      steps:
        - id: step_upload_to_s3
          type: action
          label: "Upload to S3"
          name: fictitious-org/upload-s3-action@1.0.0
          inputs:
            bucket_name: "{{ s3_bucket_name }}"
            app_version: "{{ app_version }}"
    - id: job_apply_infra
      label: "Apply Infrastructure in Environment"
      depends-on:
        - job_upload_s3
      steps:
        - id: step_apply_infra_plugin
          type: plugin
          label: "Infra Deploy Plugin"
          name: fictitious-org/infra-deploy-plugin@1.0.0
          inputs:
            environment: "{{ deployment_env }}"
            app_version: "{{ app_version }}"
            bucket_name: "{{ s3_bucket_name }}"
    - id: job_notify_deploy
      label: "Notify Deployment Success"
      depends-on:
        - job_apply_infra
      steps:
        - id: step_notify_slack
          type: action
          label: "Slack Notification"
          name: fictitious-org/notify-slack-action@1.0.0
          inputs:
            environment: "{{ deployment_env }}"
            app_version: "{{ app_version }}"
            message: "Deployment of version {{ app_version }} successfully completed in environment {{ deployment_env }}."

`reusable` type Workflow

The main feature of the reusable Workflow type is to receive inputs and generate outputs, which can be used in other Workflows, making it reusable within other Workflows. Because of this, reusable is the only Workflow type that contains outputs.

See below an example of the reusable type:

schema-version: v1
kind: workflow
metadata:
  name: reusable-create-git-repo
  display-name: Reusable - Create Git Repository
  description: "Creates a code repository in a version control service."
  version: 0.1.0
spec:
  type: reusable
  label: "Create Git Repository"
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  inputs:
    - label: "Project ID"
      scope: default
      name: project_id
      type: text
      required: true
      help: "Enter the project identifier in your repository provider."
    - label: "Project Name"
      scope: default
      name: project_name
      type: text
      required: true
      help: "Enter the project name in your repository provider."
    - label: "Repository Name"
      scope: default
      name: repository_name
      type: text
      required: true
      help: "Enter the name of the repository to be created."
  outputs:
    repository_id: "{{ outputs.job_git_repository.create_repository.repository_id }}"
    repository_url: "{{ outputs.job_git_repository.create_repository.repository_url }}"
  jobs:
    - id: job_git_repository
      label: "Repository creation orchestration"
      steps:
        - id: create_repository
          label: "Executes the repository creation action"
          name: fictitious-org/create-git-repository@0.1.0
          type: action
          inputs:
            project_id: "{{ project_id }}"
            project_name: "{{ project_name }}"
            repository_name: "{{ repository_name }}"

tip

Workflow outputs behave similarly to computed-inputs. For more details on how to use Workflow outputs, see the computed-inputs documentation.

`rollback` type Workflow

The rollback Workflow executes Jobs to revert the version of a deployed Application or Infrastructure. The targets field defines the type of resource that will be rolled back.

schema-version: v1
kind: workflow
metadata:
  name: rollback-infra-generic
  display-name: Generic Infrastructure Rollback
  description: "Orchestrates the rollback of an infrastructure to a previous version."
  version: 1.0.0
spec:
  type: rollback
  label: Infrastructure Rollback
  targets:
    - infra
  docs:
    en-us: docs/en_us/rollback.md
    pt-br: docs/pt_br/rollback.md
  inputs:
    - label: "Environment"
      scope: default
      name: environment_id
      type: select
      required: true
      items:
        - dev
        - staging
        - production
      help: "Select the environment where the rollback will be performed."
    - label: "Version for rollback"
      scope: default
      name: rollback_version
      type: text
      required: true
      pattern: '^\d+\.\d+\.\d+$'
      help: "Enter the desired version for the rollback. Example: 1.2.3"
  jobs:
    - id: job_prepare_rollback
      label: "Prepare rollback"
      steps:
        - id: step_validate_permissions
          type: action
          label: "Validate User Permissions"
          name: fictitious-org/validate-rollback-permission-action@1.0.0
          inputs:
            environment_id: "{{ environment_id }}"
    - id: job_execute_rollback
      label: "Execute rollback"
      depends-on:
        - job_prepare_rollback
      steps:
        - id: step_rollback_infra
          type: plugin
          label: "Execute Infrastructure Rollback"
          name: fictitious-org/rollback-infra-plugin@1.0.0
          inputs:
            environment_id: "{{ environment_id }}"
            rollback_version: "{{ rollback_version }}"
    - id: job_notify_rollback
      label: "Notify rollback"
      depends-on:
        - job_execute_rollback
      steps:
        - id: step_notify_slack
          type: action
          label: "Slack Notification"
          name: fictitious-org/notify-slack-action@1.0.0
          inputs:
            environment: "{{ environment_id }}"
            version: "{{ rollback_version }}"
            message: "Rollback to version {{ rollback_version }} successfully executed in environment {{ environment_id }}."

`starter`type Workflow

A starter Workflow executes the application of Plugins to create an Application or Infrastructure using the STK CLI. To create an Application or Infrastructure using a Workflow through the StackSpot EDP Portal, use the create type.

Using Starters to create Applications or Infrastructures is still possible, but it is deprecated. The targets field defines the type of resource that will be created.

schema-version: v1
kind: workflow
metadata:
  name: starter-app-node-nest-api
  display-name: Starter App Node/Nest API
  description: "Provisions the creation of a Node.js API with NestJS."
  version: 1.0.0
spec:
  type: starter
  label: "Starter Node API"
  targets:
    - app
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  inputs:
    - label: "Squad Name"
      scope: default
      name: squad_name
      type: text
      required: true
      pattern: '^[a-z]+$'
      help: "Enter the responsible squad name. Use only lowercase letters. Example: squadx."

    - label: "Project Context (kebab-case)"
      scope: default
      name: project_context
      type: text
      required: true
      pattern: '^[a-z0-9]+(-[a-z0-9]+)*$'
      help: "Enter the project context in kebab-case. Example: my-project-api."

    - label: "Add MongoDB support?"
      scope: default
      name: add_mongodb
      type: bool
      required: true
      default: false
      help: "Adds MongoDB dependencies to the project."

    - label: "Add PostgreSQL support?"
      scope: default
      name: add_postgresql
      type: bool
      required: true
      default: false
      help: "Adds PostgreSQL dependencies to the project."

    - label: "Add Redis support?"
      scope: default
      name: add_redis
      type: bool
      required: true
      default: false
      help: "Adds Redis dependencies to the project."

  computed-inputs:
    project_name: "{{ squad_name }}-api-{{ project_context }}"

  jobs:
    - id: job_apply_plugins
      label: "App Plugins Application"
      steps:
        - id: step_apply_app_plugin
          type: plugin
          label: "Apply Base Node/Nest Plugin"
          name: fictitious-org/app-node-nest-base@1.0.0
          inputs:
            squad_name: "{{ squad_name }}"
            project_context: "{{ project_context }}"

        - id: step_apply_mongodb_plugin
          type: plugin
          label: "Apply MongoDB Plugin"
          when: "{{ add_mongodb }}"
          name: fictitious-org/app-node-nest-add-mongodb@1.0.0
          inputs:
            project_name: "{{ project_name }}"

        - id: step_apply_postgresql_plugin
          type: plugin
          label: "Apply PostgreSQL Plugin"
          when: "{{ add_postgresql }}"
          name: fictitious-org/app-node-nest-add-postgresql@1.0.0
          inputs:
            project_name: "{{ project_name }}"

        - id: step_apply_redis_plugin
          type: plugin
          label: "Apply Redis Plugin"
          when: "{{ add_redis }}"
          name: fictitious-org/app-node-nest-add-redis@1.0.0
          inputs:
            project_name: "{{ project_name }}"

Step Type

`plugin` Step

A Step of type plugin executes the application of Plugins within a Job in your Workflow. This Step allows you to define all the values that should be obtained by the Workflow and used during the application of the Plugins.

Example:

steps:
  - type: plugin
    name: 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 }}"

type: The Step type.
name: The name of the Plugin will be applied by the Step. Use the format: studio-name/name-plugin@1.0.0(semantic version).

warning

The name field always uses the Plugin Studio Qualifier. This allows it to be applied both inside and outside a Workspace. Learn more about the Plugin Studio Qualifier.

id: Step identifier ID.
label: Name displayed on the Activities screen in the Workflow log.
when (Optional): Parameter to use a boolean value as a condition for executing the Job or Step.
inputs: Specifies the inputs for the Plugins defined in the Workflow. The syntax for filling them in is:
- input_name: "input_value"

Example:

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 }}"

`action` Step

The action Step executes an Action within a Job of your Workflow. This Step allows you to define all the values that must be obtained by the Workflow and used during the Action execution.

Example:

steps:
  - id: action_example
    label: Example of step run action
    name: studio-name/action-name@1.0.0
    type: action
    inputs:
      input_1: "This is a example of fixed input"

id: Step identifier ID.
label: Name displayed on the Activities screen in the Workflow log.
name: Name of the Action that the Step will execute. Use the format: studio-name/action-name@1.0.0(semantic version).
type: Step type.
inputs: Specifies the inputs for the Action defined in the Workflow. The syntax for filling them in is:
- input_name: "input_value".

`suspend` Step

A Step of type suspend pauses the execution of the Workflow until someone approves its continuation. Whenever the execution of a Workflow is paused by a suspend Step, the person responsible for the Account or Workspace in your Organization must approve the continuation of the Workflow execution.

Another way to resume the execution of a suspended Workflow is by running the stk resume workflow command in local executions or in pre-configured pipeline steps.

steps:
  - id: example_suspend
    label: Example of step suspend
    type: suspend

id: Step identifier ID.
label: Name displayed on the Activities screen in the Workflow log.
type: Step type.

`run` Step

A Step of type run executes arbitrary Shell commands.

The command in the script parameter compresses the files into a tar.gz archive
steps:
  - id: step_id_1
    label: Step which say hello
    type: run
    script: |
      tar -czvf archive.tar.gz file1 file2

id: Step identifier ID.
label: Name displayed on the Activities screen in the Workflow log.
type: Step type.
script: Shell script that will be executed by the Step.

`workflow` Step

A Step of type workflow executes another Workflow published in your Studio.

steps:
  - id: step_id_1
    name: nome-studio/nome-workflow@1.0.0
    type: workflow
    inputs:
      input_1: "This is a example of fixed input"

id: Step identifier.
name: Name of the Workflow to be executed by the Step. Use the format: studio-name/workflow-name@1.0.0(semantic version).

danger

The name field always uses the Studio Qualifier of the Workflow. This allows it to be executed inside or outside a Workspace. Learn more about the Studio Qualifier of Plugins to execute other Workflows.

type: Step type.
inputs: Filling in the inputs for the Workflow to be executed. The syntax to define them is:
- input_name: "input_value"

The label parameter is optional for Steps of the workflow type.

Executing Steps with Strategy Loop

The Strategy Loop in StackSpot Workflow allows you to execute a Step repeatedly for each value in a provided list. The Strategy Loop runs the same Step for every value in the list, iterating over each element.

During the execution of the Strategy Loop, two variables are automatically made available for use within the Step:

stk_loop_index: Represents the current position of the element in the list.
stk_loop_value: Represents the current value of the element in the list.

These variables can be used in different parts of the Step, such as in the script field, to customize the execution based on the current iteration value.

Example of a Workflow snippet demonstrating the use of Strategy Loop.
jobs:
  - id: job_id
    label: Label do Job
    steps:
      - id: ID do Step
        type: run # Step 'run' type
        label: step label, add the variables {{stk_loop_index}} e {{stk_loop_value}}
        strategy:
          loop: input_list # list-type input provided in the 'strategy.loop' field of the Workflow
        script: |
          echo "Example script that prints the position and value of the items in the provided list: {{stk_loop_index}} and {{stk_loop_value}}"

How the Strategy Loop works

Defining the List: The list received by the Strategy Loop can be provided in two ways:

Via Input: a list-type input defined in the Workflow.

Example of a list-type input that receives a list of IP strings.
inputs:
  - label: Inform the IPs list
    name: ips
    type: list
    add-question: Do you want to add more IPs in the list?
    input:
      type: text
      label: Endereço IP

In this example, the list of IPs is provided as a Workflow input.
jobs: # StackSpot Workflow Job
  - id: process_ip_list
    label: Process IPs
    steps: # Step that will use the 'ips' list
      - id: process_ip
        type: run
        label: Process IP {{stk_loop_index}} - {{stk_loop_value}}
        strategy:
          loop: ips # list-type input defined in the previous example
        script: | # script execution using the 'strategy.loop' variables
          echo "IP processed at index {{stk_loop_index}}: {{stk_loop_value}}"

tip

The example uses a list-type input with text-type inputs, but you can use any input type supported by the list input:

text;
int;
object;
required-connection.

For more details about the list input, see the Inputs page.

Hardcoded: The list is defined directly in the strategy.loop field of the Workflow:

Example of a string list.
strategy:
  loop:
    - "192.168.0.1"
    - "10.0.0.1"
    - "172.16.0.1"

strategy:
  loop: ["192.168.0.1", "10.0.0.1", "172.16.0.1"]

Workflow Types Comparison

create
- Orchestrates the creation of an Application or Infrastructure.
- Runs Plugins and other Workflows to provide resources.
- Available in both the Portal and STK CLI.
- Replaces the Starter for creation via the Portal.
deploy
- Deploys an existing Application or Infrastructure.
- Ensures that all Plugins and Actions have been applied.
- Requires mandatory parameters, such as the environment.
- Does not re-execute declarative Hooks.
reusable
- Executes versatile and adaptable Jobs.
- Accepts inputs and produces outputs for reuse in other Workflows.
- Optimized for sharing logic across various processes.
rollback
- Executes processes to restore an Application or Infrastructure to a previous version.
- Requires details such as environment and the version to be reverted.
- Emphasizes on reverting to earlier configurations.
starter

Uses Plugins to create an Application or Infrastructure via the STK CLI.
Starters have been deprecated but are still available.
Not recommended for new projects; instead, use the create type.

Type	What it does	What it does not do	Where to use
create	Creates Applications/Infrastructure, orchestrates Plugins/Workflows	It does not deploy, does not perform rollback, cannot be reused in other Workflows	Portal and STK CLI
deploy	Deploys already created resources, applies deploy Plugins/Actions	It does not create resources, does not perform rollback, cannot be reused	Portal and STK CLI
reusable	Runs generic logic, receives inputs and generates outputs for others	It does not create/deploy resources directly, does not perform rollback	Within other Workflows
rollback	Reverts Application/Infrastructure to a previous version	It does not create/deploy resources, cannot be reused, does not orchestrate creation	Portal and STK CLI
starter	Creates Application/Infrastructure via CLI with predefined Plugins	It does not deploy or rollback, not recommended for new projects, not available in Portal	STK CLI (deprecated)

tip

Use the create type for new projects, as it replaces Starters and provides greater flexibility.
Choose deploy to publish and update resources.
Centralize common logic in reusable Workflows to simplify maintenance and enhance reusability.
Use rollback to restore previous versions of resources in a controlled manner.
Avoid creating new starter Workflows; only use them to maintain compatibility with legacy projects.

Types

create type Workflow

Deploy-type Workflow

reusable type Workflow

rollback type Workflow

startertype Workflow

Step Type

plugin Step

action Step

suspend Step

run Step

workflow Step

Executing Steps with Strategy Loop

How the Strategy Loop works

Workflow Types Comparison

`create` type Workflow

`reusable` type Workflow

`rollback` type Workflow

`starter`type Workflow

`plugin` Step

`action` Step

`suspend` Step

`run` Step

`workflow` Step