131 lines
3.7 KiB
Markdown
131 lines
3.7 KiB
Markdown
# How to Use Your Template Action
|
||
|
||
## Overview
|
||
|
||
This repository demonstrates **how to use the AllSpice Action Template** to automatically generate a Bill of Materials (BOM) for Altium, OrCAD, or System Capture projects directly from your GitHub workflows.
|
||
|
||
It includes a practical example of a GitHub Actions workflow that:
|
||
|
||
* Triggers on **push** and **issue events**.
|
||
* Runs the `action-template` hosted on AllSpice Hub.
|
||
* Automatically generates and displays a BOM file.
|
||
* Uploads the BOM as an artifact for future reference.
|
||
|
||
---
|
||
|
||
## Prerequisites
|
||
|
||
Before using this template:
|
||
|
||
* Ensure your project repository contains a compatible project file:
|
||
|
||
* `.PrjPcb` (Altium)
|
||
* `.DSN` (OrCAD)
|
||
* `.SDAX` (System Capture)
|
||
* Ensure you have a **columns mapping file** (JSON or YAML) that specifies how to extract the BOM attributes.
|
||
|
||
---
|
||
|
||
## Workflow Details
|
||
|
||
The provided workflow automatically runs when:
|
||
|
||
* Code is **pushed** to the repository.
|
||
* An issue is **opened, closed, or reopened**.
|
||
|
||
### Triggered Events
|
||
|
||
```yaml
|
||
on:
|
||
push:
|
||
issues:
|
||
types: [opened, closed, reopened]
|
||
```
|
||
|
||
---
|
||
|
||
## Example Workflow
|
||
|
||
Here’s the example from this repository:
|
||
|
||
```yaml
|
||
name: Generate BOM
|
||
|
||
on:
|
||
push:
|
||
issues:
|
||
types: [opened, closed, reopened]
|
||
|
||
jobs:
|
||
Generate_BOM:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- name: Checkout
|
||
uses: actions/checkout@v3
|
||
|
||
- name: Generate BOM
|
||
uses: https://hub.allspice.io/Actions/action-template@v1
|
||
with:
|
||
source_path: Archimajor.PrjPcb
|
||
columns: .allspice/columns.yml
|
||
output_file_name: output.csv
|
||
group_by: 'Part Number'
|
||
variant: ''
|
||
|
||
- name: Show BOM
|
||
run: cat output.csv
|
||
|
||
- name: Upload file as artifact
|
||
uses: actions/upload-artifact@v3
|
||
with:
|
||
name: OUTPUT.csv
|
||
path: output.csv
|
||
```
|
||
|
||
---
|
||
|
||
## Input Parameters
|
||
|
||
| Name | Description | Required | Default |
|
||
| ------------------ | ------------------------------------------------------------------------ | -------- | -------------- |
|
||
| `source_path` | Path to the source project file (.PrjPcb, .DSN, .SDAX). | Yes | N/A |
|
||
| `columns` | Path to a YAML or JSON file mapping BOM columns to component attributes. | Yes | `columns.json` |
|
||
| `output_file_name` | The output BOM file name. | No | `bom.csv` |
|
||
| `group_by` | Column(s) to group the BOM by (comma-separated list). | No | (flat BOM) |
|
||
| `variant` | Variant name to generate BOM for (if applicable). | No | Default |
|
||
|
||
---
|
||
|
||
## Workflow Explanation
|
||
|
||
* ✅ **Checkout Step:**
|
||
Ensures your repo files are available in the GitHub Actions runner.
|
||
|
||
* ⚙️ **Generate BOM Step:**
|
||
Runs the AllSpice Action to process your project file and generate the BOM.
|
||
|
||
* 🖨️ **Show BOM Step:**
|
||
Outputs the generated BOM file to the GitHub Actions log for easy review.
|
||
|
||
* 📦 **Upload Artifact Step:**
|
||
Saves the generated BOM as an artifact you can download later from the GitHub workflow run page.
|
||
|
||
---
|
||
|
||
## Notes
|
||
|
||
* The `columns` file is **mandatory** and defines how BOM attributes are mapped.
|
||
* You can customize grouping and variants to match your specific project structure.
|
||
* The workflow is designed for easy integration with both AllSpice Hub and GitHub’s artifact system.
|
||
|
||
---
|
||
|
||
## Resources
|
||
|
||
* [AllSpice Hub](https://hub.allspice.io/)
|
||
* [AllSpice Action Template Documentation](https://hub.allspice.io/Actions/action-template)
|
||
|
||
---
|
||
|
||
If you'd like, I can help you add setup instructions for specific ECAD tools or additional customization tips. Let me know!
|