Tipos de Workflow

Os tipos de Workflow definem a finalidade da sua execução. Cada tipo possui um comportamento específico durante e após a finalização das execuções dos seus Jobs.

Tipos de Workflow

Workflow do tipo create

O Workflow do tipo create é quem evoca o Starter para que ele aplique Plugins para a criação de uma Aplicação ou Infraestrutura no Portal da StackSpot EDP. O uso está disponível tanto no STK CLI, quanto no Portal da Plataforma da StackSpot EDP.

Confira a seguir um exemplo de workflow.yaml do tipo create que também evoca os outros tipos de Workflow:

Exemplo de um Workflow do tipo 'create' invocando os demais tipos de Workflow

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

    - 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-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: "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.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 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.0.1
          type: workflow
          inputs:
            source_branch_name: "main"
            commit_message: "Commit automático realizado pelo StackSpot."
            repository_url: "{{ outputs.job_create_app_repository.create_git_repository.repository_url }}"

    - id: job_deploy_app
      label: "Deploy da aplicação"
      depends-on:
        - job_commit_app_code
      steps:
        - id: step_print_info
          label: "Informações Importantes"
          type: run
          script: |
            echo "------------------------------------------- ATENÇÃO -------------------------------------------"
            echo " "
            echo " O deploy da aplicação deve ser realizado através das pipelines do seu provedor de CI/CD!"
            echo " "
            echo "-----------------------------------------------------------------------------------------------"

Workflow do tipo deploy

O Workflow do tipo deploy é executado após todos os Jobs terem sido concluídos dentro do escopo de deploy. Na StackSpot, esse escopo garante que todos os Plugins foram aplicados, as Actions executadas e os templates processados, gerando o código do aplicativo pronto para ser implantado.

Isso significa que, nesse modo, parâmetros como o ambiente (environment) são obrigatórios, e ações como Hooks Declarativos de Actions e Plugins já foram executadas e não serão disparadas novamente durante o deploy. O campo targets define o tipo de recurso que será implantado no deploy.

Exemplo de um Workflow do tipo 'deploy'

schema-version: v1
kind: workflow
metadata:
  name: deploy-app-node-nest
  display-name: Deploy App Node/Nest
  description: "Workflow para realizar o deploy de uma aplicação Node.js com NestJS."
  version: 1.0.0
spec:
  type: deploy
  label: Deploy de Aplicação Node/Nest
  targets:
    - app
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  inputs:
    - label: "Nome do Ambiente de Deploy"
      scope: default
      name: deployment_env
      type: select
      required: true
      items:
        - dev
        - staging
        - production
      help: "Selecione o ambiente em que o deploy será realizado."
    - label: "Versão da Aplicação"
      scope: default
      name: app_version
      type: text
      required: true
      pattern: '^[0-9]+\.[0-9]+\.[0-9]+$'
      help: "Informe a versão da aplicação. Exemplo: 1.0.0"
    - label: "Bucket S3 para Deploy"
      scope: default
      name: s3_bucket_name
      type: text
      required: true
      help: "Nome do bucket S3 onde os artefatos serão armazenados."
  jobs:
    - id: job_prepare_deploy
      label: "Preparar Artefatos de Deploy"
      steps:
        - id: step_build_artifacts
          type: action
          label: "Build da Aplicação"
          name: fictitious-org/build-app-action@1.0.0
          inputs:
            app_version: "{{ app_version }}"
    - id: job_upload_s3
      label: "Upload dos Artefatos para S3"
      depends-on:
        - job_prepare_deploy
      steps:
        - id: step_upload_to_s3
          type: action
          label: "Upload para o 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: "Aplicar Infraestrutura no Ambiente"
      depends-on:
        - job_upload_s3
      steps:
        - id: step_apply_infra_plugin
          type: plugin
          label: "Plugin de Deploy Infra"
          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: "Notificar Sucesso do Deploy"
      depends-on:
        - job_apply_infra
      steps:
        - id: step_notify_slack
          type: action
          label: "Notificação Slack"
          name: fictitious-org/notify-slack-action@1.0.0
          inputs:
            environment: "{{ deployment_env }}"
            app_version: "{{ app_version }}"
            message: "Deploy da versão {{ app_version }} realizado com sucesso no ambiente {{ deployment_env }}."

Atenção!

Sempre que um Workflow possuir um targets para app ou infra. Todos os Plugins utilizados pelo Workflow devem ser do mesmo tipo app ou infra definidos no targets. E pertencerem à mesma Stack do Workflow.

Workflow do tipo reusable

O Workflow do tipo reusable executa Jobs genéricos. Sua principal característica é receber entradas (inputs) e gerar saídas (outputs), que podem ser usadas em outros Workflows. Isso torna o Workflow reutilizável em outros Workflows.

Exemplo:

Exemplo de um Workflow do tipo 'reusable'

schema-version: v1
kind: workflow
metadata:
  name: reusable-create-git-repo
  display-name: Reutilizável - Criar Repositório Git
  description: "Cria um repositório de código em um serviço de versionamento."
  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: "ID do Projeto"
      scope: default
      name: project_id
      type: text
      required: true
      help: "Informe o identificador do projeto no seu provedor de repositório."
    - label: "Nome do Projeto"
      scope: default
      name: project_name
      type: text
      required: true
      help: "Informe o nome do projeto no seu provedor de repositório."
    - label: "Nome do Repositório"
      scope: default
      name: repository_name
      type: text
      required: true
      help: "Informe o nome do repositório a ser criado."
  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: "Orquestração da criação do repositório"
      steps:
        - id: create_repository
          label: "Executa a ação de criação do repositório"
          name: fictitious-org/create-git-repository@0.1.0
          type: action
          inputs:
            project_id: "{{ project_id }}"
            project_name: "{{ project_name }}"
            repository_name: "{{ repository_name }}"

Dica!

Os outputs do Workflow possuem o comportamento semelhante ao computed-inputs. Para saber mais como usar os Outputs do Workflow, confira o conteúdo dos computed-inputs.

Workflow do tipo rollback

O Workflow do tipo rollback executa Jobs para retornar a versão de uma Aplicação ou Infraestrutura implantados. O campo targets define o tipo de recurso que será feito o rollback.

workflow.yaml

schema-version: v1
kind: workflow
metadata:
  name: rollback-infra-generic
  display-name: Rollback de Infraestrutura Genérica
  description: "Orquestra o rollback de uma infraestrutura para uma versão anterior."
  version: 1.0.0
spec:
  type: rollback
  label: Rollback de Infraestrutura
  targets:
    - infra
  docs:
    en-us: docs/en_us/rollback.md
    pt-br: docs/pt_br/rollback.md
  inputs:
    - label: "Ambiente"
      scope: default
      name: environment_id
      type: select
      required: true
      items:
        - dev
        - staging
        - production
      help: "Selecione o ambiente onde será realizado o rollback."
    - label: "Versão para rollback"
      scope: default
      name: rollback_version
      type: text
      required: true
      pattern: '^\d+\.\d+\.\d+$'
      help: "Informe a versão desejada para o rollback. Exemplo: 1.2.3"
  jobs:
    - id: job_prepare_rollback
      label: "Preparar rollback"
      steps:
        - id: step_validate_permissions
          type: action
          label: "Validar Permissões do Usuário"
          name: fictitious-org/validate-rollback-permission-action@1.0.0
          inputs:
            environment_id: "{{ environment_id }}"
    - id: job_execute_rollback
      label: "Executar rollback"
      depends-on:
        - job_prepare_rollback
      steps:
        - id: step_rollback_infra
          type: plugin
          label: "Executar Rollback de Infraestrutura"
          name: fictitious-org/rollback-infra-plugin@1.0.0
          inputs:
            environment_id: "{{ environment_id }}"
            rollback_version: "{{ rollback_version }}"
    - id: job_notify_rollback
      label: "Notificar rollback"
      depends-on:
        - job_execute_rollback
      steps:
        - id: step_notify_slack
          type: action
          label: "Notificação Slack"
          name: fictitious-org/notify-slack-action@1.0.0
          inputs:
            environment: "{{ environment_id }}"
            version: "{{ rollback_version }}"
            message: "Rollback para versão {{ rollback_version }} executado com sucesso no ambiente {{ environment_id }}."

Workflow do tipo starter

O Workflow do tipo starter executa a aplicação de Plugins para a criação de uma Aplicação ou Infraestrutura pelo STK CLI. Para criar uma Aplicação ou Infraestrutura com um Workflow pelo Portal da plataforma StackSpot EDP, use o tipo do tipo create.

O uso de Starters para criar Aplicações ou Infraestruturas ainda é possível, mas está depreciado. O campo targets define o tipo de recurso que será criado.

Exemplo de um Workflow do tipo 'starter'

schema-version: v1
kind: workflow
metadata:
  name: starter-app-node-nest-api
  display-name: Starter App Node/Nest API
  description: "Provisiona a criação de uma API Node.js com 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: "Nome da Squad)"
      scope: default
      name: squad_name
      type: text
      required: true
      pattern: '^[a-z]+$'
      help: "Informe o nome da squad responsável. Use apenas minúsculas. Exemplo: squadx."

    - label: "Contexto do Projeto (kebab-case)"
      scope: default
      name: project_context
      type: text
      required: true
      pattern: '^[a-z0-9]+(-[a-z0-9]+)*$'
      help: "Informe o contexto do projeto em kebab-case. Exemplo: meu-projeto-api."

    - label: "Adicionar suporte ao MongoDB?"
      scope: default
      name: add_mongodb
      type: bool
      required: true
      default: false
      help: "Adiciona as dependências do MongoDB ao projeto."

    - label: "Adicionar suporte ao PostgreSQL?"
      scope: default
      name: add_postgresql
      type: bool
      required: true
      default: false
      help: "Adiciona as dependências do PostgreSQL ao projeto."

    - label: "Adicionar suporte ao Redis?"
      scope: default
      name: add_redis
      type: bool
      required: true
      default: false
      help: "Adiciona as dependências do Redis ao projeto."

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

  jobs:
    - id: job_apply_plugins
      label: "Aplicação dos Plugins de App"
      steps:
        - id: step_apply_app_plugin
          type: plugin
          label: "Aplicar Plugin Base Node/Nest"
          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: "Aplicar Plugin MongoDB"
          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: "Aplicar Plugin PostgreSQL"
          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: "Aplicar Plugin Redis"
          when: "{{ add_redis }}"
          name: fictitious-org/app-node-nest-add-redis@1.0.0
          inputs:
            project_name: "{{ project_name }}"

Comparativo dos tipos de Workflow

A seguir, um resumo comparando o uso de cada tipo de Workflow para ajudar você durante a criação de Workflows.

1. create

   • Orquestra a criação de uma Aplicação ou Infraestrutura.
   • Executa Plugins e outros Workflows para provisionar recursos.
   • Usado tanto no Portal quanto no STK CLI.
   • Substitui o Starter para criação via Portal.

2. deploy

   • Realiza o deploy de uma Aplicação ou Infraestrutura já criada.
   • Garante que todos os Plugins e Actions foram aplicados.
   • Exige parâmetros obrigatórios como ambiente.
   • Não executa novamente Hooks declarativos.

3. reusable

   • Executa Jobs genéricos e flexíveis.
   • Recebe inputs e gera outputs reutilizáveis em outros Workflows.
   • Ideal para lógica compartilhada entre diferentes processos.

4. rollback

   • Executa Jobs para reverter uma Aplicação ou Infraestrutura para uma versão anterior.
   • Exige informações como ambiente e versão de rollback.
   • Focado em restaurar estados anteriores.

5. starter

   • Executa a aplicação de Plugins para criar Aplicação ou Infraestrutura via STK CLI.
   • Uso de Starters está depreciado, mas ainda disponível.
   • Não recomendado para novos projetos; prefira o tipo create.

Tipo	O que faz	O que não faz	Onde usar
create	Cria Aplicação/Infraestrutura, orquestra Plugins e Workflows	Não faz deploy, não executa rollback, não é reutilizável em outros Workflows	Portal e STK CLI
deploy	Realiza deploy de recursos já criados, aplica Plugins/Actions de deploy	Não cria recursos, não executa rollback, não é reutilizável	Portal e STK CLI
reusable	Executa lógica genérica, recebe inputs e gera outputs para outros flows	Não cria/faz deploy de recursos diretamente, não faz rollback	Em outros Workflows
rollback	Reverte Aplicação/Infraestrutura para versão anterior	Não cria/faz deploy de recursos, não é reutilizável, não orquestra criação	Portal e STK CLI
starter	Cria Aplicação/Infraestrutura via CLI usando Plugins predefinidos	Não faz deploy, rollback, não recomendado para novos projetos, não disponível no Portal	STK CLI (depreciado)

Dicas!

• Prefira o tipo create para novos projetos, pois substitui Starters e é mais flexível.
• Use deploy para processos de publicação e atualização de recursos.
• Centralize lógicas comuns em Workflows do tipo reusable para facilitar manutenção e reuso.
• Utilize rollback para restaurar versões anteriores de recursos de forma controlada.
• Evite criar novos Workflows do tipo starter; utilize apenas para manter compatibilidade com projetos antigos.