Action

In this section, you will find details about Actions structure and its types.

About Actions

Actions refer to automated tasks that you can perform on your computer. Here are a few examples of Actions:

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

Local Actions

Execute tasks on your local computer to automate actions during development or local testing.
It's important to note that Local Actions only work with the STK CLI (Stackspot CLI).

Structure of the file and Actions metadata

Upon creating an Action, it comes with an initial structure in place. This framework serves as the foundation upon which you can develop the source code for your custom Action.

This structure typically includes a folder named after the Action, and you can locate it alongside a configuration file named action.yaml. The remaining files are automatically generated based on the type of Action you're working with.

The structure of the files

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

➜ my-action-name-folder
├── 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 with the Action type. You will view the structure for each type. See 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: v1
kind: action
metadata:
  name: my-action
  display-name: my-action
  description: python action test
  version: 0.0.1
spec:
  type: python
  requires:
    - connection-interface
  inputs:
    - label: Type some label
      name: random-name
      type: text
      required: false
      pattern: '([A-Z][a-z]+)+'
      help: 'Inform your resource name (e.g.: Client)'
  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
// highlight-start
schema-version: v1
kind: action
metadata:
// highlight-end
  name: my-action
  display-name: my-action
  description: python action test
  version: 1.0.0
// highlight-next-line
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: 
// highlight-start
  type: container
  about: about.md
  implementation: implementation.md
  release-notes: release-notes-1.0.0.md
  requirementes: requirements.md
  repository: https://github.com/some-org/my-action
  requires:
    connection-interface:   
      - github-connection-interface
  inputs: 
// highlight-end    
    - label: Repository name
      type: text
      name: name
    - label: Organization
      type: text
      name: org
    - label: Personal Access Token
      type: text
      name: token  
      condition: 
        variable: action.scope
        operator: "=="
        value: local
# ... type dependent structure ...                

type: Action types. It can be:
- shell
- python
requires (Optional): Define the Connection Interfaces the Action depends on.
inputs (Optional): Define the Action inputs. The same Plugins' inputs are allowed.
about (Optional): Path to a Markdown file with the Action's "About" content in the Platform.
implementation (Optional): Path to a Markdown file with the Action's "Implementation" content in the Platform.
release-notes (Optional): Path to a Markdown file with the Action's "Release Notes" content in the Platform.
requirements (Optional): Path to a Markdown file with the Action's "Requirements" content in the Platform.
repository (Optional): Git's repository where the Action's code will be displayed on the Platform.

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 linus, macos and windows.

See an example:

'shell' Action Example
spec: 
  type: shell
# ... other spec attributes ...
  shell: # shell object
    workdir: .
    requirements-check: 
      - check-command:
          windows: |
            echo "Hello World!"
          linux: |
            echo "Hello World!" 
          mac: |
            echo "Hello World!"
        info: "Failed saying hello to world."              

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.