Pular para o conteúdo principal
Versão: v1.0.0

O que é Action

Nesta seção, você encontra as estrutura e quais são os tipos de Actions.


Sobre Actions

Na StackSpot, Actions são automações que você cria para facilitar tarefas em projetos de software. Elas permitem que scripts sejam executados automaticamente no seu computador, usando entradas (inputs) e arquivos para interagir com o processo.

Você pode criar, publicar e compartilhar Actions na sua organização. Assim, todos podem usar o mesmo processo automatizado e garantir padronização nas tarefas.

As Actions funcionam apenas pelo STK CLI (ferramenta de linha de comando da StackSpot). Elas podem, por exemplo:

  • Integrar sistemas diferentes usando a StackSpot;
  • Executar tarefas e comandos automaticamente na máquina da pessoa desenvolvedora.

Tipos de Actions

O tipo de uma Action é definido pelo atributo --type na sua configuração. Cada tipo tem atributos específicos dentro do campo spec: no arquivo de configuração da Action.

Confira nas próximas seções os tipos de Actions disponíveis e quais atributos cada uma utiliza.

Shell Actions

Actions do tipo shell possuem em sua especificação um objeto shell com os seguintes atributos:

  • workdir: pasta onde a Action deve ser executada;
  • requirements-check: verificação de dependências para mapear se todos os requisitos para executar a Action estão presentes;
    • check-command: atributo presente em cada verificação. Define e executa o comando que verifica a dependência;
    • info: mensagem de erro exibida caso o comando executado retorne falha na verificação da dependência;
  • script: define os comandos que serão executados no shell do sistema operacional. Podem ser definidos comandos diferentes para cada sistema operacional suportado, os sistemas suportados são Linux, MacOs e Windows.

Confira um exemplo:

Exemplo com um trecho da especificação de uma Action do tipo 'shell' do arquivo action.yaml
spec: 
  type: shell
# ... other spec attributes ...
  shell: # shell object
    workdir: .
    requirements-check:
      - check-command:
          linux: |
            git --version
          mac: |
            git --version
          windows: |
            git --version
        info: "Git is not installed!"
    script:
      linux: |
        echo "Hello {{inputs.user_name}}!"
      mac: |
        echo "Hello {{inputs.user_name}}!"
      windows: |
        echo "Hello {{inputs.user_name}}!"

Para scripts mais complexos com ações condicionais e interpolação de muitos valores, você precisa interpolar esses valores primeiro em um arquivo para depois executar o script da Action. Considere o script a seguir:

Script shell 'flag.sh' de exemplo que demonstra o cenário em que o script não será executado no corpo da Action.
if [ ! -z "{{inputs.verbose}}" ]; then
    echo "STK DEPLOY PLAN FLAGS = $FLAGS"
fi
$HOME/.stk/bin/stk use workspace {{ inputs.workspace }}

FLAGS=$(echo "--env {{ inputs.environment }} --version {{ inputs.version_tag }}")

if [ ! -z "{{ inputs.branch }}" ]; then
  FLAGS=$(echo "$FLAGS --branch ${{ inputs.branch }}")
fi

if [ ! -z "{{ inputs.open_api_path }}" ]; then
  FLAGS=$(echo "$FLAGS --open-api-path ${{ inputs.open_api_path }}")
fi

if [ ! -z "{{ inputs.dynamic_inputs }}" ]; then
  FLAGS=$(echo "$FLAGS {{ inputs.dynamic_inputs }}")
fi

if [ ! -z "{{ inputs.verbose }}" ]; then
  echo "STK DEPLOY PLAN FLAGS = $FLAGS"
fi

$HOME/.stk/bin/stk deploy plan $FLAGS

Para executar esse script, a sua Action precisa de inputs para capturar e interpolar os valores em um arquivo (pode ser um arquivo de texto ou script). A Action vai precisar:

  1. Crie uma pasta chamada templates dentro da sua Action.
  2. Coloque o seu script (arquivo de texto ou shell) dentro dessa pasta.
  3. No arquivo de configuração da Action, edite os inputs da sua Action que correspondem com o script shell ou adicione as expressões JINJA no script que correspondem com os inputs da Action.
  4. Use a propriedade component_path no campo script da Action. Esta propriedade possui a seguinte sintaxe:

O campo component_path serve para localizar arquivos dentro da pasta templates durante a execução da Action.

Sintaxe do uso do 'component_path' na Action do tipo shell.
{{component_path}}/[file_path]

A Action terá a seguinte estrutura:

Estrutura da pasta de uma Action com a pasta 'templates/*.txt, *.sh'
.
├── action.yaml
├── docs
│   ├── en-us
│   │   └── docs.md
│   └── pt-br
│       └── docs.md
└── templates
    └── flag.sh
Exemplo de Action com 'component_path' para executar scripts shell complexos.
schema-version: v3
kind: action
metadata:
  name: flag-script
  display-name: flag-script
  description: Test flag script
  version: 1.0.0
spec:
  type: shell
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  inputs:
    - label: Verbose Mode
      name: verbose
      type: bool
      required: false
    - label: Workspace
      name: workspace
      type: text
      required: true
    - label: Environment
      name: environment
      type: text
      required: true
    - label: Version Tag
      name: version_tag
      type: text 
      required: true  
    - label: Branch
      name: branch
      type: text
      required: false
    - label: Open API Path
      name: open_api_path
      type: text
      required: false
    - label: Dynamic Inputs
      name: dynamic_inputs
      type: text   
      required: false
  shell:
    workdir: .
    script:
      linux: cat {{ component_path }}/flag.sh
      mac: cat {{ component_path }}/flag.sh
      windows: type {{ component_path }}/flag.sh

Confira mais detalhes sobre o component_path em Conteúdo de templates e metadados da Action.

Python Actions

Actions do tipo python possuem em sua especificação um objeto python com os seguintes atributos:

Exemplo com um trecho da especificação de uma Action do tipo 'python' do arquivo action.yaml
spec: 
  type: python
# ... other spec attributes ...
  python: # python object
    workdir: .
    script: script.py
  • workdir: pasta onde a Action deve ser executada;
  • script: caminho para o script Python que será executado.

Estrutura de arquivos e metadados de uma Action

Quando você cria uma Action, uma estrutura inicial é gerada para que você possa desenvolver o script da sua Action.

A Action possui uma pasta com o nome que foi fornecido na sua criação e um arquivo de configuração, o arquivo action.yaml. Além de arquivos específicos para o tipo de Action escolhido.

Estrutura de arquivos

O exemplo ilustra uma Action com todas as variações dos tipos possíveis de estrutura de arquivos.

~ ➜ my-action-name-folder  
├── templates
├── docs
├── action.yaml  
├── script.py  
└── Dockerfile

A estrutura de uma Action é gerada pelo STK CLI, com o comando stk create action suportando os seguintes tipos de estrutura definidos pelo parâmetro --type:

Exemplos de cada estrutura de arquivo por tipo

Para testar, execute em seu terminal o comando stk create action para criar cada um dos tipos de Actions e confira a estrutura gerada por cada um.

stk create action shell-action --type shell
~ ➜  shell-action  
└── action.yaml

Metadados da Action (arquivo action.yaml)

O arquivo de configuração ou metadados de uma Action é o action.yaml. Nele estão descritas todas as informações sobre a Action.

Esse arquivo pode mudar de acordo com o tipo da Action, pois existem alguns dados específicos para cada tipo.

Exemplo da estrutura do action.yaml básico de uma Action do tipo python
schema-version: v3
kind: action
metadata:
  name: python-action-test
  display-name: python-action-test
  description: Describe your action explaining its purpose.
  version: 1.0.0
spec:
  type: python
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  inputs:
    - label: What is your name?
      name: user_name
      type: text
      required: false
      pattern: '^[A-Za-z]+(?:\s[A-Za-z]+)*$'
      help: 'Inform your name'
  python:
    workdir: .
    script: script.py

As Actions possuem em sua estrutura quatro atributos principais que são obrigatórios para todas as Actions além dos atributos comuns:

Início de um arquivo action.yaml
schema-version: v3
kind: action
metadata:
  name: my-action
  display-name: my-action
  description: python action test
  version: 1.0.0
spec:
# ... other action specs ...
  • schema-version: versão da especificação;
  • kind: sempre possui o valor action;
  • metadata: metadados comuns;
    • name: nome da Action;
    • display-name (Opcional): nome Action que será apresentado ao usuário no Portal;
    • description: descrição da Action informando o seu propósito;
    • version: versão da Action;
    • picture (Opcional): imagem exibida no Portal para representar a Action publicada.

Próximos Passos

Para mais informações sobre Actions, acesse os guias: