Setup Trace CLI — GitHub Action

Install and configure the Trace CLI in your GitHub Actions workflows. Run ERC/DRC checks, generate Gerbers, and leverage AI-powered design review directly in CI.

Quick Start

- uses: buildwithtrace/github-action@v1
  with:
    token: ${{ secrets.TRACE_API_TOKEN }}

Inputs

Input	Required	Default	Description
version	No	latest	Trace CLI version to install
token	No	—	API token for authenticated commands

Usage Examples

Run ERC on Pull Requests

name: ERC Check
on: pull_request

jobs:
  erc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: buildwithtrace/github-action@v1
        with:
          token: ${{ secrets.TRACE_API_TOKEN }}

      - name: Run Electrical Rules Check
        run: buildwithtrace erc ./hardware/schematic.kicad_sch

Run DRC on Push to Main

name: DRC Check
on:
  push:
    branches: [main]
    paths: ['hardware/**']

jobs:
  drc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: buildwithtrace/github-action@v1
        with:
          token: ${{ secrets.TRACE_API_TOKEN }}

      - name: Run Design Rules Check
        run: buildwithtrace drc ./hardware/board.kicad_pcb

Generate Gerbers on Release

name: Generate Manufacturing Files
on:
  release:
    types: [published]

jobs:
  gerbers:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: buildwithtrace/github-action@v1
        with:
          token: ${{ secrets.TRACE_API_TOKEN }}

      - name: Generate Gerbers
        run: buildwithtrace gerbers ./hardware/board.kicad_pcb --output ./output/gerbers/

      - name: Upload Gerbers as artifact
        uses: actions/upload-artifact@v4
        with:
          name: gerbers-${{ github.ref_name }}
          path: ./output/gerbers/

      - name: Attach to release
        uses: softprops/action-gh-release@v2
        with:
          files: ./output/gerbers/*.zip

Matrix Strategy (Multiple KiCad Files)

name: Validate All Boards
on: pull_request

jobs:
  validate:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        board:
          - hardware/main-board/main-board.kicad_pcb
          - hardware/daughter-board/daughter-board.kicad_pcb
          - hardware/power-supply/power-supply.kicad_pcb
    steps:
      - uses: actions/checkout@v4

      - uses: buildwithtrace/github-action@v1
        with:
          token: ${{ secrets.TRACE_API_TOKEN }}

      - name: Run DRC on ${{ matrix.board }}
        run: buildwithtrace drc ${{ matrix.board }}

      - name: AI Design Review
        run: buildwithtrace review ${{ matrix.board }} --focus "manufacturability"

AI-Powered Design Review on PR

name: AI Design Review
on: pull_request

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: buildwithtrace/github-action@v1
        with:
          token: ${{ secrets.TRACE_API_TOKEN }}

      - name: Review schematic
        run: |
          buildwithtrace review ./hardware/ \
            --focus "power integrity, signal routing" \
            --format markdown > review.md

      - name: Post review as PR comment
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          path: review.md

Token Setup

1. Option A (Dashboard): Go to buildwithtrace.com/dashboard/settings, scroll to the Developer section, and click "Create Token"
2. Option B (CLI): Run pip install buildwithtrace && buildwithtrace auth login && buildwithtrace auth token
3. In your repository, go to Settings → Secrets and variables → Actions
4. Add a secret named TRACE_API_TOKEN with your token

Supported Runners

OS	Status
ubuntu-latest	Fully supported
ubuntu-22.04	Fully supported
ubuntu-24.04	Fully supported
macos-latest	Fully supported
macos-14 (ARM)	Fully supported
windows-latest	Not yet supported

Pinning a Version

- uses: buildwithtrace/github-action@v1
  with:
    version: '0.1.0'

Troubleshooting

buildwithtrace: command not found — The script adds pip's bin directory to $GITHUB_PATH. If you're using a custom runner, ensure Python 3.10+ is available.

buildwithtrace doctor warnings — Non-fatal. The CLI will still work, but some features (like local KiCad integration) may be unavailable in CI.

Rate limiting (429) — Authenticated requests have higher limits. Set the token input to avoid throttling on large matrix builds.