README.md

[![ROS](https://upload.wikimedia.org/wikipedia/commons/b/bb/Ros_logo.svg)](http://www.ros.org/)

Using Travis CI? Take a look at [ros-industrial/industrial_ci](https://github.com/ros-industrial/industrial_ci).

## Description

This repository contains helper scripts and instructions on how to use Continuous Integration (CI) for ROS projects hosted on a GitLab instance.

Supported ROS releases (older release should be supported too):

- `humble`
- `jazzy`

This repository uses the [ROS Docker](https://store.docker.com/images/ros) images to compile your packages, it does not run tests by default.

## How to use

Your repository must be hosted on a GitLab instance with CI working and Docker support.

Create a `.gitlab-ci.yml` that looks like this:

```yml
image: ros:jazzy-ros-core

cache:
  paths:
    - ccache/

before_script:
  - apt update >/dev/null && apt install -y git >/dev/null
  - git clone https://gitlab.com/VictorLamoine/ros_gitlab_ci.git >/dev/null
  - source ros_gitlab_ci/gitlab-ci.bash >/dev/null

jazzy:build:
  stage: build
  script:
    - source ros_gitlab_ci/gitlab-ci.bash >/dev/null
    - colcon build --event-handlers console_cohesion+ --packages-up-to package_name
```

Commit, push to your repository and watch the pipeline! (make sure pipelines are enabled in your project settings).

## Useful variables

- `DISABLE_CCACHE` (false by default), if defined to `true`: disables [ccache](https://ccache.samba.org/) gcc output caching.
- `USE_ROSDEP` (true by default) use [rosdep](http://wiki.ros.org/rosdep/) to install dependencies. Define to `false` to disable.
- `ROSINSTALL_CI_JOB_TOKEN` (false by default), if defined to `true`: makes it possible to clone private repositories using wstool by using the [CI job permissions mode](https://docs.gitlab.com/ee/user/project/new_ci_build_permissions_model.html). Requires GitLab 8.12 minimum and that the private repositories are on the same GitLab server.
- `WSTOOL_RECURSIVE` (false by default), if defined to `true`: wstool will be used to cloned recursively every repositories specified in the `*.rosinstall` files. For this feature to work:
  - The rosinstall file names must be unique
  - No repository may contain a space in it's name

## Installing extra APT packages

Just add them after sourcing `gitlab-ci.bash` in the `before_script` section, for example:

```yml
before_script:
 - apt update >/dev/null && apt install -y git >/dev/null
 - git clone https://gitlab.com/VictorLamoine/ros_gitlab_ci.git >/dev/null
 - source ros_gitlab_ci/gitlab-ci.bash >/dev/null
 - apt install -y liblapack-dev ros-jazzy-uuid-msgs >/dev/null
```