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

Add-on template repository

The best place to start creating your own Add-ons is by cloning our template repository.

Anatomy of an Add-on Repo

Before writing your own Add-on, let’s understand the basics of how an Action Add-on works.

1. Repository on AllSpice

2. Dockerfile - Specifies how to load the software container

3. Action.yml - Specifies Add-On API Parameters

4. Add-on-script.py - The python script that contains the Add-on instruction code

   1. Rename this file to match what your action does

      1. generate_bom.py

      2. generate_design_review_report.py

   2. You are not limited to Python. If you need another programming language, please reach out to us at support@allspice.io to request documentation or training.

5. requirements.txt - Python dependencies.

Dockerfile

The Dockerfile is easy to understand, even if you’ve never seen this type of file before.

Here are some of the instructions:

FROM python:3.12-bookworm Loads python into the virtual environment

Copy file /file Copy the file from the repository to the virtual environment

Run pip install -r /requirements.txt Installs the python requirements from the file

ENTRYPOINT [ "/Add-on-script.py" ] The name of the Add-on. This is what other repo workflow files will reference.

Here is the complete Dockerfile

FROM python:3.12-bookworm

COPY requirements.txt /requirements.txt
COPY Add-on-script.py /Add-on-script.py

RUN pip install -r /requirements.txt

ENTRYPOINT [ "/Add-on-script.py" ]

Requirements

The requirements.txt file specifies which Python modules to load and which version to load.

module-name=version#

py-allspice AllSpice’s native Python wrapper to the AllSpice API

pyyaml A YAML markdown language processor. Helps parse workflow.yml files

py-allspice==3.5.0
pyyaml~=6.0

Define Add-On API in action.yml

The file action.yml describes how to connect your workflow call of the add-on to the actual script and specifies how parameters are used.

This is considered an API contract.

Below is the action.yml file for this repo. You can see that the inputs section maps inputs to input variables.

The second section composes the args from inputs and other values and passes it to the Dockerfile.

name: "Hardware DevOps Action"
description: >
  A generic AllSpice Action Add-on for hardware development tasks such as schematic review,
  PCB review, ECO review, and release. This action demonstrates defining parameters 
  for these tasks and utilizing GitHub context information.  

inputs:
  source_file:
    description: >
      Path to the source file or directory from the root of the repo. For example,
      the path to a schematic or PCB file.      
    required: true
  output_file_name:
    description: "Name of the output file"
    required: true
    default: "output.txt"
  config_file:
    description: >
      Path to a configuration file for the task.      
    required: true
  task_type:
    description: >
      The type of hardware task to perform. Options include 'Schematic-Review', 
      'PCB-Review', 'ECO-Review', 'Release'.      
    default: "Schematic-Review"
  additional_params:
    description: >
      Any additional parameters required for the task, provided as a JSON string.      
    default: "{}"

runs:
  using: "docker"
  image: "Dockerfile"
  args:
    - "--source_file"
    - "${{ inputs.source_file}}"
    - "--output_file"
    - "${{ github.workspace}}/${{ inputs.output_file_name }}"
    - "--config_file"
    - ${{ inputs.config_file }}
    - "--task_type"
    - ${{ inputs.task_type }}
    - "--additional_params"
    - ${{ inputs.additional_params }}
    - "--source_ref"
    - ${{ allspice.sha }}
    - "--server_url"
    - ${{ allspice.server_url }}
    - "--allspice_token"
    - ${{ secrets.ALLSPICE_TOKEN }}
env:
  GITHUB_TOKEN: ${{ github.token }}

Add-on input API

You can customize your Add-on inputs to match your own workflow. These are some example inputs that are helpful for running Add-ons.

You can have as many or as few inputs as you need for your workflow.

• source_file: The path to the source file used for the task. Example: Archimajor.PrjPcb, Schematics/Beagleplay.dsn.

• task_type: The type of hardware task to perform. Options include Schematic-Review, PCB-Review, ECO-Review, Release. (default: Schematic-Review)

• source_ref: The git reference the task should be performed for (e.g., branch name, tag name, commit SHA). (default: main)

• server_url: The URL of your AllSpice server instance.

• output_file: The path to the output file. If absent, the output will be printed to the command line.

• additional_params: Any additional parameters required for the task, provided as a JSON string. (default: {})

• allspice_token: Your AllSpice application token. Generate a token at: https://hub.allspice.io/user/settings/applications

• config_file: Path to the config file.

• input_file: Path to the input file.

Define Add-on script

Add-on-script.py This is the program that you will use to perform your Add-on. In this case, we use Python and the py-allspice API wrapper.

The first part of the program is parsing the arguments from the API contract, and the second part runs your actual Add-on. In this template example the Python script performs a connection test to AllSpice, and displays the parameters passed from the calling Workflow file.

Testing files

This repo has an optional Action workflow that checks the syntax of Add-on-script.py. This is helpful because Python is an interpreted language.

You do not need these files to run your Add-on, however using tests will help you spot errors.

• .allspice/dependabot.yml - Instructions for repository workflow tests.

• .allspice/workflows/test.yml - Workflow to test this repo on design review.

  • Lints 3 different versions of python (Checks syntax)

• pyproject.toml - Linter setup. Specifies how the repository workflow tests will check the syntax of this repository

• requirements-test.txt - the requirements for the test workflow.

Outputs

The outputs are dependent on the task performed and will be printed to the command line or saved to the specified output_file.

In this template repo, there are no actual outputs, however the name of the output is displayed to demnostrate the correct passing of inputs to the script.

Example Workflow

Here is the file .allspice/workflows/add-on-workflow-example.yml

This shows how to call the Add-on in this repo.

name: Example AllSpice Add-on Template

on: [push, pull_request]

jobs:
  hardware-devops:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run Hardware DevOps Action
        uses: <https://hub.allspice.io/AllSpice-Demos/Add-on-template@v0.1>
        with:
          source_path: ".allspice/examples/input.txt"
          output_file_name: "output.txt"
          config_file: ".allspice/examples/config.yml"
          task_type: "Schematic-Review"
          additional_params: '{"SCH_VER":"3"}'
        env:
          ALLSPICE_TOKEN: ${{ allspice.token }}