Gitea Actions: Руководство по CI/CD в Gitea

TIP

Эта статья — часть серии материалов на блоге SelfOps, посвящённой самостоятельному разворачиванию и администрированию open-source сервисов. Здесь мы глубоко погружаемся в тему Gitea Actions — встроенного механизма CI/CD в Gitea, который позволяет автоматизировать сборку, тестирование и развёртывание приложений прямо в вашем self-hosted Git-сервере.

Введение

Gitea — это легковесный, open-source Git-сервер с открытым кодом, разработанный с акцентом на простоту, производительность и возможность самостоятельного размещения (self-hosting). С выходом версии 1.20, выпущенной в апреле 2024 года, Gitea внедрил встроенную систему CI/CD, получившую название Gitea Actions.

Эта система вдохновлена GitHub Actions, но адаптирована под архитектуру Gitea и предназначена для работы в условиях ограниченных ресурсов — идеально для self-hosted окружений.

NOTE

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

🔧 Что такое Gitea Actions?

Gitea Actions — это встроенная система непрерывной интеграции и доставки (CI/CD), позволяющая автоматизировать процессы сборки, тестирования, линтинга, упаковки и развёртывания кода на основе событий в репозитории (например, push, pull_request, tag и др.).

Она использует YAML-описания в файле .gitea/workflows/*.yml (аналог .github/workflows в GitHub), что делает её знакомой для пользователей GitHub Actions.

Основные возможности

Поддержка Docker-контейнеров как среды выполнения.
Запуск параллельных заданий и зависимых этапов.
Работа с секретами (Environment Secrets).
Поддержка матричных сборок (matrix builds).
Кэширование зависимостей.
Автоматическое выполнение при событиях: push, pull_request, release, schedule и других.
Совместимость с стандартными шагами GitHub Actions (в большинстве случаев).

📦 Архитектура Gitea Actions

Gitea Actions построена на следующих компонентах:

Компонент	Описание
Gitea Server	Основной сервер, обрабатывающий события и планирующий выполнение workflow.
Runner	Встроенное или внешнее приложение, которое извлекает и выполняет задания. Начиная с 1.20, Gitea включает встроенный runner.
Workflow файлы	YAML-файлы в `.gitea/workflows/`, определяющие процессы.
Docker Engine	Требуется для изоляции и выполнения шагов в контейнерах.

WARNING

Для работы Gitea Actions обязательно наличие Docker на хосте, где запущен Gitea (или на удалённом runner’е). Без Docker — Actions не работают.

⚙️ Требования и настройка

Предварительные условия

Gitea версии 1.20 или выше.
Установленный Docker (или Docker-compatible runtime, например, Podman с docker-совместимостью).
Административный доступ к Gitea.
Включенный режим CI/CD в конфигурации.

Включение Gitea Actions

Отредактируйте файл конфигурации Gitea (app.ini):

[actions]
ENABLED = true
MANAGED_ACTIONS = true

IMPORTANT
После изменения app.ini перезапустите Gitea:
systemctl restart gitea

Встроенный Runner

Начиная с Gitea 1.20, встроенный runner включён по умолчанию. Он автоматически регистрируется как self-hosted runner и доступен для всех репозиториев.

Проверить статус runner’а можно в интерфейсе:

Настройки репозитория → Actions → Runners

TIP

Встроенный runner — это часть процесса Gitea, он использует Docker для запуска заданий. Убедитесь, что пользователь, от которого запущен Gitea, имеет доступ к Docker (docker group).

📄 Структура Workflow

Файлы workflow размещаются в директории .gitea/workflows/ в корне репозитория.

Пример базового файла .gitea/workflows/ci.yml:

name: CI Pipeline
 
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.22'
 
      - name: Build
        run: go build -v ./...
 
      - name: Test
        run: go test -v ./...

Ключевые элементы

Поле	Описание
`name`	Название workflow
`on`	Триггеры (события) запуска
`jobs`	Список заданий
`runs-on`	Тип runner’а (поддерживается `ubuntu-latest`, `self-hosted` и др.)
`steps`	Последовательность действий
`uses`	Подключение action’а (из репозитория)
`run`	Выполнение команды в shell

🧪 Поддерживаемые события (triggers)

Gitea Actions поддерживает широкий спектр событий:

on:
  push:
    branches: [ main ]
    tags: [ 'v*' ]
  pull_request:
    branches: [ main ]
  release:
    types: [ published ]
  schedule:
    - cron: '0 2 * * 1'  # Каждый понедельник в 2:00
  workflow_dispatch:  # Ручной запуск

INFO

Поддержка schedule и workflow_dispatch добавлена в Gitea 1.20. Подробнее: Gitea Docs — Workflow Syntax

🛠️ Примеры использования

1. Сборка и тестирование Go-приложения

name: Go CI
 
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.22'
 
      - name: Test
        run: go test -race -cover ./...
 
      - name: Build
        run: go build -ldflags="-s -w" -o myapp .

2. Сборка Docker-образа и пуш в Gitea Package Registry

Gitea поддерживает встроенный Docker-реестр. Пример публикации образа:

name: Docker Build and Push
 
on:
  push:
    tags: [ 'v*' ]
 
jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3
 
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
 
      - name: Login to Gitea Docker Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ secrets.DOCKER_REGISTRY }}
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
 
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ secrets.DOCKER_REGISTRY }}/myuser/myapp:${{ github.ref_name }}

NOTE

Перед использованием добавьте секреты в репозиторий:

DOCKER_REGISTRY: например, gitea.example.com:3000

DOCKER_USERNAME

DOCKER_PASSWORD

3. Автоматический деплой на сервер по SSH

name: Deploy to Production
 
on:
  push:
    branches: [ main ]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1.0.0
        with:
          host: ${{ secrets.PROD_HOST }}
          username: ${{ secrets.PROD_USER }}
          key: ${{ secrets.PROD_SSH_KEY }}
          script: |
            cd /var/www/myapp
            git pull origin main
            sudo systemctl restart myapp

4. Кэширование зависимостей (npm)

name: Node.js CI
 
on: [push, pull_request]
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
 
      - run: npm install
      - run: npm run build
      - run: npm test

TIP

Кэширование работает через actions/cache, который поддерживается в Gitea Actions.

🔐 Управление секретами

Секреты можно задавать на уровне:

Репозитория (Settings → Secrets and Variables → Secrets)
Организации
Системы (глобальные, для администраторов)

Используются в workflow через secrets.SECRET_NAME.

Пример:

env:
  DATABASE_URL: ${{ secrets.DATABASE_URL }}

WARNING

Секреты никогда не отображаются в логах. Gitea автоматически маскирует их.

🧩 Поддержка сторонних Actions

Gitea Actions поддерживает большинство GitHub Actions из actions/*, поскольку использует тот же формат.

Примеры совместимых actions:

actions/checkout@v4
actions/setup-go@v4
docker/login-action@v3
appleboy/ssh-action@v1

CAUTION

Не все действия будут работать. Некоторые зависят от GitHub-специфичных переменных окружения. Всегда тестируйте.

📊 Мониторинг и логи

После запуска workflow вы можете:

Просматривать ход выполнения в интерфейсе Gitea: Actions вкладка репозитория.
Читать логи в реальном времени.
Повторно запускать упавшие задания.
Просматривать артефакты (если сохранены).

🛡️ Безопасность

🔄 Отличия от GitHub Actions

Функция	Gitea Actions	GitHub Actions
Встроенность	Да	Да
Требует Docker	Да	Нет (GitHub-hosted runners)
Поддержка Windows runners	Нет	Да
Глобальные managed runners	Нет	Да
Бесплатно	Да (self-hosted)	Ограничено для публичных репозиториев
Поддержка `pull_request_target`	Частично	Да

📚 Официальная документация

Gitea Actions Overview — официальное руководство.
Workflow Syntax — полный синтаксис.
Actions Marketplace Compatibility — список совместимых actions.

🧰 Устранение неполадок

Проблема: Actions не запускаются

Проверьте, включены ли Actions в app.ini.
Убедитесь, что Docker работает.
Проверьте права пользователя Gitea на доступ к Docker.

Проблема: “Failed to start job: cannot connect to Docker daemon”

Добавьте пользователя Gitea в группу docker:
```
usermod -aG docker gitea
```
Перезапустите Gitea.

Проблема: Секреты не подставляются

Убедитесь, что секреты добавлены в нужный уровень (репозиторий/организация).
Проверьте синтаксис: secrets.MY_SECRET.

✅ Заключение

Gitea Actions — мощный инструмент для построения полностью автономной CI/CD-системы в рамках self-hosted Git-сервера. Он идеально вписывается в философию SelfOps и позволяет:

Полностью контролировать инфраструктуру.
Автоматизировать рутинные задачи.
Обеспечить безопасность и прозрачность процессов.

Это важный шаг вперёд для Gitea, делающий его серьёзным конкурентом GitLab CE и других self-hosted решений.

SUCCESS

Теперь вы можете создавать сложные пайплайны, автоматизировать деплой и тестирование, не выходя за пределы вашего Gitea-сервера.

SelfOps

Проводник

Gitea actions

Gitea Actions: Руководство по CI/CD в Gitea

Введение

🔧 Что такое Gitea Actions?

Основные возможности

📦 Архитектура Gitea Actions

⚙️ Требования и настройка

Предварительные условия

Включение Gitea Actions

Встроенный Runner

📄 Структура Workflow

Ключевые элементы

🧪 Поддерживаемые события (triggers)

🛠️ Примеры использования

1. Сборка и тестирование Go-приложения

2. Сборка Docker-образа и пуш в Gitea Package Registry

3. Автоматический деплой на сервер по SSH

4. Кэширование зависимостей (npm)

🔐 Управление секретами

🧩 Поддержка сторонних Actions

📊 Мониторинг и логи

🛡️ Безопасность

Рекомендации:

🔄 Отличия от GitHub Actions

📚 Официальная документация

🧰 Устранение неполадок

Проблема: Actions не запускаются

Проблема: “Failed to start job: cannot connect to Docker daemon”

Проблема: Секреты не подставляются

✅ Заключение

Вид графа

Оглавление

Обратные ссылки