- 6 Minutes to read
- Print
- DarkLight
- PDF
How does AllSpice Actions work?
- 6 Minutes to read
- Print
- DarkLight
- PDF
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
trigger event | activity types |
---|---|
create | not applicable |
delete | not applicable |
fork | not applicable |
gollum (wiki) | not applicable |
push | not applicable |
issues |
|
issue_comment |
|
pull_request |
|
pull_request_review |
|
pull_request_review_comment |
|
release |
|
registry_package |
|
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)