Action

In this section, you will find Action's structure and types.

About Actions

At StackSpot, Actions is a structure that gives intelligence to scripts to execute automation locally on your machine. It is possible to use inputs and files that interact with your script to automate a process, or even facilitate bureaucratic processes in your organization.

In addition to creating your Actions, you can publish and distribute them in your organization so that everyone follows the same type of automation process that the Action executes.

Actions are executed only by the STK CLI, and can contain, for example, scripts that execute:

Seamlessly connect with other systems via StackSpot integration;
Carry out developer-related tasks, such as generating a GitHub repository.

Types of Action

The attribute --type defines the Action types. The difference among the types is the specific attributes in the spec: field of each Action.

See below the types of Actions and specific attributes for each:

Shell Actions

Shell Actions have a shell object in the specification with the following attributes:

workdir: Folder where you need to execute the Action;
requirements-check: Check every dependency to map if the requirements to execute an Action are present;
- check-command: It is an attribute that defines and executes the command that checks the dependency;
- info: It is an error message displayed if the dependency check fails;
script: It defines the commands that will execute the shell in the operating system. Each operating system can have a different command. StackSpot support Linux, MacOs and Windows.

See an example:

'shell' Action Example
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}}!"

To address more complex scripts with conditional actions and interpolating many values, interpolate these values into a file before executing the Action script. Consider the following script:

Sample 'flag.sh' shell script that demonstrates the scenario where the script will not be executed in the Action body.
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

To execute this script, your Action needs inputs to capture and interpolate the values in a file (it can be a text file or script). The Action will need:

Create the "templates" folder.
Add a text file or shell script and place the script in this file.
Edit the inputs of your Action that correspond to the shell script or add JINJA expressions in the script that correspond to the Action's inputs.
Use the component_path property in the script field of the Action. This property has the following syntax:

Syntax of using 'component_path' in the shell Action.
{{component_path}}/[file_path]

The Action will have the following structure:

Folder structure of an Action with the folder 'templates/*.txt, *.sh'
.
├── action.yaml
├── docs
│   ├── en-us
│   │   └── docs.md
│   └── pt-br
│       └── docs.md
└── templates
    └── flag.sh

Action example with 'component_path' to execute complex shell scripts.
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

See more details about component_path in Action template content and metadata.

Python Actions

Python Actions has a Python object in the specification with the following attributes:

workdir: The folder you need to execute the Action;
script: The path to the Python script will be executed.

See an example:

'python' Action example
spec: 
  type: python
# ... other spec attributes ...
  python: # python object
    workdir: .
    script: script.py  

Structure of the file and Actions metadata

When you create an Action, an initial structure is generated so that you can develop your Action script.

The Action has a folder with the name given when it was created and a configuration file, the action.yaml file. In addition to specific files for the type of Action chosen.

The files' structure

The example below shows an Action with the possible file structures:

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

STK CLI generates the Action structure, with the stk create action command. It supports the structure the parameter --type defines. See the types below:

Example of each file structure:

To test, execute the stk create action in your terminal to create for each Action type. See the files for the structure that is generated below:

Action type: shell
Action type: python

stk create action shell-action --type shell

~ ➜  shell-action  
└── action.yaml

stk create action python-action --type python

~ ➜  python-action  
├── action.yaml  
└── script.py  

Action (`action.yaml` file) metadata

The Action's configuration file or metadata is an action.yaml and it has details about the Action. The YAML has specific data for each type, so it changes according to the Action type.

See the examples below:

Basic action.yaml: 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

Actions consist of four primary attributes within their structure, which are mandatory for all Actions, in addition to other optional attributes. Here's an example for reference:

Action default attributes
Common attributes of Action's specification

An 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: Specifications version;
kind: It always has action value;
metadata: It is common metadata;
- name: Action name;
- display-name (Optional): Action name to display to the user;
- description: Describe the Action's purpose;
- version: Action's version;
- picture (Optional): Image displayed on the StackSpot Platform.

Common action.yaml file specification
# ... other action attributes ...
spec: 
  type: python
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  repository: https://github.com/some-org/my-action
  inputs:
    - label: Connection Interface for my bucket-1
      name: bucket-1
      type: required-connection
      connection-interface-type: aws-s3-conn
    - label: Who are you?
      name: user_name
      type: text
      required: false
      pattern: '([A-Z][a-z]+)+'
      help: 'Inform your name'
  python:
    workdir: .
    script: script.py
# ... type dependent structure ...                            

type: Action types. It can be:
- shell
- python
docs: Path to the Markdown files with the contents of the Action's Portuguese and English documentation on the Portal;
requires (Optional): Define the Connection Interfaces the Action depends on.

info

When you create an Action to add it with an Infra Plugin, you must select at least one of the Connection Interfaces generated by the Plugin. To find out more, go to the guides:

inputs (Optional): Define the Action inputs. The same Plugins' inputs are allowed;
repository (Optional): Git's repository where the Action's code will be displayed on the Platform.

Next Steps

For more information about Actions, follow the guides below: