Today in this article, we are going to see how to take your open source project and let Travis test, build and deploy your project, all for free.
Create a Travis account
Go to https://travis-ci.org/ and click “Sign up”, log in using your Github account.
Attach your repository in Travis
- Go to the repository page: https://travis-ci.org/account/repositories.
- Click on “Sync account” to make sure all your repository are present.
- In the “Filter repository” search box, start typing the name of your repo.
- When you find it, toggle to checkbox to enable Travis for this project
Configure the settings of your repository in Travis
- After enabling your repo, click on “Settings”
- For my repo, here are my settings:
- Build pushed branches : ON
- Build pushed pull requests: ON
- Limit concurrent jobs: OFF
- Auto cancel branch builds: ON
- Auto cancel pull request builds: ON
- Cron Jobs:
- branch master
- Runs monthly
- Do not run if there has been a build in the last 24h
You can look at my project at https://travis-ci.org/leobenkel/safety_plugin.
Configure the .travis.yml file
The yml config file is extremely confusing. I will try to do my best explaining it simply.
Key concepts (Stages and Jobs)
A Stage in Travis is a collection of Jobs.
Each stage run sequentially and will only run if all previous Stage have succeeded.
You define them in the
stages key in the yml file.
stages: - name: clean - name: test - name: release if: ((branch = master AND type = push) OR (tag IS present)) AND NOT fork
In this example of stages declaration, we have 3 stages:
release. Note here that the
release stage have condition, it will only execute if the condition is True.
A Job in Travis is part of a Stage and they will run in parallel.
You declare them inside
include in the config file.
jobs: include: - stage: cleanStage name: cleanJob script: make clean
In this example, we have declared on Job inside the Stage named
cleanStage , the job is named
cleanJob and the code executed will be
To declare several Job inside one Stage, you have to do something like:
jobs: include: - stage: test name: compile script: sbt compile - name: scalafmt script: ./bin/scalafmt --test - name: unit-test script: make unit_test
In this example, there are 3 Jobs inside the Stage named
test. The three jobs are named
unit-test. Those 3 Jobs will run in parallel.
What does it look like in the Travis UI?
The screenshot have been taken from this Travis build: https://travis-ci.org/leobenkel/safety_plugin/builds/544870243.
You can see 3 Stages:
Release. Each of those stage will run one after another.
Test stage, each Jobs will run together in parallel.
If any of the Jobs fail, the owning Stage will be marked as fail. If any of the previous Stage have failed, all next Stages will not run.
Have several step inside a Job
To have sequential steps inside a job, you have to do:
jobs: include: - stage: StageName name: JobName script: - step 1 - step 2
Summary – all together
Here is an example, all together:
stages: - name: clean - name: test - name: release if: ((branch = master AND type = push) OR (tag IS present)) AND NOT fork jobs: include: - stage: clean name: clean script: make deep_clean - stage: test name: compile script: sbt compile - name: scalafmt script: ./bin/scalafmt --test - name: mutators-test script: make mutator_test if: branch = master AND type = push AND NOT fork - name: plugin-test script: make test_plugin - name: unit-test script: - make test_coverage test_coverage_report - sbt coveralls - stage: release name: release script: sbt ci-release
In this example, taken from this repo: Safety_Plugin
- There are three stages, named:
- Clean contains 1 job:
- Test contains 4 jobs, including one with a condition
- Release contains 1 job:
- Clean contains 1 job:
I hope this help you understand the Travis config file. Let me know in the comment below if you have any questions !
Install the Travis badge in your README.md file
To add the badge in your README file, edit the file and add this line of code:
[BRANCH_NAME] by the name of the branch you want to monitor, usually
[GITHUB_USER] by your user group name and
[GITHUB_PROJECT_NAME] by the name of your project. It correspond to the github URL in this way:
For my project, it looks something like:
And this badge will update when you push new code to the monitored branch. It can be marked as failing if the build have failed for the monitored branch. The caching is marked for 7 days so you might have to wipe you local cache out if you want to see the most recent update for your project.
You can add those lines below to cache the dependencies and speed up the build process.
# https://github.com/olafurpg/sbt-ci-release/blob/master/.travis.yml cache: directories: - $HOME/.sbt/1.0/dependency - $HOME/.sbt/boot/scala* - $HOME/.sbt/launchers - $HOME/.ivy2/cache - $HOME/.coursier before_cache: - du -h -d 1 $HOME/.ivy2/cache - du -h -d 2 $HOME/.sbt/ - find $HOME/.sbt -name "*.lock" -type f -delete - find $HOME/.ivy2/cache -name "ivydata-*.properties" -type f -delete - rm -rf $HOME/.ivy2/local
I put all my test Job inside one Stage so they can run in parallel:
jobs: include: - ...other Stages... - stage: test name: compile script: sbt compile - name: scalafmt script: ./bin/scalafmt --test - name: plugin-test script: make test_plugin - name: unit-test script: - make test_coverage test_coverage_report - sbt coveralls
Add a clean up stage
I added a first clean up stage, that allow the virtual machine to fetch the dependency during this Stage and keep it for the next Stages.
jobs: include: - stage: clean name: clean script: sbt clean
That’s it for today ! Let me know if you have any questions about how to set up your Travis pipeline in the comment below or if you have things to add to this article.