Workflows

AllSpice Actions Workflows

Workflows are the scaffolding of your automation. They are the grouping element that stores the automation code. They are defined by easy to read and write YAML files within your repository. To use workflows, you must create and store them in a folder inside your repo with the following path: your-repository-name/.allspice/workflows/your-workflow-file.yml

Structure of a workflow file

Every workflow follows a simple ordered structure that contains multiple sections where you need to define child elements that represent your automation code. The structure is as follows:

1. Triggers

Triggers define how and when the workflow is activated. Triggers can be set based on various events or conditions within your repository to initiate the workflow.

2. Jobs

Jobs are groupings of Steps. Jobs run in parallel by default.

3. Runs-on: Software Container

Each automation has to be run by a virtual instance that is properly configured to execute your scripts and tasks. To use those virtual instances you need to first define them in this section.

Ubuntu LTS 2024: As of now, our runners are only ubuntu compatible so you would need to define an ubuntu runner to use AllSpice actions.

4. Load Dependencies

After defining the instance, it’s time to load
- Software Libraries: Include necessary software libraries required for the workflow.
- Design Files: Load relevant design files needed for processing.
- API Tools: Integrate API tools required for the workflow operations.
- Secrets/Tokens/Keys: Securely load secrets, tokens, and keys necessary for accessing various services.

5. Run Steps
- Add-ons: Use pre-built no-code automation programs for specific tasks.
- Python: Write programs in Python and access the AllSpice.io API via the py-allspice Python module.
- C/C++: Utilize the same language as firmware development but to write scripts.
- JavaScript, Rust: Write scripts in these other common languages as needed.
- Any Programming Language: You can use any programming language that can run on Debian/Ubuntu Linux to write and run scripts.

6. Store Generated Data
- BOMs, Manufacturing Files: Store generated Bill of Materials and manufacturing files.
- Design Review Reports: Save reports from design reviews.
- Release Files: Archive final release files.

Wokrflow files are written in YAML

YAML (YAML Ain't Markup Language) is a human-readable data serialization language commonly used for configuration files and data exchange between languages. Its simplicity and readability make it an ideal choice for defining workflows in a structured and understandable manner.

YAML Syntax Basics

Before diving into workflows, it's important to understand some basic YAML syntax rules:

• Indentation: YAML uses indentation to represent the structure.

• Key-Value Pairs: Data is represented using key-value pairs separated by a colon and a space (key: value).

• Lists: Lists are indicated by a hyphen and a space (- item).

• Comments: Comments start with a hash symbol (#) and continue to the end of the line.

Example:

# This is a comment
name: Example Workflow
on: push
jobs:
  build:
    steps:
      - run: echo "Checking PCB revision"

Example Workflow File

An AllSpice Actions workflow is defined in a YAML file located in the .allspice/workflows/ directory of your repository. The workflow file consists of several key sections:

• name: An optional identifier for the workflow.

• on: Specifies the event(s) that trigger the workflow.

• jobs: Defines one or more jobs that the workflow will execute.

Example:

name: CI Pipeline
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: make test

Workflow Best Practices

• Consistent Indentation: Always check your indentation

• Descriptive Names: Use the name field for workflows, jobs, and steps to improve readability.

• Reusability: Consider creating reusable workflows or actions for common tasks.

• Version Pinning: When using actions, specify exact versions to ensure consistent behavior.

Example of Version Pinning:

uses: actions/checkout@v3.5.2

Conclusion

Understanding the YAML syntax is crucial for leveraging the full potential of AllSpice Actions workflows. By mastering the structure and components outlined in this guide, you can create powerful automation pipelines that enhance your development lifecycle.

Check out our documentation on Triggers to see how to make your Workflows responsive and flexible.