Provision
—— XP

Файл .gitlab-ci.yml: стадии, задачи, правила

теория~6 минут+210 XP

Весь конвейер проекта, от проверки до выката, записан в одном файле в корне репозитория — .gitlab-ci.yml. GitLab читает его при каждом push: есть файл — запускает конвейер, нет — ничего не делает. Формат — обычный YAML, тот же, что у Compose в разделе 08, только ключи свои.

Хорошая новость: ключей, которые встречаются в каждом проекте, всего шесть. stages, image и script говорят, что и в каком порядке выполнять, needs — чего можно не ждать, rules — когда задачу запускать, а artifacts — что передать дальше. Раннер просто идёт по файлу сверху вниз, ничего не додумывая. В уроке разберём ключи по кусочку, а целиком файл ты соберёшь в практике.

Стадии и задачи

Начинается файл со списка стадий — в каком порядке они идут.

начало .gitlab-ci.yml
stages:
  - check
  - build
  - deploy

Дальше идут задачи. Задача — любой ключ верхнего уровня, кроме служебных; имя придумываешь сам.

одна задача
yaml-lint:
  stage: check
  image: python:3.12-slim
  script:
    - pip install yamllint
    - yamllint stand/

Разбор по строкам. stage — в какую стадию попадает задача. image — образ, в котором исполнитель docker запустит контейнер. script — команды, по одной на строку; они выполняются по очереди, и первая упавшая команда роняет задачу. Упавшая — значит вернувшая ненулевой код возврата из раздела 03: текст ошибки в журнале GitLab не читает.

Задачи одной стадии идут одновременно, если раннер может брать несколько. Стадия build начнётся только после того, как закончатся все задачи check. Если хоть одна упала, дальше конвейер не пойдёт.

Порядок по стадиям прост, но строг: быстрая задача следующей стадии ждёт самую медленную из предыдущей, даже если от неё не зависит.

needs: не ждать лишнего

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

Две временные диаграммы. Вверху без needs: стадии идут строго по очереди, итого семь минут пятьдесят секунд. Внизу с needs: сборка стартует сразу после линтера, итого четыре минуты пятьдесят секунд.
Без needs сборка ждёт самую медленную задачу своей стадии, даже если от неё не зависит. С needs очередь превращается в граф, и три минуты экономятся на каждом запуске.
зависимость сборки
build-image:
  stage: build
  needs: [yaml-lint]

Пустой список needs: [] значит «не жди никого» — так делают задачи, которые можно запускать сразу.

Пока же любая задача запускается на каждый push в любую ветку, а выкат из черновой ветки никому не нужен.

rules: когда запускать

Ключ rules — список условий. GitLab проверяет их сверху вниз, и первое подошедшее решает судьбу задачи. Ни одно не подошло — задачи в конвейере нет.

только в основной ветке
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Переменные со словом CI_ GitLab подставляет сам в каждую задачу. CI_COMMIT_BRANCH — ветка, в которую пришёл push, CI_DEFAULT_BRANCH — основная ветка проекта, у нас main. Значит, задача появится только после слияния в main. Ещё одна частая: $CI_PIPELINE_SOURCE == "merge_request_event" — конвейер запущен для merge request.

К условию можно добавить when: manual — тогда задача не запустится сама, а появится кнопкой «запустить». Так делают выкат.

В старых статьях вместо rules пишут only и except. Это прежний способ, менее гибкий; GitLab советует rules, и смешивать их в одной задаче нельзя.

Каждая задача при этом стартует в чистом окружении: то, что собрала предыдущая, в следующую само не попадёт.

artifacts и cache

Каждая задача работает в своём свежем контейнере, и файлы из прошлой задачи в нём не появятся. Чтобы передать результат, его объявляют артефактом.

сохранить файл после задачи
  artifacts:
    paths:
      - report.txt
    expire_in: 1 week

paths — что сохранить, expire_in — сколько хранить. Артефакты можно скачать на странице задачи в интерфейсе, и задачи следующих стадий получают их автоматически.

Кеш (cache) похож, но это лишь ускорение: скачанные пакеты, которые неплохо бы не качать заново. Кеш может пропасть, и конвейер обязан работать без него. Для джуна правило простое: результат — в artifacts, ускорение — в cache.

Словарь урока

Стадия
Ступень конвейера. Стадии идут по очереди, задачи внутри — одновременно. ↩ к тексту
script
Команды задачи. Первая с ненулевым кодом возврата роняет задачу.
needs
Настоящие зависимости задачи: стартует, как только готовы они, не дожидаясь всей стадии.
rules
Условия, при которых задача попадает в конвейер. Проверяются сверху вниз.
Артефакт
Файл, который задача сохраняет для следующих задач и для скачивания. ↩ к тексту

Что спросят на собеседовании

  • Команда в задаче напечатала ошибку, а задача зелёная. Почему?
    GitLab смотрит на код возврата, а не на текст. Если команда вернула 0 — например, ошибку проглотил конвейер команд без pipefail — задача считается успешной.
  • Как запустить выкат только по кнопке и только из main?
    Правило if с CI_COMMIT_BRANCH == CI_DEFAULT_BRANCH и when: manual. Внутри rules у ручной задачи allow_failure уже false; вне rules он true, и тогда конвейер может остаться зелёным, даже если выкат не нажат или упал.

Что дальше

Дальше — собрать из этих кусков настоящий конвейер проверок и увидеть его в интерфейсе.

Проверь себя+210 XPдве попытки
1
Стадии и задачи
Как идут задачи одной стадии?
2
Задача
По чему GitLab решает, что задача упала?
3
Правила
Что делает правило if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH?
4
Артефакты и кеш
Чем артефакты отличаются от кеша?
ответь на все вопросы, чтобы проверить

Нашёл ошибку или непонятное место? Наведи на абзац — слева появится «+», нажми и напиши, что не так. Замечание увидит автор курса.Нашёл ошибку или непонятное место? Нажми «+» справа от заголовка раздела и напиши, что не так. Замечание увидит автор курса.