matbox-actions

A collection of GitHub Actions for MATLAB toolbox development, testing, and release automation using the MatBox toolbox. These actions provide a complete CI/CD solution for MATLAB toolbox projects with automated testing, code analysis, packaging, and release management.

Is your toolbox full of code smells, bugs, and curious critters?
matbox-actions helps you test, polish, and release with confidence!

Overview

matbox-actions enables automated workflows for MATLAB toolbox development by providing:

• Code Quality Analysis - Static code analysis with SARIF integration for GitHub's security tab
• Automated Testing - Test suite execution with report generation and badge creation
• Release Management - Automated toolbox packaging and GitHub release creation
• Workflow Templates - Ready-to-use workflow templates for common CI/CD scenarios

All actions are built around the MatBox toolbox and support both custom task functions and built-in MatBox functionality.

Quick Start

1. Repository Structure

Organize your MATLAB toolbox repository with the following structure:

your-toolbox/
├── src/                    # Main MATLAB source code
├── tests/                  # Unittests and test helpers
├── tools/                  # CI tools and metadata
│   ├── MLToolboxInfo.json  # Toolbox metadata
│   └── tasks/              # Custom/extended MatBox task functions (optional)
└── .github/
    └── workflows/          # GitHub workflow files

2. Basic Workflow Example

name: Test and Analyze Code

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        
      - name: Setup MATLAB
        uses: matlab-actions/setup-matlab@v3
          
      - name: Install MatBox
        uses: ehennestad/matbox-actions/install-matbox@v1
        
      - name: Test Code
        uses: ehennestad/matbox-actions/test-code@v1
        
      - name: Check Code Quality
        uses: ehennestad/matbox-actions/check-code@v1

3. Required Permissions

The calling workflow must grant the permissions used by the steps it runs:

Permission	Needed for
contents: read	Checking out the repository
security-events: write	Uploading the code-analysis SARIF report (check-code)
contents: write	Committing/pushing badge updates and release tags (push-badges, create-github-release, reusable test/analyse workflows when update_badges is true)
checks: write	Publishing test results (test-code)

Grant only what a given workflow actually exercises. The reusable test-code-workflow.yml and prepare-release-workflow.yml need contents: write and checks: write in addition to the permissions above.

4. Pinning

Reference this repo by version tag:

• @v1 — latest v1.x; recommended, receives fixes automatically.
• @v1.5 — an exact release, for reproducible builds.

Do not pin to a commit SHA. The reusable workflows reference this repo's own actions internally by version tag, so a SHA pin on the entry workflow does not freeze the nested actions — they still resolve through the release tag, and a SHA that points at a main commit will run the development tip.

Available Actions

Core Actions

Action	Description
install-matbox	Install MatBox framework in MATLAB environment
test-code	Run MATLAB test suites with report generation
check-code	Analyze MATLAB code quality with SARIF integration
package-toolbox	Package MATLAB toolbox into MLTBX file

Release and Utility Actions

Action	Description
create-github-release	Create GitHub releases with MLTBX attachments
validate-version	Validate version numbers and extract from git tags
configure-matlab-test-matrix	Configure MATLAB version test matrices
generate-tested-with-badge	Generate "tested with" badges for MATLAB versions
push-badges	Push generated badges to repository
update-codemeta	Update the release fields of a codemeta.json file
update-citation	Update the release fields of a CITATION.cff file

Badge Updates

The reusable code analysis and test workflows handle badges differently depending on the event:

• Draft pull requests run CI without badge generation or badge commits.
• Ready pull requests generate badges. If update_badges is true, badge updates are committed back to same-repository pull request branches. If update_badges is false, the workflow reports whether committed badges are stale and the Badges current job fails when they are.
• Push events generate and commit badge updates when update_badges is true.

Use the update_badges input to opt out of badge commits or restrict stable branch updates:

jobs:
  test:
    uses: ehennestad/matbox-actions/.github/workflows/test-code-workflow.yml@v1
    with:
      update_badges: ${{ github.event_name == 'push' && (
        github.ref == 'refs/heads/main' ||
        github.ref == 'refs/heads/dev' ||
        startsWith(github.ref, 'refs/heads/release/')
      ) }}

If update_badges is omitted, badge updates run for all push events and same-repository pull requests that are ready for review. To run badge logic when a draft pull request becomes ready, include the ready_for_review activity type in the calling workflow's pull_request trigger.

The reusable workflows also expose a badges_stale output. Branch protection cannot require this output directly, but it can require the dependent Badges current job.

Workflow Templates

Pre-configured workflow templates are available in .github/workflow-templates/ for common scenarios:

• analyse-code.yml - Code analysis workflow
• test-code.yml - Comprehensive testing workflow
• prepare-release.yml - Complete release automation
• run-codespell.yml - Spell checking for documentation

See the workflow templates README for detailed usage instructions.

Features

🔍 Code Quality Analysis

• Static code analysis with MATLAB Code Analyzer
• SARIF report generation for GitHub security integration
• Custom code check task support

🧪 Automated Testing

• Unit test execution with customizable test runners
• Test report generation and publishing
• Badge creation for test status
• Multi-version MATLAB testing support

📦 Release Automation

• Automated toolbox packaging with version management
• GitHub release creation with MLTBX attachments
• Version validation and tag processing
• Release notes generation

🎯 Customization

• Support for custom MatBox task functions
• Configurable directory structures
• Flexible MATLAB version matrices
• Optional Python integration support

Requirements

• MATLAB: Actions require MATLAB to be installed (use matlab-actions/setup-matlab)
• MatBox toolbox: Automatically installed by the install-matbox action
• Repository Structure: Follow the recommended directory layout with src/, tests/ and tools/ directories
• Metadata: MLToolboxInfo.json file required for packaging and release workflows

Advanced Usage

Custom Task Functions

You can override default behavior by providing custom MatBox task functions in your tools/ directory:

• testToolbox.m - Custom test execution
• codecheckToolbox.m - Custom code analysis
• packageToolbox.m - Custom packaging logic
• verifyToolboxInstallation - Verify installation of a packaged toolbox

Release Workflow

Automate releases on version tags:

on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+' # Matches v1.2.3

jobs:
  release:
    uses: ehennestad/matbox-actions/.github/workflows/prepare-release-workflow.yml@v1
    with:
      source_directory: src
      tools_directory: tools
    secrets:
      DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}

If the repository root contains a codemeta.json, the release workflow updates its version, downloadUrl, releaseNotes, runtimePlatform and dateModified fields and includes the file in the release check-in commit. All other fields are left untouched. runtimePlatform is derived from MinimumMatlabRelease and MaximumMatlabRelease in MLToolboxInfo.json. Repositories without a codemeta.json are unaffected.

In the same way, if the repository root contains a CITATION.cff, the release workflow sets its version and date-released and includes it in the release check-in commit, leaving every other line of the file as it was. Repositories without a CITATION.cff are unaffected.

Contributing

Contributions are welcome! Please see individual action directories for specific documentation and examples.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• MatBox - MATLAB toolbox development framework
• matlab-actions - Official MATLAB GitHub Actions