Criar Workflow

Pré-requisitos

• StackSpot CLI instalado e atualizado.
• Permissão e acessos de Content Creator para criar conteúdos para um Estúdio.

Criar um Workflow

Você deve criar o Workflow usando o STK CLI, execute o comando a seguir:

Comando para criar um Workflow

stk create workflow

Responda às perguntas no terminal. Confira a seguir as informações obrigatórias dos metadados do seu Workflow:

• Informe um nome para o Workflow;
• Dê uma descrição para o uso do seu Workflow;
• Escolha o tipo do seu Workflow. Atualmente, os tipos disponíveis são create, starter, deploy e reusable. Acesse a página que detalha os tipos disponíveis.

Uma pasta com o nome do Workflow é criada com a seguinte estrutura:

• Pasta /docs: pasta que contém um template para a documentação do seu Workflow. As documentações devem ser escritas em arquivos Markdown e têm as pastas pt_br e en_us para as documentações com versões em português e inglês.
• Arquivo .stkignore, comum em todo projeto StackSpot. Para mais detalhes, acesse a página do stkignore.
• Arquivo workflow.yaml com a estrutura do seu Workflow.

Inicialmente, o Workflow possui a seguinte estrutura:

schema-version: v1
kind: workflow
metadata:
  name: create-app-template
  display-name: "Criação de Aplicação Modelo"
  description: "Workflow inicial para orquestrar a criação de uma aplicação genérica."
  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: "Nome da Squad"
      scope: default
      name: squad_name
      type: select
      help: "Informe o nome da squad responsável pelo recurso."
      items:
        - exemplo1
        - exemplo2
        - exemplo3
    - label: "Contexto do Projeto (kebabcase)"
      scope: default
      name: project_context
      type: text
      required: true
      pattern: '^[a-z0-9]+(-[a-z0-9]+)*$'
      help: "Informe o contexto do projeto. Exemplo: meu-projeto-api"
    - label: "Adicionar MongoDB?"
      scope: default
      name: add_mongodb
      type: bool
      required: true
      default: false
      help: "Adiciona dependências do MongoDB."
    - label: "Adicionar PostgreSQL?"
      scope: default
      name: add_postgresql
      type: bool
      required: true
      default: false
      help: "Adiciona dependências do PostgreSQL."
    - label: "Adicionar Redis?"
      scope: default
      name: add_redis
      type: bool
      required: true
      default: false
      help: "Adiciona dependências do Redis."
  jobs:
    - id: job_create_app_code
      label: "Criação do código da aplicação"
      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: "Criação do repositório da aplicação"
      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 do código da aplicação"
      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: "Commit automático realizado pelo Workflow."
            repository_url: "{{ outputs.job_create_app_repository.create_git_repository.repository_url }}"

Editando o seu Workflow

Um Workflow é formado por Jobs, que são compostos por Steps.

Ao criar um Workflow, uma estrutura básica e funcional é gerada como exemplo. No entanto, essa estrutura inicial não é suficiente para atender às necessidades de um Workflow real e deve ser ajustada conforme o seu caso de uso.

Escrevendo Jobs

Um Job é composto pelos seguintes parâmetros:

• id: nome identificador do Job. Deve ser escrito no formato snake_case.
• label: texto apresentado para a pessoa usuária quando o Job estiver executando.
• depends-on: lista com os Jobs que o Job atual depende.
• when: condição que determina se o Job será executado. Retorna os valores "true" ou "false" e deve retornar "true" para que o Job execute.
• steps: lista dos passos que serão executados no 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

Escrevendo Steps

Um Step é composto pelos seguintes parâmetros:

• type: tipo do Step. As opções disponíveis são action, plugin, workflow e run. Acesse a página que detalha os tipos de Steps disponíveis.

Atenção!

Se o Step for do tipo workflow, ele deverá ser único dentro do Job.

• workdir: diretório onde o Step será executado. O valor padrão caso não for preenchido será " . " (pasta atual). Atributo opcional.
• id: nome identificador do Step. Deve ser escrito no formato snake_case.
• label: texto apresentado no Portal da StackSpot quando o Step for exibido.
• when: condição que determina se o Step será executado. Retorna os valores "true" ou "false" e deve retornar "true" para que o Step execute.
• inputs: mapeamento dos valores de inputs a serem informados para a Action/ Plugin/ Workflow. Sintaxe: nome-do-input: "valor-do-input". Acesse a página que detalha os tipos de Inputs disponíveis.
• name: indica qual Action, Plugin ou Worfklow que será executado ou aplicado. Sintaxe:
  • Action: nome-do-estudio/nome-action@número-da-versão;
  • Plugin: nome-do-estudio/nome-plugin@número-da-versão;
  • Workflow: nome-do-estudio/nome-workflow@número-da-versão;
• generated-connections: lista o mapeamento das Connections Interfaces geradas pelos Plugins. A chave é o alias da conexão e o valor é o nome indicado pela pessoa usuária.

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

Declarando Inputs

É preciso declarar os valores de inputs a na Action/Plugin/Workflow. A sintaxe é: nome-do-input: "valor-do-input".

Confira os tipos de Inputs disponíveis. Eles são definidos no campo type.

Tipos	Valor
text	String.
textarea	String.
bool	Boolean.
int	Integer.
password	Criptografa o valor informado. (string)
select	Lista os valores, permitindo escolher apenas 1 valor (string).
multiselect	Lista os valores, permitindo escolher 1 ou mais valores (string).
list	Lista de Inputs de um mesmo tipo (text, int, object e required-connection).
object	Armazena um conjunto de Inputs dentro de um objeto. O objeto passa a ser um input pai com um conjunto de inputs filhos.
required-connection	Armazena um conjunto de Inputs necessários para se conectar em uma Infraestrutura dentro de um objeto.
generated-connection	Armazena um conjunto de Inputs necessários para criar uma Infraestrutura dentro de um objeto.

Confira a seguir o trecho de um exemplo de workflow.yaml do tipo create com Inputs dos tipos select, text e bool.

schema-version: v1
kind: workflow
metadata:
  name: create-app-node-nest-api
  display-name: Criação de API Node/Nest
  description: "Orquestra a criação de uma API usando Node.js 22 e 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: "Nome da Squad"
      scope: default
      name: squad_name
      type: select
      help: "Informe o nome da squad responsável pelo recurso."
      items:
        - alpha
        - beta
        - gamma
        - delta
    - label: "Contexto do Projeto (kebabcase)"
      scope: default
      name: project_context
      type: text
      required: true
      pattern: '^[a-z0-9]+(-[a-z0-9]+)*$'
      help: "Informe o contexto do projeto. Exemplo: meu-projeto-api"
    - label: "Adicionar MongoDB?"
      scope: default
      name: add_mongodb
      type: bool
      required: true
      default: false
      help: "Adiciona dependências do MongoDB."

Acesse a página que detalha os tipos de Inputs disponíveis com os respectivos exemplos.