.. _ci-pipeline:

How to use the CI Pipeline
==========================

The CI pipeline is a gitlab pipeline that is triggered on every push to the repository. It is used to test whether the container and catkin still builds. It also builds and deploys the documentation to the gitlab pages.


How to setup a project gitlab runner
------------------------------------

In case the IT department does not provide a gitlab runner, you can setup your own gitlab runner. The following steps are necessary to setup a gitlab runner:

1. Go to the gitlab project and click on ``Settings`` -> ``CI/CD`` -> ``Runners settings``. There you can create a new project runner.

   a. You need to at least use ``as_ros`` as the tag for the runner.

2. Install the gitlab runner on the machine that will run the gitlab runner. The installation instructions can be found at https://docs.gitlab.com/runner/install/docker.html

   a. Use local system volume mounts to start the Runner container:

      .. code-block:: bash

            docker run -d --name gitlab-runner --restart always \
               -v /srv/gitlab-runner/config:/etc/gitlab-runner \
               -v /var/run/docker.sock:/var/run/docker.sock \
               gitlab/gitlab-runner:latest

   b. Enter the container:

      .. code-block:: bash

            docker exec -it gitlab-runner /bin/bash
      
   c. Register the runner:

      .. code-block:: bash

            gitlab-runner register \
               --url "https://gitlab.curemannheim.de" \
               --executor "docker" \
               --docker-image "docker:24.0.5" \
               --description "docker-runner" \
               --docker-volumes "/cache" \
               --docker-volumes "/var/run/docker.sock:/var/run/docker.sock"

   d. Edit the config.toml file, ``[runner.docker]`` should look like this:

      .. code-block:: bash

            sudo nano /srv/gitlab-runner/config/config.toml
      
      .. code-block:: bash

            [runners.docker]
               tls_verify = false
               image = "docker:24.0.5"
               privileged = false
               disable_entrypoint_overwrite = false
               oom_kill_disable = false
               disable_cache = false
               volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"]
               shm_size = 0
               network_mtu = 0
               allowed_pull_policies = ["always", "never"]