README.adoc

= GitLab CI templates

Templates for GitLab Continuous Integration are provided in the folder link:ci-templates[]. These can be included from any repo by using `include:project`:

```yml
include::examples/simple_include.yml[]
```

== Core Pipeline
The Core pipeline, defined in link:ci-templates/core.yml[], has the following structure:

- Stage: `build`
  * Check python syntax
  * `.industrial_ci` template (see https://github.com/ros-industrial/industrial_ci[the industrial_ci repo]), which can be used to define jobs that build `ROS` packages
    ** Needs the `ROS_DISTRO` variable to be defined
    ** If the package has `.rosinstall` dependencies, they can be installed using the variable `UPSTREAM_WORKSPACE`
    ** Uses `flexbotics-base-devel:${ROS_DISTRO}` as a starting image
    ** Runs link:scripts/ci_run_entry_points.sh[] in the `AFTER_SETUP_TARGET_WORKSPACE` stage, which in turn finds and runs every `ci_entry_script.bash` script found in the target repo.
- Stage: `deploy`
  * `.ddeploy` template (see https://git.code.tecnalia.com/tecnalia_robotics/flexbotics/flexbotics_utils/ddeploy[the ddeploy repo]), which:
    ** Is run automatically for tags, but can also be run manually on normal commits
    ** Calls `ddeploy` to generate the docker image
    ** Renames the image created by ddeploy with different tags and pushes them to the registry.
    *** Tag `${COMMIT_SHA}` (hash of commit)
    *** Tag `${CI_COMMIT_REF_NAME}` (branch or tag name)
    *** Tag `latest` only on the default branch
- Stage: `.post`
  * Check `bash`/`sh` script syntax
  * Check Markdown and AsciiDoc syntax
  * Check files have no trailing whitespace and are `UTF-8` encoded
  * Check that `C++` files follow this link:clang-format[]


== Manual Jobs

Using the templates defined by the core pipeline, one can easily define jobs to build the packages in the repo.

```yml
include::examples/manual_job.yml[]
```

More examples can be found in link:ci-templates/examples[].

== Auto Rules
In the link:ci-templates/auto-rules[] folder, automatic pipelines are defined that will try to detect the ROS distro from the branch name and create jobs.
For example, if the branch starts with `noetic-` it will build for noetic.
If the branch doesn't start with any ROS distro, it will build the default distro, which can be specified with the variable `DEFAULT_DISTRO`.
For convenience, some templates are provided that already set this variable.
If your repo needs to uses `.rosinstall`, you can use the templates in the link:ci-templates/auto-rules/with-rosinstall[] folder.

The auto rules also allow for using variables to explicitely activate each job:

```yml
include::examples/build_vars.yml[]
```

If a `ddeploy.yaml` file exists, the auto-rules will add a job extending the `.ddeploy` template defined

== LFS
By default, lfs files are not downloaded. If you need to add LFS, include the link:ci-templates/lfs-pull.yml[] along with anything else:
```yml
include::examples/include_lfs.yml[]
```