Подключаем Runner для CI/CD в Gitea

В статье "Docker 6. Собственный GIT-сервис - Гид по быстрому запуску Gitea на вашем сервере!" мы настроили собственный git-сервер на базе Gitea. Теперь настало время расширить его функционал, добавив поддержку CI/CD с помощью раннеров (Runner).

Что вас ждёт в статье?

В этой статье мы начнём с теории: разберёмся, что такое CI/CD и какую роль в этом процессе играет Runner. Далее мы шаг за шагом настроим и развернём собственный раннер на сервере, а затем подключим его к вашему Gitea-серверу.

В этой статье:

• Разберёмся, что такое CI/CD ;
• Роль Runner в CI/CD;
• Настроим и развернём собственный раннер на сервере;
• Подключим его к вашему Gitea-серверу;

Разрабатывать сложные CI/CD-пайплайны мы не будем, но рассмотрим простой пример, чтобы убедиться, что всё настроено и готово к использованию.

Я буду ссылаться на прошлую статью "Docker 6. Собственный GIT-сервис - Гид по быстрому запуску Gitea на вашем сервере!" где это необходимо, поэтому рекомендую с ней ознакомиться.

Что такое CI/CD?

CI/CD (Continuous Integration / Continuous Delivery) — это подход к разработке, который автоматизирует процессы тестирования, сборки и доставки программного продукта, делая их непрерывными и более надёжными.

• Непрерывная интеграция (CI) — это процесс автоматического объединения изменений кода в общую ветку репозитория. Он включает автоматическое тестирование и анализ, чтобы гарантировать стабильность и безопасность проекта.
• Непрерывная доставка (CD) — это процесс, при котором изменения автоматически проходят через сборку, тестирование и развёртывание, чтобы попасть в рабочий продукт (на продакшен).

CI/CD позволяет разработчикам быстрее и безопаснее вносить изменения в проект, а также сокращает время на ручные проверки.

На самом деле, возможности и применение CI/CD значительно шире, но их детальное изучение выходит за рамки этой статьи и скорее относится к области DevOps.

Что такое Runner?

Runner — это специальное агентское ПО, которое выполняет задачи, связанные с CI/CD. Оно запускается на сервере и связывается с вашим git-сервером, таким как Gitea, GitHub, GitLab или любой другой платформой, поддерживающей CI/CD.

Основная задача Runner’а — принимать сигналы от git-сервера (например, после push-коммита) и запускать указанные в Workflow операции. Обычно Runner создаёт изолированный Docker-контейнер, где и выполняются все действия: сборка, тестирование или развёртывание.

Типы раннеров

Раннеры классифицируются по платформам, на которых они работают:

• Linux
• macOS
• Windows

Каждый Runner при настройке получает "теги", которые указывают, какие операционные системы и/или платформы он поддерживает. Например, если Runner развёрнут на Linux-сервере, он сможет запускать только задачи, совместимые с Linux. Собрать проект для Windows на таком Runner’е, скорее всего, не получится.

Gitea vs. GitHub

Gitea изначально поддерживает механизм автоматизации под названием "Gitea Actions", который по своей сути является аналогом GitHub Actions. Однако, чтобы сохранить лёгкость и простоту платформы, в Gitea, как и в любой другой self-hosted git-платформе, раннеры не встроены "из коробки". Их необходимо устанавливать и настраивать отдельно. В отличие от этого, GitHub предоставляет собственные встроенные раннеры для запуска действий, упрощая начальную настройку.

Что такое Actions?

Actions — это инструменты для автоматизации задач, таких как сборка, тестирование и развёртывание проектов, которые запускаются на основе событий, происходящих в репозитории. Они позволяют создавать рабочие процессы (workflows), упрощая выполнение повторяющихся задач и ускоряя разработку.

Сходства между GitHub Actions и Gitea Actions:

• Оба сервиса тесно интегрированы со своими платформами для хостинга Git-репозиториев.
• Оба позволяют создавать рабочие процессы для автоматизации задач.
• Поддерживают широкий спектр инструментов и языков программирования для выполнения заданий.

Отличия:

• GitHub Actions разрабатывается компанией GitHub и предлагает более обширный функционал, включая встроенные раннеры и интеграции с множеством сторонних сервисов.
• Бесплатные пользователи в GitHub сталкиваются с ограничениями по количеству минут для выполнения действий.
• Gitea Actions — это решение от сообщества с открытым исходным кодом. Оно предоставляет аналогичные возможности, но требует настройки и установки раннеров вручную, что даёт больше гибкости для тех, кто хочет полный контроль над своей инфраструктурой.

Ограничения GitHub

Несмотря на то, что GitHub предоставляет бесплатный доступ к Actions, для пользователей без подписки есть ряд ограничений:

1. Суммарное время выполнения действий: 2000 минут в месяц. Это достаточно много для небольших проектов, но может быть ограничением для активной разработки или нескольких репозиториев.
2. Суммарный объём хранимых артефактов и пакетов: 500 МБ. Это ограничение может стать серьёзной проблемой, если вы собираете Docker-образы или храните большие артефакты, особенно если вам важна их версионность.
3. Actions недоступны бесплатно для приватных репозиториев. Это одно из самых существенных ограничений, поскольку делает GitHub Actions практически бесполезными для частных проектов, не являющихся открытым исходным кодом.

Таким образом, хотя GitHub предоставляет мощные инструменты для работы с CI/CD, ограничения бесплатного плана могут свести на нет все преимущества.

Ограничения Gitea

У Gitea нет таких ограничений, как у GitHub, но есть несколько нюансов, которые стоит учитывать:

1. Требуется сервер. Для работы Gitea и её раннеров необходим собственный сервер, что влечёт за собой дополнительные затраты и ответственность за настройку и обслуживание.
2. Ограниченный функционал Actions. В некоторых аспектах Gitea Actions может уступать GitHub Actions, особенно если речь идёт о сложных интеграциях с внешними сервисами.
3. Непостоянное обновление функционала. Gitea — это проект с открытым исходным кодом, поэтому новый функционал появляется нерегулярно, в зависимости от активности сообщества.

Преимущества Gitea перед GitHub

Несмотря на указанные нюансы, Gitea обладает рядом весомых преимуществ:

1. Полный контроль. Gitea — это self-hosted решение. Развернув его на своём сервере, вы полностью управляете всеми аспектами работы: способами авторизации и регистрации, уровнями доступа к репозиториям и другими настройками.
2. Кастомизация. Gitea позволяет настраивать практически всё: от логотипа и тем оформления до предустановленных шаблонов Readme.
3. Отсутствие ограничений на Actions и хранилище. Единственные ограничения — это ресурсы вашего сервера: вычислительная мощность и объём дискового пространства. Вы можете хранить любое количество артефактов и пакетов, а также запускать рабочие процессы без лимитов.

Наш git-сервер!

Если по каким-либо причинам вы не хотите использовать GitHub или другие подобные платформы, мы предлагаем вам рассмотреть наш проект — "GIT на салфетке".

Что мы предлагаем:

• Удобные репозитории: Вы можете создавать как публичные, так и приватные репозитории для своих проектов. Не нужно беспокоиться о сложных настройках — все готово к работе сразу после регистрации.
• Гибкость с раннерами: Если вам нужно интегрировать автоматические процессы CI/CD, вы можете подключить свои собственные раннеры. Это обеспечит удобство и позволит настроить работу в точности под ваши нужды.
• Все возможности Gitea: Наша платформа использует Gitea, что предоставляет вам доступ ко всем её мощным возможностям. Это включает в себя управление репозиториями, систему pull-запросов, встроенную вики и многое другое.
• Минимум настроек, максимум возможностей: Забудьте о трудоемком обслуживании собственного инстанса. Мы полностью позаботились о развертывании и обслуживании инфраструктуры, оставив вам только приятную работу с проектами.
• Безопасность и доступ: Мы предоставляем надежную систему доступа, чтобы вы могли быть уверены в безопасности своих данных. Возможность настройки приватных репозиториев и управления доступом к ним — в распоряжении администраторов.

Если вы ищете простое и удобное решение для хранения ваших проектов, не нужно тратить время на настройку и обслуживание собственного git-сервера. Наш сервис — это ваш надежный инструмент для работы над проектами, который всегда под рукой.

Подключайтесь и начинайте пользоваться возможностями прямо сейчас!

Раннеры в Gitea

В Gitea раннеры отличаются по "областям видимости", то есть уровням доступа:

• Персональный — раннер, добавленный в вашу учётную запись. Он доступен только для ваших публичных и приватных репозиториев.
• Репозиторий — раннер, привязанный к определённому репозиторию. Его использование ограничено этим репозиторием.
• Организация — раннер, доступный для всех репозиториев в рамках одной организации.

Кроме того, существует ещё один уровень, управляемый администратором:

• Серверный — раннер, добавляемый администратором, который будет доступен всем пользователям сервера.

Важное замечание

Один раннер может быть только одного типа. Это значит, что:

• Нельзя использовать один и тот же раннер для нескольких репозиториев.
• Раннер, привязанный к организации, не будет доступен для персональных репозиториев пользователя.

Если вам нужно покрыть несколько репозиториев или уровней видимости, необходимо запускать несколько копий раннера и регистрировать их отдельно. О том, как это сделать, мы расскажем далее.

Как добавить раннер?

Рассмотрим процесс добавления раннера на уровне репозитория. Для других уровней процедура аналогична.

Открываем репозиторий 
Создайте новый или откройте уже существующий репозиторий. Если не знаете, как это сделать, обратитесь к предыдущей статье "Docker 6. Собственный GIT-сервис - Гид по быстрому запуску Gitea на вашем сервере!".

Переходим в настройки репозитория 
В верхней части страницы нажмите кнопку "Настройки": 

Выбираем раздел "Раннеры" 
В меню слева перейдите в раздел "Действия", затем выберите вкладку "Раннеры": 

Как видите, у меня уже есть один раннер — на него не обращаем внимания.

Создаём новый раннер 
В правой части экрана нажмите большую синюю кнопку "Создать новый раннер": 

Получаем токен регистрации 
В открывшемся меню появится токен для регистрации раннера, скопируйте его:
wJg5E5NS0KiUdcS8MBii1LZ6gLg22CDkTags1XgP 
Этот токен понадобится нам на следующем этапе.

На этом работа с веб-интерфейсом Gitea завершена. Теперь переходим к настройке раннера на сервере.

Что делать, если раздела "Действия" нет?

Если в вашей версии Gitea отсутствует раздел "Действия", возможно, действия отключены по умолчанию. Это актуально для версий до 1.21.0. Чтобы включить их, есть два варианта решения:

1. Обновите версию Gitea

Самый надёжный и рекомендуемый способ — обновить Gitea до актуальной версии. Для этого:

• Откройте ваш файл docker-compose.yaml с настройками Gitea.
• В параметре image укажите последнюю доступную версию. Например:
  yaml image: gitea/gitea:1.22.6-rootless 
  На момент написания статьи актуальная версия — 1.22.6.

После обновления перезапустите контейнер:

docker-compose down && docker-compose up -d  

2. Включите действия вручную

Если обновление невозможно, вы можете включить действия вручную:

1. Найдите файл app.ini в локальной директории config, подключённой к контейнеру.
2. Добавьте в конец файла следующий блок:
   [actions] ENABLED=true
3. Перезапустите контейнер Gitea, чтобы изменения вступили в силу.

Что выбрать?

Мы рекомендуем использовать первый вариант, поскольку обновление не только активирует новые функции, но и исправляет ошибки и уязвимости.

Запуск раннера на VPS

Подключаемся к серверу по SSH. Если вы не знаете, как это сделать или как настроить VPS, ознакомьтесь со статьёй "Гайд по первоначальной настройке VPS".

Все команды выполняются из домашней директории авторизованного пользователя, но вы можете выбрать любую удобную для вас директорию.

Создаём директорию для раннеров

Создадим директорию gitea_runners и перейдём в неё:

mkdir gitea_runners && cd gitea_runners

Чтобы сразу предусмотреть возможность запуска нескольких раннеров, создадим внутри gitea_runners отдельную директорию для первого раннера — runner-1 — и перейдём в неё:

mkdir runner-1 && cd runner-1

В дальнейшем для запуска дополнительных раннеров можно будет просто создавать аналогичные директории (runner-2, runner-3 и т.д.) и настраивать их по аналогии.

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

В директории раннера создадим файл config.yaml. Этот файл будет содержать основные настройки раннера.

Откроем его в редакторе nano. Если файла ещё нет, он создастся автоматически после сохранения:

nano config.yaml

Вставляем следующую конфигурацию:

log:
  level: info

runner:
  file: .runner
  capacity: 1
  timeout: 3h
  insecure: false
  fetch_timeout: 5s
  fetch_interval: 2s
  labels: ["ubuntu-latest:docker://gitea/runner-images:ubuntu-latest", "ubuntu-22.04:docker://gitea/runner-images:ubuntu-22.04"]

cache:
  enabled: true
  dir: ""
  host: "1.2.3.4"
  port: 8088
  external_server: ""

container:
  network: ""
  privileged: false
  options:
  workdir_parent:
  valid_volumes: []
  docker_host: ""
  force_pull: false

host:
  workdir_parent:

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

Ключевые параметры конфигурации:

• log.level — уровень логирования. Возможные значения: от info до critical.
• runner.capacity — количество задач, которые раннер может обрабатывать одновременно. Настраивайте в зависимости от ресурсов вашего сервера. Если сервер справляется с нагрузкой, можно увеличить значение.
• runner.labels — теги раннера. Они позволяют ограничить задачи, которые раннер будет выполнять. По умолчанию установлены ubuntu-latest и ubuntu-22.04, но вы можете добавить свои. Обратите внимание: Linux-раннер не сможет выполнять задачи для Windows или macOS.
• cache.enabled — включение кэширования. Рекомендуется оставить true, чтобы ускорить повторное выполнение задач.
• cache.host — IP-адрес сервера для кэширования. Указывайте конкретный IP-адрес. Не оставляйте поле пустым или значением 0.0.0.0, чтобы избежать конфликтов.
• cache.port — порт для кэширования. Убедитесь, что порт свободен и не используется другими раннерами.

Все остальные параметры можно настроить по необходимости.

Сохраняем файл комбинацией клавиш CTRL+S, затем выходим из редактора с помощью CTRL+X.

Возвращаемся в директорию gitea_runners:

cd ..

Конфигурация Docker Compose

Находясь в директории gitea_runners, создаём файл docker-compose.yaml при помощи nano:

nano docker-compose.yaml

Вставляем следующую конфигурацию:

services:
  runner-1:
    image: gitea/act_runner:nightly
    restart: always
    environment:
      - CONFIG_FILE=/config.yaml
      - GITEA_INSTANCE_URL=https://git.pressanybutton.ru/
      - GITEA_RUNNER_REGISTRATION_TOKEN=wJg5E5NS0KiUdcS8MBii1LZ6gLg22CDkTags1XgP
    volumes:
      - ./runner-1/config.yaml:/config.yaml
      - ./runner-1/data:/data
      - ./runner-1/cache:/root/.cache
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "8088:8088"

Пояснение конфигурации:

• image: gitea/act_runner:nightly — указывает используемый образ раннера.
• restart: always — контейнер будет автоматически перезапускаться при возникновении ошибок.
• environment: — переменные окружения, передаваемые контейнеру:
  • CONFIG_FILE=/config.yaml — путь к файлу конфигурации.
  • GITEA_INSTANCE_URL= — URL-адрес вашего Gitea-сервера.
  • GITEA_RUNNER_REGISTRATION_TOKEN= — токен для регистрации раннера, полученный ранее.
• volumes: — монтируемые директории и файлы:
  • ./runner-1/config.yaml:/config.yaml — подключаем файл конфигурации раннера.
  • ./runner-1/data:/data — директория для данных раннера.
  • ./runner-1/cache:/root/.cache — директория для кэширования.
  • /var/run/docker.sock:/var/run/docker.sock — передаём Docker-сокет для работы контейнера.
• ports: — указываем открытые порты:
  • "8088:8088" — внешний и внутренний порты. Убедитесь, что порт не используется другими сервисами. Лучше оставить внешний и внутренний порты одинаковыми, чтобы избежать путаницы.

Сохраняем файл с помощью CTRL+S, затем выходим из редактора, нажав CTRL+X.

Запуск раннера

Для запуска раннера выполните команду:

sudo docker compose up -d

Команда инициирует процесс скачивания и запуска образа раннера.

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

sudo docker logs gitea_runners-runner-1-1

Если всё настроено правильно, в выводе логов должно быть сообщение:

level=info msg="Runner registered successfully."

Теперь вернитесь на страницу настроек раннеров в вашей Gitea и обновите её. Если настройка прошла успешно, вы увидите добавленный раннер:

Тестовый Workflow

Чтобы проверить, как отрабатывает наш раннер, создадим простой тестовый workflow прямо в репозитории.

В будущих статьях мы подробно разберём CI/CD, включая добавление workflow в уже существующие проекты.

Перейдите на вкладку "Код" в вашем репозитории.

Нажмите на кнопку "Новый файл".

Файлы для workflow должны располагаться в директории .gitea/workflows/ и иметь расширение .yaml. Создадим файл test.yaml с полным путём:

.gitea/workflows/test.yaml

Введите следующее содержимое в файл:

name: Test Workflow  

on:  
  push:  

jobs:  
  test:  
    runs-on: ubuntu-latest  

    steps:  
      - name: Print environment variables  
        run: |  
          echo "GITHUB_REPOSITORY: $GITHUB_REPOSITORY"  
          echo "GITHUB_SHA: $GITHUB_SHA"  
          echo "GITHUB_REF: $GITHUB_REF"  
          echo "GITHUB_ACTOR: $GITHUB_ACTOR"  
          echo "PATH: $PATH"

Что мы указали в этом файле:

• name — имя workflow.
• on — условия для выполнения workflow, в данном случае он будет срабатывать при каждом пуше в репозиторий.
• jobs — перечень задач, выполняемых в workflow.
• test — имя задачи.
• runs-on — что использовать для выполнения задачи (убедитесь, что ваш раннер поддерживает этот тег).
• steps — шаги задачи.
  • name — имя шага.
  • run — команда, которая будет выполнена. В данном примере выводятся переменные окружения, такие как репозиторий, хэш коммита, реф и другие.

Нажмите "Сохранить правки" внизу страницы.

Перейдите в раздел "Действия", где вы увидите запущенный Workflow.

Кликнув на workflow, откроется подробная информация о его выполнении. В левой части экрана расположены задачи, а в правой — шаги.

На первом шаге всегда выполняется Set up job, который отвечает за скачивание всех необходимых "Actions", например, actions/checkout для клонирования репозитория или actions/setup-python для установки Python.

Далее идут прописанные шаги. В нашем примере это один шаг с выводом переменных окружения. Кликнув на шаг, откроется лог выполнения, в котором вы увидите значения переменных.

Последним шагом всегда будет "Complete job", который завершает работу, сохраняет данные в кэш и удаляет лишние файлы.

Заключение

Gitea — это удобный и гибкий git-сервер, который с подключенными к нему раннерами становится мощным инструментом для автоматизации процессов CI/CD. С помощью Gitea вы получаете надежную платформу для хранения и управления кодом, а с интеграцией раннеров можно значительно упростить и ускорить процессы тестирования, сборки и развертывания.

В будущих статьях мы более подробно разберём возможности CI/CD и расскажем о том, как запускать тестирование проектов, собирать Docker-образы и сохранять их в репозитории образов Gitea. Также мы рассмотрим, как автоматизировать процесс разворачивания проектов на сервере при изменениях в репозитории.

Не забывайте, что наш "GIT на салфетке" предоставляет вам удобный и безопасный способ работы с репозиториями и интеграции с CI/CD, не требуя сложных настроек и обслуживания. Всё, что нужно для эффективной работы — это просто подключить свой репозиторий и настроить раннеры.

Следите за обновлениями, и в следующих статьях вы получите ещё больше полезных советов для улучшения ваших рабочих процессов с Gitea!