Welp, it's the holidays! Whether you celebrate Christmas, Hanukah, Kwanzaa, Festivus, or, you know, Tuesday, I certainly wish you a well and happy close out to a pretty unprecedented and challenging year. Hopefully you do indeed have something to celebrate and be grateful for, and I am here to let you in on a few gifts we've been working on which we hope will be well received!
At this time of year I think it is common for us all to think about ways we can be involved with service to others, alleviating the burdens of those who are facing challenges and overall trying to do what we each can to make the world a bit of a better place. Well while I don't want to claim that this is in the same league as all the real good that goes on to help the marginalized and downtrodden, I am excited to put on my testing, CI, and DevOps hat to give some good gifts for those who may find it a bit difficult to realize the value we sometimes talk about on this blog.
These gifts come in the form of a bit of service in in their own right, or perhaps this is more properly stated as services. What do I mean? Well if you've been a reader of this blog for a while you know that we care about continuous integration, solid testing practices, and other forms of developing software that lead to reproducibility and robustness. Often we have shown how this is done through showing examples with Jenkins, and more recently even producing and highlighting a Jenkins plugin to make your Jenkins setup easier.
Hopefully this has been useful, but setting up your own Jenkins setup can be a bit of an investment. Sometimes there are setup challenges and there can be a learning curve. Then, after you set it up you are then signed up to manage and maintain your IT infrastructure, i.e. your machines that will run tests and do other CI related activities on each commit or pull request. Well there is indeed some good news to share!
I am talking about a gift of service(s), and I mean this in regard to our support for some really great CI services. There are a variety of services now available that will run your CI builds on their machines in the cloud with nothing more than adding a bit of YAML to your GitHub repository. Some of these key services include Travis CI, GitHub Actions, CircleCI, and Azure Pipelines (which is included under the Azure DevOps umbrella). In short:
These services provision and spin up cloud based build agents that do all of your work for you, and you never have to concern yourself with managing machines, their health and uptime, or any of the concerns you are presented with when the burden is on you to provide a machine that can do some work.
What else? These services make it super easy to get started, especially for open source projects that are done in out in the open in public repositories. Getting started building for public projects is free! You only need to install an app to your GitHub repo, add a bit of configuration code to a YAML file and put it in your repo and you are good to go.
Wanna see it? Let's try this with one of the services that pioneered this approach, Travis CI. I can show this with my local fork of one of the MathWorks' deep learning repos. This repo contains tools for face detection using a pretrained MTCNN.
Step 1: Sign Up for the Service
In order to leverage these services you will need to sign up and give them access to your repository. This enables them to see and react to pull requests and commits on your git branches. It also allows these services to install their integration onto your GitHub repo or organization. Once these integrations are in your repositories, your CI results will show up directly in GitHub where the work is happening. The specifics of this process is different for each service, but they are all pretty similar as they go through the standard GitHub integration processes. Today, we'll walk through Travis CI.
To do this, first just go to travisci.com and click sign up:
This will enable you to sign up for the service. For Travis CI, you can simply leverage your existing GitHub account. If your code is hosted by a service other than GitHub you may have options there as well, depending on which service you are using you may have varying levels of support. You can see Travis CI has Beta support for 3 other hosting providers:
Once you sign in using your GitHub credentials you can then authorize the service to operate on your repositories. Confirm for yourself that you and your organization are comfortable providing these permissions to the service to operate on your behalf, and then once you are, click authorize:
Now that Travis CI is authorized, you can activate which repositories you would like the service to operate on:
Almost there! You can select all current (and future) repositories in your organization if you would like, or you can choose to activate the service for each of your repositories specifically. Select which code you'd like the service to run against, and there you go, you are ready:
Step 2: Add your CI config
Alright, now that the service is installed for your GitHub organization it is anxiously watching your pull requests and commits, ready to run through your CI process for you. But what is your CI process? The service needs to know something about your repository so that it can know how to help. This is where the YAML comes in. You now can specify your CI config in the form of a YAML file that you check in right next to your code. This follows the principle of Configuration as Code, which is a great way to manage your CI information, but maybe we can go into more depth about this philosophy in a future post.
How can we do this for MATLAB? Actually, how can we do this for our specific deep learning MATLAB repository? Well, it is amazingly simple. First off though, you should be aware that I really know nothing about this repository we are setting up. I haven't contributed to the code at all, and have a limited knowledge even of the problem domain. We have a very talented and knowledgeable consulting staff who set up this repo. In fact, they have set it up to leverage projects. Like we've discussed before, leveraging projects enables anyone to get started working with the repository without any domain or preexisting project knowledge. Note that Travis CI fits this bill. Like me, it really knows nothing about the project, how it builds or which tests should run. Good thing the project already knows how to launch and test itself. Because of that, all we need to do to enable Travis CI to do its thing is place the following single line into a file named .travis.yml file in the root of the repository:
That's it. Really, that's it! Since this project knows how to start up into a valid environment on any machine (including the ephemeral machines in the cloud that Travis CI is using), all we need to tell Travis CI is which language the project is using and our language support does the rest. Check it out:
Here is what just happened:
- First, how about that GitHub dark mode? Pretty slick and easy on the eyes if you ask me.
- I created the minimal Travis CI config for the MATLAB language an committed it to the .travis.yml file.
- Travis CI saw this commit, provisioned a machine to run the standard CI process for the MATLAB language.
- We setup MATLAB on this ephemeral instance that Travis CI spun up. This has historically been one of the biggest challenges of using these services with MATLAB. We are very excited to deliver some progress here.
- The default run command for the Travis CI MATLAB support is then run in batch mode. When projects are being used, the result is that all tests are run as specified in the project. If a project is not being used then all the tests found in the source tree are discovered and run. However in this latter case there is no project startup to ensure the project environment is setup properly, so this would be the responsibility of the tests to ensure the needed steps are performed such as ensuring the right source code is on the path. It can be done without using MATLAB projects, but they make it so easy.
- The build passes or fails depending on whether this command completes without error. Using the (relatively) new assertSuccess method of matlab.unittest.TestResult, test failures are turned into errors, thus failing the build if there are any test failures.
There ya go. It's just as easy as that. If you want to run some command other than the default, you can override the script tag of the Travis CI and invoke matlab -batch myCustomScript where myCustomScript is checked into the project, and can be customized to run your custom CI process as may be more appropriate for you.
The final gift? This usage of MATLAB in batch mode for these CI services is free for public projects. We love open source! ...and we are excited to see how these services can help improve the quality of MATLAB projects all over the world. I can't think of a better way to accelerate the pace of engineering and science. We'd love to hear how you are using these services, or maybe how you plan to. Happy Holidays!
To leave a comment, please click here to sign in to your MathWorks Account or create a new one.