Interfacing CrazyS with GitHub Action

In this wiki section is illustrated the employed solution to link the continuous integration (CI) open-source platform GitHub Action with the CrazyS repository. Moreover, it is described the corresponding advantages that a CI system may give when developing a ROS component like CrazyS.

In the Listing below is reported the script used to configure the CrazyS repository with GtiHub Action. The code is based on the version used with TravisCI and has been customized to make it compatible with the Kinetic Kame distro of ROS.

# This is a basic workflow to help you get started with Actions
name: 'CrazyS Build Automation Script'

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
 push:
   branches:
      - 'master'
      - 'dev/gazebo9'
      - 'dev/ros-melodic'
 pull_request:
   branches:
      - 'master'
      - 'dev/gazebo9'
      - 'dev/ros-melodic'

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
###########################################################################################
## FIRST JOB - GITHUB ACTIONS - UBUNTU 16.04 ROS KINETIC WITH GAZEBO 7
###########################################################################################
 job1:
   name: Build on Ubuntu 16.04 with ROS Kinetic and Gazebo 7
   runs-on: ubuntu-16.04
   steps:
     - uses: actions/checkout@v2
     - name: Install ROS
       env:
         ROS_CI_DESKTOP: "`lsb_release -cs`"  # e.g. [trusty|xenial|...]
         CI_SOURCE_PATH: $(pwd)
         ROSINSTALL_FILE: $CI_SOURCE_PATH/dependencies.rosinstall
         CATKIN_OPTIONS: $CI_SOURCE_PATH/catkin.options
         ROS_PARALLEL_JOBS: '-j8 -l6'
         # Set the python path manually to include /usr/-/python2.7/dist-packages
         # as this is where apt-get installs python packages.
         PYTHONPATH: $PYTHONPATH:/usr/lib/python2.7/dist-packages:/usr/local/lib/python2.7/dist-packages
         ROS_DISTRO: kinetic
       run: |
           sudo sh -c "echo \"deb http://packages.ros.org/ros/ubuntu $ROS_CI_DESKTOP main\" > /etc/apt/sources.list.d/ros-latest.list"
           wget http://packages.ros.org/ros.key -O - | sudo apt-key add -
           sudo apt-get update -qq
           sudo apt-get install dpkg
           sudo rm /var/lib/dpkg/lock
           sudo dpkg --configure -a
           sudo apt-get install -y python-catkin-tools python-catkin-pkg python-rosdep python-wstool protobuf-compiler 
           sudo apt-get install -y ros-$ROS_DISTRO-desktop-full ros-$ROS_DISTRO-joy ros-$ROS_DISTRO-octomap-ros
           sudo apt-get install -y ros-$ROS_DISTRO-mavlink python-wstool python-rosinstall build-essential
           sudo apt-get install -y protobuf-compiler libgoogle-glog-dev python-rosinstall python-rosinstall-generator
           sudo apt-get install -y ros-$ROS_DISTRO-octomap ros-$ROS_DISTRO-octomap-mapping
           sudo apt-get install -y ros-$ROS_DISTRO-pointcloud-to-laserscan ros-$ROS_DISTRO-octovis
           sudo apt-get install -y ros-$ROS_DISTRO-joy ros-$ROS_DISTRO-control-toolbox
           sudo apt-get install -y libeigen3-dev ros-$ROS_DISTRO-image-view ros-$ROS_DISTRO-parrot-arsdk libprotobuf-dev 
           sudo apt-get install -y libprotoc-dev ros-$ROS_DISTRO-joy-teleop ros-$ROS_DISTRO-nav-msgs ros-$ROS_DISTRO-mav-msgs 
           sudo apt-get install -y libyaml-cpp-dev ros-$ROS_DISTRO-nodelet ros-$ROS_DISTRO-mav-planning-msgs ros-$ROS_DISTRO-urdf 
           sudo apt-get install -y ros-$ROS_DISTRO-image-transport ros-$ROS_DISTRO-roslint ros-$ROS_DISTRO-angles ros-$ROS_DISTRO-cv-bridge 
           sudo apt-get install -y ros-$ROS_DISTRO-tf2-geometry-msgs ros-$ROS_DISTRO-xacro ffmpeg libavcodec-dev libavformat-dev 
           sudo apt-get install -y libavutil-dev libswscale-dev ros-$ROS_DISTRO-camera-info-manager ros-$ROS_DISTRO-cmake-modules 
           sudo apt-get install -y ros-$ROS_DISTRO-gazebo-msgs ros-$ROS_DISTRO-mavros-msgs ros-$ROS_DISTRO-control-toolbox 
           sudo apt-get install -y ros-$ROS_DISTRO-mav-msgs ros-$ROS_DISTRO-libmavconn ros-$ROS_DISTRO-mavros ros-$ROS_DISTRO-octomap-msgs 
           sudo apt-get install -y ros-$ROS_DISTRO-geographic-msgs ros-$ROS_DISTRO-mavlink ros-$ROS_DISTRO-mavros-extras 
           sudo apt-get install -y ros-$ROS_DISTRO-mav-planning-msgs ros-$ROS_DISTRO-joy
           source /opt/ros/$ROS_DISTRO/setup.bash
           sudo rosdep init
           rosdep update --include-eol-distros
           rosdep install octomap_mapping
           rosmake octomap_mapping
############################################################################
     - name: Installation completed! Started the building process..
       env:
        ROS_DISTRO: kinetic
       run: |
         source /opt/ros/$ROS_DISTRO/setup.bash
         mkdir -p ~/catkin_ws/src
         catkin_init_workspace
         catkin init
         cd ~/catkin_ws/src
         git clone https://github.com/gsilano/CrazyS.git
         git clone -b crazys https://github.com/gsilano/mav_comm.git
         rosdep update
         cd ~/catkin_ws
         rosdep install --from-paths src -i
         catkin build
         echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc
         source ~/.bashrc
##########################################################################################
## SECOND JOB - GITHUB ACTIONS - ROS MELODIC WITH GAZEBO 9
###########################################################################################
 job2:
   name: Build on Ubuntu 18.04 with ROS Melodic
   runs-on: ubuntu-18.04
   steps:
    - uses: actions/checkout@v2
    - name: Install ROS
      env:
       ROS_CI_DESKTOP: "`lsb_release -cs`"  # e.g. [trusty|xenial|...]
       CI_SOURCE_PATH: $(pwd)
       ROSINSTALL_FILE: $CI_SOURCE_PATH/dependencies.rosinstall
       CATKIN_OPTIONS: $CI_SOURCE_PATH/catkin.options
       ROS_PARALLEL_JOBS: '-j8 -l6'
       # Set the python path manually to include /usr/-/python2.7/dist-packages
       # as this is where apt-get installs python packages.
       PYTHONPATH: $PYTHONPATH:/usr/lib/python2.7/dist-packages:/usr/local/lib/python2.7/dist-packages
       ROS_DISTRO: melodic
      run: |
       sudo sh -c "echo \"deb http://packages.ros.org/ros/ubuntu $ROS_CI_DESKTOP main\" > /etc/apt/sources.list.d/ros-latest.list"
       wget http://packages.ros.org/ros.key -O - | sudo apt-key add -
       sudo apt-get update -qq
       sudo apt-get install dpkg
       sudo rm /var/lib/dpkg/lock
       sudo dpkg --configure -a
       sudo apt install -y python-catkin-tools python-catkin-pkg python-rosdep python-wstool ros-$ROS_DISTRO-desktop-full 
       sudo apt-get install -y ros-$ROS_DISTRO-joy  python-rosinstall python-rosinstall-generator python-wstool build-essential
       sudo apt install -y ros-$ROS_DISTRO-octomap-ros ros-$ROS_DISTRO-mavlink python-rosinstall build-essential protobuf-compiler
       sudo apt install -y libgoogle-glog-dev python-rosinstall-generator ros-$ROS_DISTRO-pointcloud-to-laserscan
       sudo apt install -y python-rosdep ros-$ROS_DISTRO-octomap ros-$ROS_DISTRO-octomap-mapping
       sudo apt-get install -y ros-$ROS_DISTRO-joy ros-$ROS_DISTRO-control-toolbox
       source /opt/ros/$ROS_DISTRO/setup.bash
       sudo rosdep init
       rosdep update --include-eol-distros
       rosdep install octomap_mapping
       rosmake octomap_mapping
#####################################################################################
    - name: Installation completed! Started the building process..
      env:
       ROS_DISTRO: melodic
      run: |
       source /opt/ros/$ROS_DISTRO/setup.bash
       mkdir -p ~/catkin_ws/src
       catkin_init_workspace
       catkin init
       cd ~/catkin_ws/src
       git clone -b dev/ros-melodic https://github.com/gsilano/CrazyS.git
       git clone -b med18_gazebo9 https://github.com/gsilano/mav_comm.git
       rosdep update
       cd ~/catkin_ws
       rosdep install --from-paths src -i
       rosdep update
       catkin build
       echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc
       source ~/.bashrc

In order to use GtiHub Action, a GitHub account and GitHub Action script are all the necessary components. The script, i.e., the main.yml file, has to be put in the .github/workflows folder located in the root of the repository.

When the process starts, the catkin workspace is build with all the packages under integration (the commands listed in the install section). GitHub Action clones the GitHub repository(-ies) into a new virtual environment, and carries out a series of tasks to build and test the code. If one or more of those tasks fails, the build is considered broken. If none of the tasks fails, the build is considered passed, and GitHub Action can deploy the code to a web server, or an application host. In particular, the build is considered broken when one or more of its jobs complete with a state that is not passed:

• errored: a command in the before install or install phase returned a nonzero exit code. The job stops immediately;
• failed: a command in the script phase returned a non-zero exit code. The job continues to run until it completes;
• canceled: a user cancels the job before it completes.

At the end of the process, email notifications are sent to all the listed contributors members of the repository. The notifications can be forwarded: on success, on failure, always or never. Finally, the CI system can be also employed to automatically generate documentation starting from the source code and to link it to an online hosting. It is very useful when the project is going to increase or a lot of people are working on it or, more generally, when it is difficult to have an overview of the developed code. Further information on how to use the CI system and how to configure it can be found in 1.

Such procedure allows to easily verify the code quality, underlying errors and warnings through automated software build (including tests), that may not appear when building on own machine. It also ensures that modules working individually (e.g., SLAM, vision or sensors fusion algorithms) do not fail when they are put together due to causes that were difficult to predict during the development phase. For all such reasons, having a software tool able to catch what happened and why it happened, and able to suggest possible solutions, is extremely desirable when working with complex platforms as Gazebo and ROS.

The most updated GitHub Action scripts can be found at this link.