# Logilab's public gitlab-ci templates


In the `templates/` you can find some of our gitlab-ci templates.
You can include them in your gitlab-ci.

To include them use this snippet:

```yaml
include:
  - project: "open-source/gitlab-ci-templates"
    ref: "branch/default"
    file:                                           # the stages are:
      - "templates/no-duplicated-ci-pipelines.yml"  # use workflow to avoid duplicated pipelines
      - "templates/build-docker-image.yml"
      - "templates/build-debian-package.yml"        # will build a .deb and upload it to heptapod
      - "templates/create-release-on-heptapod-including-debian-package.yml"
      - "templates/upload-to-pypi.yml"
```

Depending on your templates you will need certains stages **in a specific order**:

```yaml
stages:
  # put your testing/linting stages here before
  # for build-debian-package.yml
  - build-debian-package
  - upload-deb-to-heptapod
  # for build-docker-image.yml
  # for release-on-heptapod.yml
  - release
  # for upload-to-pypi.yml
  - publish
```

A recommended configuration for a cube would be:

```yaml
---
default:
  image: python:3.7

include:
  - project: "open-source/gitlab-ci-templates"
    ref: "branch/default"
    file:
      - "templates/no-duplicated-ci-pipelines.yml"  # use workflow to avoid duplicated pipelines
      - "templates/lint/flake8.yml"  # will do the equivalent of 'tox -e flake8'
      - "templates/lint/check-manifest.yml"  # will do the equivalent of 'tox -e check-manifest'
      - "templates/lint/yamllint.yml"  # will do the equivalent of 'tox -e yamllint'
      - "templates/tests/py3.yml"  # will do the equivalent of 'tox -e py3'
      - "templates/create-release-on-heptapod.yml"  # this will create a release on heptapod
      - "templates/upload-to-pypi.yml"  # on a new mercurial tag (expected to be done with release-new), will push a release on pypi
  # uncomment and uses to customize/extend the configuration here if needed
  # (it needs to be at the same level than "- project")
  # - ".gitlab-ci-extended.yml"

stages:
  - lint
  - tests
  - release
  - publish
```

You can also refer to [release-new's gitlab-ci](https://forge.extranet.logilab.fr/open-source/release-new/-/blob/branch/default/.gitlab-ci.yml)
for instance, to see how it can be used.

You can also find the official documentation [here](https://docs.gitlab.com/ee/ci/yaml/includes.html),
and some examples [here](https://docs.gitlab.com/ee/ci/yaml/README.html#include).

## Job customisation

If you want to modify a job in your project, you can override it.
For example, you need to change the `rule` condition of `image_build`.

This is your default `.gitlab-ci.yml`:
```yaml
include:
  - project: "open-source/gitlab-ci-templates"
    ref: "branch/default"
    file:
      …
      - "templates/build-docker-image.yml"        # build two docker images with image_build and image_build_latest
      …
  - ".gitlab-ci-extended.yml"

…
```
In `.gitlab-ci-extended.yml`, you can override the definition of the rule:

```yaml
---
image_build:
  rules:
    - if: '$CI_MERGE_REQUEST_ID'
      when: never
    - if: '$CI_COMMIT_TAG'
      when: on_success
```
Now the job `image_build` will run only on tags.

## Description of all the jobs

| Job filename                                                                                                                 | Stage                                        | Purpose                                                                                              |
| ---                                                                                                                          | ---                                          | ---                                                                                                  |
| [no-duplicated-ci-pipelines.yml](templates/no-duplicated-ci-pipelines.yml)                                                   | None                                         | avoid running duplicate pipelines for both topic head and MR                                         |
| [lint/black.yml](templates/lint/black.yml)                                                                                   | lint                                         | run tox -e black                                                                                     |
| [lint/check-manifest.yml](templates/lint/check-manifest.yml)                                                                 | lint                                         | run tox -e check-manifest                                                                            |
| [lint/flake8.yml](templates/lint/flake8.yml)                                                                                 | lint                                         | run tox -e flake8                                                                                    |
| [lint/mypy.yml](templates/lint/mypy.yml)                                                                                     | lint                                         | run tox -e mypy                                                                                      |
| [lint/safety.yml](templates/lint/safety.yml)                                                                                 | lint                                         | run tox -e safety                                                                                    |
| [lint/yamllint.yml](templates/lint/yamllint.yml)                                                                             | lint                                         | run tox -e yamllint                                                                                  |
| [tests/py27.yml](templates/tests/py27.yml)                                                                                   | tests                                        | run tox -e py27                                                                                      |
| [tests/py3.yml](templates/tests/py3.yml)                                                                                     | tests                                        | run tox -e py3                                                                                       |
| [build-debian-package.yml](templates/build-debian-package.yml)                                                               | build-debian-package, upload-deb-to-heptapod | build and upload debian packages to heptapod                                                         |
| [build-docker-image.yml](templates/build-docker-image.yml)                                                                   | release                                      | build two docker images and push them to heptapod registry (the "latest" is added when MR is merged) |
| [create-release-on-heptapod.yml](templates/create-release-on-heptapod.yml)                                                   | release                                      | create a release on heptapod on new tags                                                             |
| [create-release-on-heptapod-including-debian-package.yml](templates/create-release-on-heptapod-including-debian-package.yml) | release                                      | create a release on heptapod on new tags and link the debian package to it                           |
| [upload-to-pypi.yml](templates/upload-to-pypi.yml)                                                                           | publish                                      | upload the package to pipy on new tag using tox -e pypi-publish                                      |
| [upload-python-package-to-heptapod.yml](templates/upload-python-package-to-heptapod.yml)                                     | publish                                      | upload the package to heptapod registry on new tag                                                   |