How does AllSpice Actions work?

Background

Here is a quick high-level refresher of the different parts of Actions. We’ll go into more details, later in this article.

Actions overview

Actions is the name of our automation features.

Workflows are files that define how to set-up and run pre-existing or custom Add-Ons or scripts.
Examples:

.allspice/workflows/your_workflow.yml

.allspice/workflows/generate_BOM.yml

.allspice/workflows/create_release.yml

Triggers run the workflow files automatically after common actions like pushing files to AllSpice. They are defined in the workflow files.

Task (steps) setup the runner environment, run existing Add-ons or custom scripts. These can use out-of-the-box modules like Add-ons, or execute code in any language, and connect to any external API.

Runners trigger the Workflows, setup the environments, execute Tasks, store files, and report pass/fail status.

Actions tour

Try our interactive tour that shows how each part of the Actions interface works.

Workflows

Workflows are the scaffolding of your automation. They are the code that loads the automation code. Workflows are easy to read and write yaml files.

Define Triggers

• Set how and when the workflow is triggered (see Triggers, below)

Load software container

• Ubuntu LTS 2024 (Debian flavored Linux distro)

Load dependencies

• Software libraries

• Design Files

• API tools

• Secrets/tokens/keys

Run Tasks

• Add-ons - Pre-built no-code automation programs

• Python - Programs can be written in python and access our AllSpice.io API via our py-allspice python module.

• C/C++, use the same language as firmware development

• Javascript, Rust

• Any programming language that can run on Debian/Ubuntu Linux

Extend existing automation

Workflows can be broken into modules, called Add-ons that can be reused and extended.

Store generated data

• BOMs, Manufacturing files

• Design review reports

• Release files

Simple workflow example

The first demo shows the minimum workflow to print “Hello World”.

https://hub.allspice.io/Actions-demos/.allspice/workflows/00-Workflow-syntax-minimal.yml

name: Workflow-hello-world

on: 
  push:
  issues:
    # Trigger on issue open, close, or reopen
    types: [opened, closed, reopened]

jobs:
  Job-Hello-World:
    runs-on: ubuntu-latest
    steps:
      - name: "Print Hello World 🔎" 
        run: echo "Hello World"      

You can see that it triggers on push, and whenever an issue is opened, closed, or reopened

The only thing needed to set up a basic Actions runner is to use runs-on: ubuntu-latest, the rest is automatic.

The command echo “Hello World” is just a unix shell script.

Anatomy of a workflow

This second workflow shows a minimal workflow, but with comments to explain each part of the YAML file.

https://hub.allspice.io/Actions-demos/.allspice/workflows/01-Workflow-syntax-commented.yml

# This is a basic workflow to help you get started with Actions
# Lines beginning with a `#` are comments, and only intended to help reviewers understand the script
# Actions documentation: https://learn.allspice.io/docs/actions-cicd
# This file is written in YAML syntax, to learn more about YAML visit https://learn.allspice.io/docs/yaml

# Workflow name
name: Workflow-syntax-commented

# Workflow triggers on
# To learn more about triggers, visit https://learn.allspice.io/docs/actions-triggers
on: 
  # Workflow is triggered if any of the following events occur
  # i.e. Logical OR of triggers, i.e. trigger on push or issues

  # Trigger on push
  push:

  # Trigger on issues
  issues:
    # Trigger on issue open, close, or reopen
    types: [opened, closed, reopened]


# Workflow jobs
# Jobs run in parallel by default
# To run jobs in sequence, create multiple steps in a job
jobs:

  # Job name
  Job-Hello-World:
    
    # Set up server container using Ubuntu operating system (Debian based Linux distribution)
    # To learn more about Ubuntu, visit https://ubuntu.com/
    runs-on: ubuntu-latest

    # Job steps
    # Steps run in sequence on the runner machine
    # To make steps run in parallel, create multiple jobs
    steps:

      # Job steps start with - name: "Step name"
      - name: "Print Hello World 🔎" 
        
        # run keyword specifies the shell command to run
        # The shell command is a simple echo command to print "Hello World"
        # The command is run in the runner machine
        # To learn more about shell commands, visit https://www.shellscript.sh/
        run: echo "Hello World"

      - name: "Multiline shell command 🔎"
        
        # The shell command is a simple echo command to print two lines of text
        # The | pipe character is used to specify a multiline command
        run: |
          echo "This is the first line"
          echo "This is the second line"          

Triggers

Triggers are events that kick off workflows

Triggers are defined in a workflow file and are named after familiar Git commands push, pull_request (Design Review), issues, and release.

Here is part of an example workflow file:

# .allspice/workflows/your_workflow.yml
name: Generate BOM
run-name: ${{ allspice.actor }} is testing out AllSpice Actions 🚀
on:
  # Add your triggers here
  # You can use more than one trigger to run the same code
  push:
  issues:
    types: [opened, closed, reopened]

jobs:
  Your_job:
   # Your job steps

Example triggers

• on push

  • Generate BOM

  • Check part numbers against component allow-list

  • Generate COGS

  • Check DRC rules are correct

• on merge pull_request closed

  • Create release fabrication package

    • Copy approved files from design review to release zip file

    • Check file format and naming conventions have been used

      • Check and filter out problematic naming conventions PCB1234-V2_thisone-revG.pcb

  • Update PLM

  • Generate archival/compliance Design Review package of checklist/comments/attachments

  • Add firmware from linked repos

• on release

  • Notify CM/JDM

  • Notify Planning/Purchasing

  • Backup/distribute files

• on issue / pull_request_review_comment

  • New part request workflow

  • Smart comments allow you to add your own #tags in comments to trigger software

    • Create issue from comment

    • Add new checks to the main checklist from a comment

  • Integrate your native issue tracking / comment system using Actions or Webhooks

List of triggers

For pull_request events, in GitHub Actions, the ref is refs/pull/:prNumber/merge, which is a reference to the merge commit preview. However, AllSpice.io has no such reference. Therefore, the ref in AllSpice.io Actions is refs/pull/:prNumber/head, which points to the head of pull request rather than the preview of the merge commit.

Tasks (steps)

Tasks are the verbs of Actions. They are the individual commands that are run. Tasks can take many forms

Add-ons

Add-ons are pre-configured Actions modules that can be called from any repo. They have a API with parameters to help you configure the Add-on to your project

• AllSpice provides a list of Add-ons

• Use/Share community Add-ons

• Create your own custom Add-ons to standardize and simplify CI

Bash scripts

Bash scripts are the simplest thing to run in a Task. You can leverage the power of the Linux CLI to process data, make simple API calls, and call other programs.

Python scripts

Python is the preferred programming language for Electrical Engineers, for it’s ease of use and extensive module library.

Add-ons can be made from any programming language, but ours are written in Python to show you how you can customize them to meet your needs.

Our our py-allspice Python wrapper allows you to quickly and easily access your repository files, issues, design reviews, and releases.

Python scripts can be hosted in your local repo, in a centralized script library repo, or from an external source.

Other programming languages

You can use any programming language that can compile and run on Ubuntu Linux LTS.  C/C++ is a good choice as it allows firmware developers to work in their daily language. It is also extremely performant. Javascript is also a popular choice, if you are leveraging your IT team and integrating existing databases and APIs.

Runners

Runners are the programs that wait for your triggers, run your workflows, update pass/fail statuses, and store data. Runners run your automation.

Actions minutes

AllSpice Actions are metered by how long they run in minutes, rounded up to the nearest minute.

Cloud

On hub.allspice.io, every organization starts with a free 100 minutes per month to experiment or run automation. If you need more minutes, you can update your minutes in your organization settings. Each additional minute is $0.128/minute.

Dedicated

Minutes are available in a pool at the organization level and can be shared across committers.

• 1000 free minutes per year

• Bundle A: 50,000 minutes per year

• Bundle B: 100,000 minutes per year

• Bundle C: 200,000 minutes per year

Self-hosted

Self-hosted servers setup and maintain their own runners. Organizations are charged per runner, per year.

Next up: How to turn on Actions and run your first Action (Quickstart)