Файл gitlab-ci.yml

Файл .gitlab-ci.yml является ключевым элементом в экосистеме GitLab CI/CD, определяя как должны выполняться автоматизированные задачи по тестированию, сборке и развертыванию вашего проекта. Файл использует YAML человекочитаемый формат данных для конфигурации пайплайнов. Понимание структуры и синтаксиса этого файла позволит вам эффективно настраивать процессы CI/CD для ваших проектов.

Синтаксис файл gitlab-ci.yml

В файле конфигурации .gitlab-ci.yml используется ряд ключевых элементов синтаксиса, позволяющих настроить поведение пайплайнов. Подробнее рассмотрим основные элементы.

stages:
  - build
  - test
  - deploy

build_job:
  stage: build
  script:
    - echo "Сборка кода..."

test_job:
  stage: test
  script:
    - echo "Запуск тестов..."

deploy_job:
  stage: deploy
  script:
    - echo "Развертывание приложения..."

build:
 image: ubuntu:24.04
 stage: build
 tags:
   - cloud-runner
 script:
   - docker build -t "image:tag" -t "image:latest" --push.

before_script:
  - echo "Выполнение предварительных скриптов..."
  - setup-environment.sh

after_script:
  - echo "Завершающие действия..."
  - cleanup-environment.sh

variables:
  PROJECT_ENV: "production"
  DEPLOY_PATH: "/var/www/html"

include:
  - project: 'my-group/my-project'
    ref: master
    file: '/templates/.template.yml'
  
  - local: '/ci/common.yml'

artifacts:
  paths:
    - build/
  expire_in: 1 week

cache:
  paths:
    - project-venv

image: ruby:2.7

services:
  - mysql:9

only:
  - master
  - develop
except:
  - v.*

rules:
   - if: $CI_COMMIT_BRANCH
      exists:
        - Dockerfile

build-job:
  stage: build
  script:
    - build-project.sh
  tags:
    - linux
    - docker

environment:
  name: production
  url: https://prod.example.com

build:
  stage: build
  script:
    - echo "This build can be canceled."
  interruptible: true

parallel:
  matrix:
    - TEST_SUITE: ["unit", "integration"]

workflow:
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
    - changes:
        - path/to/directory/**
        - "*.config"

Основные элементы синтаксиса.

Работа с Jobs

Конфигурация задачи в CI/CD представляет собой инструмент для организации и управления пайплайнами непрерывной интеграции и доставки. Благодаря гибкости настройки этапов, зависимостей и условий выполнения задач, разработчики могут создавать сложные пайплайны, оптимизированные под конкретные потребности проекта, что способствует ускорению процессов разработки и обеспечению высокого качества продукта.

Конфигурация Stages

Конфигурация этапов stages в CI/CD играет важную роль в организации и управлении жизненным циклом разработки программного обеспечения. Она позволяет разработчикам структурировать пайплайн развертывания таким образом, чтобы различные задачи jobs, такие как сборка build, тестирование test, развертывание deploy, выполнялись в определенном, логически обоснованном порядке. Этот подход не только обеспечивает четкое разделение ответственности между различными этапами разработки, но и повышает эффективность и надежность процессов.

Порядок, в котором этапы перечислены в секции stages файла .gitlab-ci.yml, непосредственно определяет последовательность их выполнения в пайплайне. Эти этапы организуются таким образом, чтобы каждый последующий этап начинался только после полного и успешного завершения всех задач предыдущего этапа. Это гарантирует, что все необходимые предварительные условия и зависимости удовлетворены перед переходом к следующему шагу:

stages:
  - build
  - test
  - deploy

GitLab CI/CD предоставляет два механизма для управления зависимостями между задачами, dependencies и needs:

test1:
  stage: test
  dependencies:
    - compile

test2:
  stage: test
  needs:
    - compile

Одной из основных преимуществ структурирования пайплайнов с использованием stages является возможность параллельного выполнения задач внутри одного этапа. Это позволяет оптимизировать использование ресурсов и сократить общее время выполнения пайплайна. GitLab автоматически запускает все задачи одного этапа параллельно, если только не ограничено зависимостями dependencies или потребностями needs:

stages:
  - build
  - test
  - deploy

build_job_1:
  stage: build
  script:
    - echo "Building part 1..."

build_job_2:
  stage: build
  script:
    - echo "Building part 2..."

Определение и настройка Jobs

Jobs задача является основным строительным блокам пайплайнов в GitLab CI/CD. Каждая задача определяет набор операций, которые должны быть выполнены: это может быть сборка кода, выполнение тестов, развертывание приложения и т.д.

Ключевой элемент каждой задачи script, содержит команды или скрипты, выполняемые в рамках задачи.

test-job:
  stage: test
  script:
    - echo "Запуск тестов..."
    - run-tests.sh

В этом примере задача test-job находится на этапе test и выполняет две команды: вывод сообщения и запуск скрипта run-tests.sh.

Дириктивы only и except

only и except это директивы, позволяющие контролировать когда задача должна выполняться, основываясь на различных условиях, таких как ветки, теги или переменные среды.

only определяет условия, при которых задача будет выполняться. Если условия совпадают, задача включается в пайплайн:

deploy-job:
  stage: deploy
  script:
    - deploy-application.sh
  only:
    - master
    - tags

Здесь deploy-job будет выполняться только если изменения сделаны в ветке master или если был установлен тег.

except указывает условия, при которых задача не будет выполняться. Если условия совпадают, задача исключается из пайплайна:

experimental-test-job:
  stage: test
  script:
    - experimental-tests.sh
  except:
    - master

В этом примере experimental-test-job будет исключена из выполнения, если изменения сделаны в ветке master.

Очистка

GitLab CI/CD позволяет автоматизировать процессы очистки с помощью директивы on_stop в определении окружения, где environment позволяет определить окружение, в котором выполняется задача. Это может быть любая среда, например, тестовая, стейджинг или продуктовая. Каждое окружение может иметь свою уникальную конфигурацию и жизненный цикл. Директива on_stop в определении environment используется для указания задачи, которая должна быть выполнена для остановки или удаления этого окружения. Это особенно полезно для временных окружений, создаваемых для ревью кода или тестирования, которые необходимо очистить после использования:

stop_review:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script:
    - echo "Removing review environment..."
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_NAME
    action: stop
  only:
    - branches
  except:
    - main

С появлением и развитием контейнеризации, GitLab CI/CD обеспечивает интеграцию с Docker и Kubernetes, позволяя легко собирать, тестировать и развертывать контейнеризированные приложения. Использование services для запуска вспомогательных сервисов, таких как базы данных или кэширующие системы, упрощает тестирование приложений в условиях, максимально приближенных к продуктовой среде:

test:
  stage: test
  services:
    - postgres:latest
  script:
    - echo "Testing with PostgreSQL..."

Переменные

Переменные в GitLab CI/CD предоставляют механизм для динамической настройки пайплайнов. Они могут быть использованы для конфигурации задач на лету, позволяя задавать различные параметры без необходимости изменения самого файла .gitlab-ci.yml. Переменные могут быть определены на уровне GitLab CI/CD пайплайна в файле .gitlab-ci.yml, на уровне проекта или группы в настройках GitLab, а также могут быть предоставлены как переменные среды в Runner.

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

• Конфигурацию задач: определение специфических параметров, необходимых для выполнения скриптов сборки, тестирования и развертывания
• Управление средами: указание среды, в которую будет производиться развертывание, или настройка параметров, специфичных для среды
• Передачу секретов: безопасное предоставление чувствительной информации, такой как пароли, токены доступа или ключи API, без их явного указания в файле .gitlab-ci.yml

deploy:
  stage: deploy
  script:
    - deploy-to-env.sh $DEPLOY_ENV
  variables:
    DEPLOY_ENV: staging

В этом примере переменная DEPLOY_ENV используется для определения среды развертывания в задаче deploy. Значение staging указано напрямую в конфигурации задачи, однако оно может быть легко изменено или переопределено на уровне проекта или группы через настройки GitLab, а также может быть задано динамически через переменные среды в Runner.

Переменные в GitLab CI/CD могут быть определены на нескольких уровнях:

• Файл .gitlab-ci.yml непосредственное определение переменных в конфигурации пайплайна позволяет задать стандартные значения или специфичные настройки для задач
• Настройки проекта или группы переменные, заданные на уровне проекта или группы в GitLab, автоматически применяются ко всем пайплайнам в рамках этого проекта или группы. Это удобно для глобальных настроек или секретов.
• Переменные среды Runner эти переменные могут быть заданы на уровне Runner и являются полезными для конфигурации окружения, в котором выполняются задачи

Одной из ключевых особенностей переменных в GitLab CI/CD является возможность их переопределения на разных уровнях. Это позволяет, например, задать значение переменной по умолчанию в файле .gitlab-ci.yml, но при необходимости изменить его на уровне проекта для конкретного запуска пайплайна или даже передать другое значение через переменные среды Runner, обеспечивая тем самым высокую степень гибкости и адаптации к различным условиям выполнения задач.

Артефакты

Артефакты это файлы и директории, генерируемые в результате выполнения задач в пайплайне. Они используются для сохранения важных результатов работы, таких как результаты сборки, тестовые отчеты, логи, или любые другие данные, которые необходимо сохранить после завершения задачи. Артефакты могут быть переданы между задачами в рамках одного пайплайна или сохранены для доступа после его завершения:

test:
  stage: test
  script:
    - run-tests.sh
  artifacts:
    paths:
      - test-results/
    expire_in: 2 days
    when: always

В приведенном примере задача test генерирует артефакты в директории test-results, которые сохраняются на срок до 2 дней. Опция when: always гарантирует сохранение артефактов независимо от результата выполнения задачи.

Кэширование

Кэширование предназначено для временного хранения файлов и директорий, которые используются между различными запусками задач. Это особенно актуально для зависимостей проекта, позволяя не загружать их каждый раз, когда выполняется пайплайн. Кэширование сокращает время на сборку и тестирование, оптимизируя использование ресурсов:

build:
  stage: build
  script:
    - npm install
  cache:
    paths:
      - node_modules/
    key: ${CI_COMMIT_REF_SLUG}

В данном примере paths указывает директории или файлы, которые необходимо кэшировать. В этом случае кэшируется директория. node_modules указывает где npm сохраняет зависимости проекта. key определяет ключ кэша, который используется для ассоциации кэша с конкретными задачами и условиями. В примере ключ кэша задается как ${CI_COMMIT_REF_SLUG}, что означает использование уникального идентификатора ветки в качестве ключа. Это позволяет каждой ветке иметь свой собственный кэш, предотвращая конфликты и некорректное использование зависимостей между различными ветками.

GitLab CI/CD предоставляет различные стратегии управления кэшем, такие как:

• policy: pull кэш будет только загружаться, но не обновляться в результате выполнения задачи
• policy: push кэш будет обновляться после выполнения задачи, но не загружаться при ее старте
• policy: pull-push (по умолчанию) кэш будет загружаться перед выполнением задачи и обновляться после ее завершения

Преимущества кэширования:

• Уменьшение времени сборки за счет повторного использования уже скачанных или сгенерированных данных.
• Экономия ресурсов уменьшает нагрузку на сеть и серверы хранения, поскольку уменьшается количество необходимых загрузок из внешних источников.
• Гибкость конфигурации ключи кэша и стратегии позволяют настроить кэширование с учетом специфики проекта и рабочих процессов

Хотя артефакты и кэширование служат различным целям, вместе они обеспечивают гладкое и быстрое выполнение пайплайнов в GitLab CI/CD. Артефакты обеспечивают сохранение и передачу важных результатов работы между задачами или после завершения пайплайна, в то время как кэширование ускоряет пайплайны, позволяя повторно использовать данные между запусками. Использование обоих механизмов позволяет разработчикам оптимизировать CI/CD процессы, сокращая время ожидания и повышая эффективность разработки.