Create Workflow

Prerequisites

• StackSpot CLI installed and updated.
• Content Creator permission and access to create content for a Studio.

Create a Workflow

You must create the Workflow using the STK CLI. Run the following command:

Command to create a Workflow

stk create workflow

Answer the questions in the terminal. See the required metadata fields for your Workflow:

• Provide a name for the Workflow;
• Enter a description for the usage of your Workflow;
• Choose the type of your Workflow. The currently available types are create, starter, deploy, and reusable.For more details, visit the page detailing the available types.

A folder with the Workflow name is created with the following structure:

• /docs folder: This folder contains a template for your Workflow documentation. The documentation must be written in Markdown files and include pt_br and en_us folders for Portuguese and English versions, respectively.
• .stkignore file, common to all StackSpot projects. For more details, visit the stkignore page.
• workflow.yaml file containing the structure of your Workflow.

The Workflow has the following structure:

schema-version: v1
kind: workflow
metadata:
  name: create-app-template
  display-name: "Create Model App"
  description: "Initial workflow for orchestrating the creation of a generic application."
  version: 0.1.0
spec:
  type: create
  label: "Create Generic App"
  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:
        - example1
        - example2
        - example3
    - label: "Project Context"
      scope: default
      name: project_context
      type: text
      required: true
      pattern: '^[a-z0-9]+(-[a-z0-9]+)*$'
      help: "Enter the name project. Example: my-api-context"
    - label: "Add MongoDB?"
      scope: default
      name: add_mongodb
      type: bool
      required: true
      default: false
      help: "Add dependency on MongoDB."
    - label: "Add PostgreSQL?"
      scope: default
      name: add_postgresql
      type: bool
      required: true
      default: false
      help: "Add PostgreSQL dependency"
    - label: "Add Redis?"
      scope: default
      name: add_redis
      type: bool
      required: true
      default: false
      help: "Add Redis dependency."
  jobs:
    - id: job_create_app_code
      label: "Create app code"
      steps:
        - id: step_create_code
          name: fictitious-org/starter-app-base@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 app respository"
      depends-on:
        - job_create_app_code
      steps:
        - id: create_git_repository
          name: fictitious-org/reusable-create-git-repo@0.1.0
          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 the application code"
      depends-on:
        - job_create_app_repository
      steps:
        - id: step_commit_code
          name: fictitious-org/reusable-commit-git-repo@0.1.0
          type: workflow
          inputs:
            source_branch_name: "main"
            commit_message: "Automatic commit performed by Workflow."
            repository_url: "{{ outputs.job_create_app_repository.create_git_repository.repository_url }}"

Editing Your Workflow

A Workflow is composed of Jobs, which in turn are made up of Steps.

When you create a Workflow, a basic and functional structure is generated as an example. However, this initial structure is not sufficient for real-world use cases and should be adjusted according to your needs.

Writing Jobs

A Job consists of the following parameters:

• id: Identifier name for the Job. It must be written in snake_case.
• label: Text shown to the user when the Job is running.
• depends-on: List of Jobs that the current Job depends on.
• when: Condition that determines if the Job will be executed. Returns "true" or "false" and must return "true" for the Job to run.
• steps: List of steps that will be executed in the Job.

Jobs:
  - id: optional
    label: Optional job
    depends-on:
      - some_job-id
    when: "{{ boolean_input }}"
    steps:
      - type: plugin
        name: studio/optional_plugin@1
        id: apply_optional_plugin
        label: Apply optional plugin

Writing Steps

A Step is composed of the following parameters:

• type: Step type. The available options are action, plugin, workflow, and run. For more details, visit the page detailing the types of Steps available.

warning

If the Step is of type workflow, it must be unique within the Job.

• workdir: Directory where the Step will be executed. If not provided, the default value will be " . " (the current folder). Optional attribute.
• id: Identifier name of the Step. It must be written in snake_case format.
• label: Text displayed in the StackSpot Portal when the Step is shown.
• when: Condition that determines whether the Step will be executed. Returns "true" or "false" and must return "true" for the Step to execute.
• inputs: Mapping of input values to be provided for the Action/Plugin/Workflow. Syntax: input-name: "input-value". For more details, visit the page detailing the types of inputs available.
• name: Indicates which Action, Plugin, or Workflow will be executed or applied. Syntax:
  • Action: studio-name/action-name@version-number;
  • Plugin: studio-name/plugin-name@version-number;
  • Workflow: studio-name/workflow-name@version-number;
• generated-connections: Lists the mapping of Connection Interfaces generated by the Plugins. The key is the connection alias, and the value is the name provided by the user.

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

Declaring Inputs

You must declare the values of inputs in Action/Plugin/Workflow. The syntax is: input-name: “input-value”.

Check the input types available in StackSpot Workflow. They are defined in the type field.

Type	Value
text	String.
textarea	String.
bool	Boolean.
int	Integer.
**password	Encrypts the provided value. (string)
select	Lists values, allowing you to select only one value (string).
**multiselect	Lists values, allowing you to select one or more values (string).
list	List of inputs of the same type (text, int, object, and required-connection).
object	It stores a set of inputs inside an object. The object becomes a parent input with a set of child inputs.
required-connection	It stores a set of inputs required to connect to Infrastructure inside an object.
generated-connection	It stores a set of inputs required to provision Infrastructure inside an object.

See below excerpt from an example of a create type workflow.yaml with select, text, and bool type inputs.

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

For more details, visit the page that details the types of inputs available with their respective examples.