Handbook

Gitlab

Терминология

  • Runner или Gitlab Runner - это сервер, на котором выполняются команды CI.
  • Runner executor - тип runner'а. От них зависит то, как выполняются команды.
  • Pipeline - набор стадий, через которые проходит сборка или тестирование проекта.

Типы Runner'ов

  • docker-executor (с тегом docker) - позволяют выполнять команды в контейнере любого образа. Этот runner используется по умолчанию. Документация.
  • shell-executor (с тегом shell) - выполняет команды в контексте сервера, где установлен runner. Сейчас на них доступны базовый набор unix-утилит, bash, ansible и docker.

Создание нового проекта в Gitlab:

  1. Выбор группы:

    • Для инфраструктурных проектов используйте группу "/infra". В остальных случаях "/apliteni".
    • Обратите внимание, что проект будет доступен для всех участников выбранной группы.

  2. Выбор подгруппы:

    • Если ожидается несколько репозиториев/сервисов, то сразу заведите подгруппу по имени проекта. Например, "apliteni/gdbc". У проектов на go есть ряд проблем при использовании подгрупп в имени пакета, здесь решение https://gitlab.com/gitlab-org/gitlab-ce/issues/30785#note_132378592

  3. Выбор имени проекта:

    • Для разделения слов в имени, используйте знак минус. Пример, "auth-api-server".

  4. Создайте README.md с описанием проекта на русском языке.

Версионирование проекта

В каждом проекте заводится файл с номером версии. Это может version.php, version.go или version.ts. Номер версии выставляем согласно соглашению SemVer 2.0.

+----- Major version is synchronize with tslint's major version.
| +--- Minor version has BREAKING CHANGE and feat.
| | +- Patch version has patch.
| | |
x.x.x

Номер версии используем сразу в нескольких местах:

  • Для автоматического тегирования в git и docker образа.
  • Для blue-green деплоя в k8s.
  • Записи в лог.

Gitlab CI / CD

CI/CD позволяет запускать набор команд (pipeline) прямо Gitlab.

Чтобы использовать CI/CD нужно создать файл .gitlab-ci.yml в репозитории проекта (документация)

Рекомендации по написанию pipeline'а

  1. Как можно раньше заложите контроль качества кода: прогон тестов, проверка форматирования, статический анализатор кода.
  2. Файлы для ci, рекомендуется держать в директории ./ci. И внутри: ci/bin, ci/docker, ci/helm.
  3. Вместо написания кода в script секции, лучше вынести код в bash файл.
  4. Если нужно передать артефакты из одной стадии в другую, используйте artifacts и dependencies (Документация).
  5. Тестируйте успешность деплоя и созданные артефакты.

Рекомендациии по отладке CI

  1. Используйте CI Lint для проверки ошибок в gitlab-ci.yml (Проект > Pipelines > CI Lint).

  2. Результат выполнения CI смотрите через Gitlab, 'CI / CD > Jobs'.

  3. Чтобы посмотреть все переменные окружения (ENV), добавьте CI_DEBUG_TRACE: "true":

job_name:
  variables:
    CI_DEBUG_TRACE: "true"

  1. Выносите код из секции script в bash-файлы, так вы сможете проверять скрипты у себя локально.

  2. Запускайте скрипты в docker контейнере. Так вы сможете отладить скрипт у себя локально и исключить проблему зависимостей скрипта от внешних утилит.

run_phpstan:
  stage: quality_check    
  image: phpstan/phpstan     # образ с docker hub
  tags:
    - docker                 # чтобы использовать runner на базе docker-executor
  script:
    - ci/bin/run_phpstan.sh
  1. Для отладки образов, часто бывает удобным запустить его в контейнере и зайти в терминал:
$ docker pull REGISTRY/project:tag
$ docker run -it REGISTRY/project:tag sh

> ls

Выполнение внутри docker-контейнера (Docker in Docker)

Чтобы использовать runner с docker'ом, нужно указать тег docker:

build:
  tags:
    - docker                 # <- чтобы использовать runner на базе docker-executor
  image: node:latest         # <- из какого образа запускать контейнер (можно также задать глобально для всех стадий) https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#define-image-and-services-from-gitlab-ciyml
  script:
    - npm install          # <- это выполниться уже в запущенном контейнере

Тоже самое с shell-executor:

build:
  tags:
    - shell                   # <- выбор shell-runner
  script:
    - export DOCKER_USER=$(id -u):$(id -g)
    - docker run --user ${DOCKER_USER} -v "${PWD}:/data" -w "/data" node:9.11.1   npm install

Gitlab Registry

По умолчанию runner'ы не имеют доступа к Gitlab Regitry. Чтобы можно было выполнять pull/push образов, потребуется авторизоваться:

before_script:
  - docker login -u gitlab-ci-token -p ${CI_JOB_TOKEN} ${CI_REGISTRY};

Параметры CI_JOB_TOKEN и CI_REGISTRY описаны в (документации gitlab)

Сборка образа и push (doc):

docker build -t GITLAB_REGISTRY/group/subgroup/project .
docker push GITLAB_REGISTRY/group/subgroup/project

Обратите внимание, что для использования docker, нужно использовать image: "docker:latest" или tags: [shell].

Получение публичных ключей

Публичный ключ любого пользователя запрашивается по адресам формата:

https://gitlab.apliteni.com/USERNAME.keys

Тегирование релизов

В Gitlab еще не реализован механизм создания тегов через CI, но можно использовать API:

#!/usr/bin/env bash
set -e -x -o pipefail

curl -X POST --show-error --fail "https://{GITLAB_URL}/api/v4/projects/${CI_PROJECT_ID}/repository/tags?ref=${CI_COMMIT_SHA}&tag_name=${APP_VERSION}&private_token=${GITLAB_TOKEN}"
  • GITLAB_URL - URL Gitlab'а.
  • CI_PROJECT_ID - ID проекта. Пробрасывается самим Gitlab CI.
  • CI_COMMIT_SHA - SHA коммита. Пробрасывается самим Gitlab CI.
  • APP_VERSION - версия продукта или деплоя.
  • GITLAB_TOKEN - персональный токен (Personal Access Tokens). Желательно использовать не свой токен, а создавать его у пользователя Bot.

← DevOps →