Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mathworks/ci-configuration-examples
This repository makes it easy to run your MATLAB tests on some of the most common CI platforms. The configuration files take care of setting up MATLAB and automatically executing your MATLAB tests.
https://github.com/mathworks/ci-configuration-examples
azure-devops circleci github-actions matlab-ci travis-ci
Last synced: 7 days ago
JSON representation
This repository makes it easy to run your MATLAB tests on some of the most common CI platforms. The configuration files take care of setting up MATLAB and automatically executing your MATLAB tests.
- Host: GitHub
- URL: https://github.com/mathworks/ci-configuration-examples
- Owner: mathworks
- License: other
- Created: 2021-05-04T14:06:24.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-11-18T12:47:49.000Z (3 months ago)
- Last Synced: 2025-01-26T21:03:50.591Z (14 days ago)
- Topics: azure-devops, circleci, github-actions, matlab-ci, travis-ci
- Language: MATLAB
- Homepage:
- Size: 86.9 KB
- Stars: 76
- Watchers: 11
- Forks: 289
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: License.txt
- Security: SECURITY.md
Awesome Lists containing this project
README
| **Azure® DevOps** | **CircleCI®** | **GitHub® Actions** |
|:---------------------------|:-----------------:|:----------------------------:|
| [](https://dev.azure.com/iat-ci/ci-configuration-examples/_build)
 | [](https://app.circleci.com/pipelines/github/mathworks/ci-configuration-examples)
| [](https://github.com/mathworks/ci-configuration-examples/actions/workflows/ci.yml)
|
# Continuous Integration (CI) configuration examples for MATLAB®
Are you interested in automating your testing with CI?
Not sure how to connect MATLAB with CI systems?
We've got you covered!
This repository makes it easy to run your MATLAB tests on some of the most common CI platforms. The configuration files take care of setting up MATLAB to work with the CI system and automatically executing your MATLAB tests.
## Getting started
### Quick start guide
Here's how to quickly get this repository running on a CI system:
1. Fork the repository to your own GitHub account
2. Go to one of the supported CI platforms and install the available MATLAB CI plugin ***Note:*** GitHub Actions does not require this step
3. Create a new CI job using your forked repository
4. Enjoy using CI with MATLAB!
That's really it!
To use your MATLAB code or Simulink® models with this repository, simply replace the existing code and tests in "code" and "tests" with your own code and tests. There's no need to modify any of the CI configuration files because they are all completely agnostic of the MATLAB code being used.
***Notes:***
* In most cases, the configuration files will automatically get picked up by the CI platform during step 3, but some platforms may require you to specify which file to use
* The default branch for this repository is "main"
### Step-by-step getting started guide for GitHub Actions
Our Continuous Integration with MATLAB and GitHub Actions Workshop provides a step-by-step guide for getting started with GitHub Actions.
* https://github.com/mathworks/ci-with-matlab-and-github-actions-workshop
## Badges
Badges look really great, but they're not always easy to set up. Take a look at the badges, badge code, and reference links below to get started with badges for your repository.
| **Azure DevOps** | |
|:---------------------------|:-|
| Badges | [](https://dev.azure.com/iat-ci/ci-configuration-examples/_build)
 |
| Badge Code | \[\!\[Build Status](https[]()://dev.azure.com/***AZURE_DEVOPS_ORG***/***AZURE_DEVOPS_PROJECT_NAME***/_apis/build/status/***GITHUB_USERNAME***.***GITHUB_REPO_NAME***)](https[]()://dev.azure.com/***AZURE_DEVOPS_ORG***/***AZURE_DEVOPS_PROJECT_NAME***/_build)
\!\[Azure DevOps Coverage](https[]()://img.shields.io/azure-devops/coverage/***AZURE_DEVOPS_ORG***/***AZURE_DEVOPS_PROJECT_NAME***/***AZURE_DEVOPS_DEFINITION_ID***) |
| Badge Help | [Blog with helpful information for setting up Azure DevOps badges](https://gregorsuttie.com/2019/03/20/azure-devops-add-your-build-status-badges-to-your-wiki/) |
| **CircleCI** | |
|:------------------|:-|
| Badge | [](https://circleci.com/gh/mathworks/ci-configuration-examples) |
| Badge Code | \[\!\[CircleCI](https[]()://circleci.com/***SOURCE_CONTROL_SYSTEM***/***GITHUB_USERNAME***/***GITHUB_REPO_NAME***.svg?style=svg)](https[]()://circleci.com/***SOURCE_CONTROL_SYSTEM***/***GITHUB_USERNAME***/***GITHUB_REPO_NAME***) |
| Badge Help | [CircleCI documentation for setting up badges](https://circleci.com/docs/2.0/status-badges "CircleCI documentation for setting up badges") |
| **GitHub Actions** | |
|:-----------------------------|:-|
| Badge | [](https://github.com/mathworks/ci-configuration-examples/actions/workflows/ci.yml) |
| Badge Code | \[\!\[MATLAB](https[]()://github.com/***GITHUB_USERNAME***/***GITHUB_REPO_NAME***/actions/workflows/ci.yml/badge.svg)](https[]()://github.com/***GITHUB_USERNAME***/***GITHUB_REPO_NAME***/actions/workflows/ci.yml) |
| Badge Help | [GitHub Actions documentation for setting up badges](https://docs.github.com/en/actions/managing-workflow-runs/adding-a-workflow-status-badge) |
| **GitLab CI/CD** | |
|:--------------------------|:-|
| Badge Code | \[\!\[Pipeline Status](https[]()://gitlab.com/***GITLAB_PROJECT_PATH***/badges/***DEFAULT_BRANCH_NAME***/pipeline.svg)](https[]()://gitlab.com/***GITLAB_PROJECT_PATH***) |
| Badge Help | [GitLab CI/CD documentation for setting up badges](https://docs.gitlab.com/ee/user/project/badges.html "GitLab CI/CD documentation for setting up badges") |
**How to use the Badge Code:**
1. Copy-paste the badge code into your README.md file
* The badge code you copy should start with "`[!`" and not "`\[\!`"
2. Replace all ***BOLD+ITALIC*** names with your specific credentials/names
* Replace ***GITHUB_ORG*** with your GitHub organization name (usually your GitHub username)
* Replace ***GITHUB_REPO_NAME*** with the name of your GitHub repository
* Replace ***SOURCE_CONTROL_SYSTEM*** with the name of the source control system you are pointing to (gh = GitHub, bb = BitBucket)
* Replace ***AZURE_DEVOPS_ORG*** with the name of your Azure DevOps organization name (usually your Azure DevOps username)
* Replace ***AZURE_DEVOPS_PROJECT_NAME*** with the name of the Azure DevOps project that will run the CI job
* Replace ***AZURE_DEVOPS_DEFINITION_ID*** with the definition ID for your Azure DevOps pipeline
* To find the definition ID for your Azure DevOps pipeline, you must:
* go to your Azure DevOps project
* select "Pipelines" from the left-side navigation menu
* select the pipeline you want to get coverage for
* look at the end of the resulting URL for the number in "definitionId=###"
* Replace ***GITLAB_PROJECT_PATH*** with the path of your GitLab project
* Replace ***DEFAULT_BRANCH_NAME*** with the repository branch name you want to get the pipeline status from
## Supported CI platforms
* Azure DevOps
* CircleCI
* GitHub Actions
* Jenkins™
* GitLab CI/CD
## About the code
The primary goal of this repository is to provide a set of configuration files as templates that illustrate how to run MATLAB on various CI platforms (e.g., Azure DevOps, CircleCI, GitHub Actions, Jenkins).
Each of these pipeline definitions does four things:
1. Install the latest MATLAB release on a Linux®-based build agent
2. Run all MATLAB tests in the root of your repository, including its subfolders
3. Produce a test results report (if necessary)
4. Produce a code coverage report in Cobertura XML format for the source folder
* Currently, only Azure DevOps supports code coverage directly
* To see an example of using [Codecov](https://about.codecov.io/) to show coverage results, please refer to [https://github.com/mathworks/matlab-codecov-example](https://github.com/mathworks/matlab-codecov-example)
The example MATLAB code example `dayofyear.m` is a simple function takes a date string `"mm/dd/yyyy"` and returns the day-of-year number.
Notes:
* MATLAB already includes a day-of-year calculation using `day(d,"dayofyear")`, where `d` is a datetime object. This code is only used as an example since it is a concept that is familiar to most people.
* The code coverage is intentionally set below 100% to show how missing coverage looks with badges. Uncomment the last test in `TestExamples.m` to increase the coverage to 100%.
There are 2 test classes provided:
1. TestExamples.m - A simple set of equality and negative tests
2. ParameterizedTestExamples.m - A set of 12 equality tests set up using the parameterized test format
The repository includes these files:
| **File Path** | **Description** |
|:---------------------------|:----------------|
| [`code/dayofyear.m`](code/dayofyear.m) | The [`dayofyear`](code/dayofyear.m) function returns the day-of-year number for a given date string "mm/dd/yyyy" |
| [`tests/TestExamples.m`](tests/TestExamples.m) | The [`TestExamples`](tests/TestExamples.m) class provides a few equality and negative tests for the [`dayofyear`](code/dayofyear.m) function |
| [`tests/ParameterizedTestExample.m`](tests/ParameterizedTestExample.m) | The [`ParameterizedTestExample`](tests/ParameterizedTestExample.m) class provides 12 tests for the [`dayofyear`](code/dayofyear.m) function using the parameterized test format |
| [`azure-pipelines.yml`](###Azure-DevOps) | The [`azure-pipelines.yml`](azure-pipelines.yml) file defines the pipeline that runs on [Azure DevOps](https://marketplace.visualstudio.com/items?itemName=MathWorks.matlab-azure-devops-extension). |
| [`.circleci/config.yml`](###CircleCI) | The [`config.yml`](.circleci/config.yml) file defines the pipeline that runs on [CircleCI](https://circleci.com/orbs/registry/orb/mathworks/matlab) |
| [`.github/workflows/ci.yml`](###GitHub-Actions) | The [`ci.yml`](.github/workflows/ci.yml) file defines the pipeline that runs on [GitHub Actions](https://github.com/matlab-actions/overview) |
| [`Jenkinsfile`](###Jenkins) | The [`Jenkinsfile`](Jenkinsfile) file defines the pipeline that runs on [Jenkins](https://plugins.jenkins.io/matlab/) |
| [`.gitlab-ci.yml`](###GitLab-CI/CD) | The [`.gitlab-ci.yml`](.gitlab-ci.yml) file defines the pipeline that runs on [GitLab CI/CD](https://docs.gitlab.com/ee/ci/) |
## CI configuration files
### Azure DevOps
```yml
pool:
vmImage: ubuntu-latest
steps:
- task: InstallMATLAB@1
- task: RunMATLABTests@1
inputs:
sourceFolder: code
codeCoverageCobertura: code-coverage/coverage.xml
testResultsJUnit: test-results/results.xml
- task: PublishTestResults@2
inputs:
testResultsFormat: 'JUnit'
testResultsFiles: 'test-results/results.xml'
- task: PublishCodeCoverageResults@1
inputs:
codeCoverageTool: 'Cobertura'
summaryFileLocation: 'code-coverage/coverage.xml'
pathToSources: 'code/'
# As an alternative to RunMATLABTests, you can use RunMATLABCommand to execute a MATLAB script, function, or statement.
# - task: RunMATLABCommand@1
# inputs:
# command: addpath('code'); results = runtests('IncludeSubfolders', true); assertSuccess(results);
```
### CircleCI
```yml
version: 2.1
orbs:
matlab: mathworks/matlab@1
jobs:
build:
machine:
image: ubuntu-2204:current
steps:
- checkout
- matlab/install
- matlab/run-tests:
source-folder: code
# As an alternative to run-tests, you can use run-command to execute a MATLAB script, function, or statement.
# - matlab/run-command:
# command: addpath('code'); results = runtests('IncludeSubfolders', true); assertSuccess(results);
```
### GitHub Actions
```yml
# This is a basic workflow to help you get started with MATLAB Actions
name: MATLAB Build
# Controls when the action will run.
on:
# Triggers the workflow on push or pull request events but only for the main branch
push:
branches: [ main ]
pull_request:
branches: [ main ]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
jobs:
# This workflow contains a single job called "build"
build:
# The type of runner that the job will run on
runs-on: ubuntu-latest
# Steps represent a sequence of tasks that will be executed as part of the job
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- uses: actions/checkout@v4
# Sets up MATLAB on a GitHub-hosted runner
- name: Set up MATLAB
uses: matlab-actions/setup-matlab@v2
# Runs a set of commands using the runners shell
- name: Run all tests
uses: matlab-actions/run-tests@v2
with:
source-folder: code
# You can use "run-build" to invoke the MATLAB build tool and run build tasks
#- name: Run the default "test" task in the build file
# uses: matlab-actions/run-build@v2
# You can use "run-command" to execute custom MATLAB scripts, functions, or statements
#- name: Run custom testing procedure
# uses: matlab-actions/run-command@v2
# with:
# command: disp('Running my custom testing procedure!'); addpath('code'); results = runtests('IncludeSubfolders', true); assertSuccess(results);
```
### Jenkins
```groovy
pipeline {
agent any
stages {
stage('Run MATLAB Tests') {
steps {
runMATLABTests(
sourceFolder: 'code'
)
// As an alternative to runMATLABTests, you can use runMATLABCommand to execute a MATLAB script, function, or statement.
// runMATLABCommand "addpath('code'); results = runtests('IncludeSubfolders', true); assertSuccess(results);"
}
}
}
}
```
### GitLab CI/CD
```yml
stages:
- matlab-test
matlab-test:
stage: matlab-test
script:
- matlab -batch "addpath('code'); results = runtests('IncludeSubfolders', true); assertSuccess(results);"
```
## Caveats
* On cloud-hosted agents provided by Azure DevOps, CircleCI, and GitHub Actions, you need a [MATLAB batch licensing token](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/alternates/non-interactive/MATLAB-BATCH.md#matlab-batch-licensing-token) if your project is private or if your pipeline includes transformation products, such as MATLAB Coder™ and MATLAB Compiler™. You can request a token by contacting MathWorks® at [[email protected]](mailto:[email protected]).
## Links
- [Continuous Integration with MATLAB and Simulink](https://www.mathworks.com/solutions/continuous-integration.html)
## Contact Us
If you have any questions or suggestions, please contact MathWorks at [[email protected]](mailto:[email protected]).