Executar Workflows StackSpot via API

A execução do Workflow da StackSpot pode ser feita via API utilizando a sua credencial de usuário (PAT) ou de serviço. A seguir você confere os requisitos e passos necessários para integrar a execução de Workflows em suas requisições.

Pré-requisitos

Se você escolher usar Credenciais de Serviço, confira como criar Credenciais de Serviço;
Se você optar por usar Credenciais de Usuário (PAT - Personal Access Token), confira como criar um Token de Acesso Pessoal;

Permissões necessárias:

O token utilizado (serviço ou usuário) deve possuir a permissão workflow:dispatch.
Se não possuir, a API retorna HTTP 403 com mensagem de permissão insuficiente.

Passo 1. Gerar o Token de Acesso (JWT)

Você precisa de um Personal Access Token (PAT) ou Credencial de Serviço.

Confira um exemplo de requisição para obter o JWT:

curl --request POST \
  --url https://iam-auth-ssr.stackspot.com/test/oidc/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'client_id=<seu_client_id>' \
  --data 'client_secret=<seu_client_key>' \
  --data 'grant_type=client_credentials'

Substitua <seu_client_id> e <seu_client_key> pelos valores do seu PAT.
O retorno será um JSON com o campo access_token. Copie e guarde esse valor.

Passo 2. Disparar o Workflow

Corpo da Requisição (`/v3/workflows/dispatch`)

{
  "injectScmIntegration": false,           // (opcional)
  "workspace": {                           // (opcional, mas recomendado)
    "id": "workspace_id",                  // (obrigatório se workspace for enviado)
    "slug": "workspace_slug"               // (obrigatório se workspace for enviado)
  },
  "workflow": {                            // (obrigatório)
    "name": "studio-slug/workflow-slug@1.0.0", // (obrigatório)
    "label": "Descrição do workflow",      // (obrigatório)
    "type": "starter",                     // (obrigatório) - Ex: starter, create, deploy, etc.
    "inputs": {                            // (obrigatório, pode ser objeto vazio)
      "input1": "valor1"
    },
    "targets": [],                         // (opcional, depende do tipo do workflow)
    "env": {                               // (opcional, depende do workflow)
      "id": "env_id",                      // (obrigatório se env for enviado)
      "slug": "env_slug"                   // (obrigatório se env for enviado)
    },
    "base_workflow_type": "starter"        // (opcional)
  },
  "frontData": {                           // (opcional)
    "qualquerCoisa": {}
  },
  "requestBy": {                           // (opcional, obrigatório se usar credencial de serviço)
    "userId": "user_id"
  }
}

Campos da Requisição

1. `injectScmIntegration` (opcional, boolean)

Descrição: se true, injeta integração com SCM (GitHub, GitLab, etc) configurada no Workspace.
Default: false
Quando usar: se o Workflow precisa acessar repositórios SCM.

2. `workspace` (opcional, objeto)

Descrição: identifica o Workspace onde o Workflow será executado.
Campos obrigatórios:
- id (string): ID do Workspace.
- slug (string): slug do Workspace.
Quando usar: quase sempre necessário, exceto em Workflows globais.

3. `workflow` (obrigatório, objeto)

Descrição: define qual Workflow será executado e seus parâmetros.
Campos obrigatórios:
- name (string): nome completo do Workflow (Exemplo: "studio-slug/workflow-slug@1.0.0").
- label (string): descrição legível do Workflow.
- type (string): tipo do Workflow (starter, create, deploy, rollback, reusable, extension).
- inputs (objeto): parâmetros de entrada do Workflow (pode ser vazio {}).
Campos opcionais:
- targets (array): alvos do Workflow (ex: [{ "id": "...", "type": "app" }]). É necessário para alguns tipos de Workflow.
- env (objeto): ambiente de execução. Necessário para Workflows de deploy, rollback, etc.
  - id (string): ID do ambiente.
  - slug (string): slug do ambiente.
- base_workflow_type (string): tipo base do Workflow. Ele é opcional e geralmente é igual ao type).

4. `frontData` (opcional, objeto)

Descrição: dados extras para rastreabilidade ou uso pelo Front-end.
Quando usar: se precisar passar informações adicionais não usadas pelo Back-end.

5. `requestBy` (opcional, objeto)

Descrição: identifica o usuário responsável pelo dispatch.
Campos:
- userId (string): ID do usuário.
Quando usar: Obrigatório se usar credencial de serviço (PAT). Não deve ser enviado se usar credencial de usuário.

Campo	Obrigatório	Observação
`injectScmIntegration`	Não	Default: false
`workspace`	Não	Recomendado, obrigatório para maioria dos casos
`workflow`	Sim	Sempre obrigatório
`frontData`	Não
`requestBy`	Não	Obrigatório se usar credencial de serviço (PAT)

Exemplos de Respostas

Sucesso: HTTP 200/201 com detalhes da execução do workflow.
Permissão insuficiente: HTTP 403 com mensagem clara.

2.1. Exemplo com credencial de serviço

Atenção!

Se você usar credencial de serviço, inclua o campo requestBy no corpo da requisição, informando o userId responsável pelo dispatch.

Executar Workflow com credencial de serviço.
curl --request POST \
  --url https://workflow-workflow-api.stackspot.com/v3/workflows/dispatch \
  --header 'Authorization: Bearer <seu_jwt>' \
  --header 'Content-Type: application/json' \
  --data '{
    "injectScmIntegration": true,
    "workspace": {
      "id": "7N10882JBMX62368434Y65SZZ3",
      "slug": "workspace-slug-name"
    },
    "workflow": {
      "name": "studio-slug/workflow-slug@1.0.0",
      "label": "A workflow which runs something",
      "type": "starter",
      "inputs": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "targets": [],
      "env": {
        "id": "5NBF23P01S1HD2KWKNYWRGZN64",
        "slug": "string"
      },
    },
    "requestBy": {
      "userId": "string"
    }
  }'

Substitua <seu_jwt> pelo token obtido na etapa anterior.
O campo userId deve ser o identificador do usuário responsável.

2.2. Exemplo com credencial de usuário

Atenção!

Se usar credencial de usuário (PAT), NÃO inclua o campo requestBy.

Executar Workflow com Credencial de Usuário (PAT).
curl --request POST \
  --url https://workflow-workflow-api.stackspot.com/v3/workflows/dispatch \
  --header 'Authorization: Bearer <seu_jwt>' \
  --header 'Content-Type: application/json' \
  --data '{
    "injectScmIntegration": true,
    "workspace": {
      "id": "7N10882JBMX62368434Y65SZZ3",
      "slug": "D6iptT6joDYpFL32pPx-48FJd8bMBzvDRvFb"
    },
    "workflow": {
      "name": "studio-slug/workflow-slug@1.0.0",
      "label": "A workflow which runs something",
      "type": "starter",
      "inputs": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "targets": [],
      "env": {
        "id": "5NBF23P01S1HD2KWKNYWRGZN64",
        "slug": "string"
      },
    },
  }'

Informação Adicional

O responsável pelo dispatch é registrado/auditado.
Se um Workflow estiver com o status "pendente" (pending), ele será atualizado automaticamente para "cancelado" após 72 horas.

Pré-requisitos

Passo 1. Gerar o Token de Acesso (JWT)

Passo 2. Disparar o Workflow

Corpo da Requisição (/v3/workflows/dispatch)

Campos da Requisição

1. injectScmIntegration (opcional, boolean)

2. workspace (opcional, objeto)

3. workflow (obrigatório, objeto)

4. frontData (opcional, objeto)

5. requestBy (opcional, objeto)