Gitea Actions: Git-платформа і pipeline на одному сервері

Gitea Actions: Git-платформа і pipeline на одному сервері

У третій і четвертій частинах ми переносили на власний сервер виконання задач. Код при цьому лишався там, де й був: у GitHub або GitLab. Для більшості команд це правильний баланс, бо адмініструвати доводиться лише агента. Але є задачі, де такий поділ не проходить, і тоді на ваш сервер переїжджає вся система разом з репозиторієм.

Ця частина про Gitea і її вбудований CI. Піднімемо git-платформу на VPS, підключимо до неї act runner, напишемо workflow у синтаксисі, який ви вже знаєте з третьої частини, і завершимо тим самим деплоєм через SSH. Наприкінці розберемо, у якому місці «повністю закритий контур» лишається неповним, якщо його не добудувати свідомо.

1.1 Коли self-hosted runner недостатньо

Власний агент вирішує питання ресурсів і доступу до закритої мережі, але не змінює головного: репозиторій, історія комітів, issues і код-рев'ю живуть на чужій платформі. Ситуації, де це стає перешкодою:

• Договірні зобов'язання. Замовник вимагає, щоб вихідний код не залишав його периметра, і формулювання у договорі не робить винятку для хмарного git-хостингу.
• Робота без доступу до інтернету. Ізольований контур, де зовнішніх з'єднань немає взагалі, а не просто обмежені.
• Незалежність від постачальника. Зміна умов ліцензування, тарифів або доступності сервісу не повинна зупиняти розробку.
• Вартість при великій команді. Оплата за користувача на кількох десятках акаунтів помітно перевищує ціну VPS.

1.2 Що дає повністю закритий контур

Коли git-платформа і CI стоять на вашому сервері, зникає зовнішня залежність у щоденній роботі: розробка продовжується, навіть якщо зовнішній канал недоступний. Дані з приватного репозиторію не передаються стороннім сервісам, а обмеження доступу описуються вашими правилами.

Ціна цього рішення пряма. Ви відповідаєте за бекапи репозиторіїв і бази, за оновлення платформи і закриття вразливостей, за доступність сервера у робочий час. Хмарний GitHub це робить непомітно, ваш сервер вимагає, щоб хтось цим займався.

1.3 Що ще є у цій ніші

Розвилка тут така. Gitea і Forgejo дають дві системи в одній: git і CI ставляться разом, конфігурація одна, синтаксис знайомий по GitHub. Gogs у парі з Woodpecker дає більшу гнучкість і незалежність частин, ціною двох окремих сервісів, які треба піднімати, оновлювати і зв'язувати між собою. Для першого власного контуру перший варіант простіший, і далі у статті ми йдемо саме ним.

2. Архітектура Gitea Actions

2.1 Gitea як git-платформа

Gitea це один бінарник на Go, який дає репозиторії, issues, pull request, огляд коду, вебхуки, організації і права доступу. У простому варіанті вона працює з SQLite і файловою системою, тобто без окремої бази і без додаткових сервісів. Для команди з десяти інженерів цього достатньо, для більшої інсталяції беруть PostgreSQL.

Споживання ресурсів помітно нижче, ніж у GitLab: сама Gitea тримається у межах сотень мегабайтів пам'яті. Різниця у тому, що GitLab це десяток пов'язаних сервісів, а Gitea один процес.

2.2 Gitea Actions: знайомий синтаксис

Gitea Actions з'явилися у версії 1.19 і повторюють модель GitHub Actions: workflow, задачі, кроки, дії через uses. Файли лежать у каталозі .gitea/workflows/, і більшість простих конфігурацій з третьої частини переносяться без правок.

Сумісність не повна, і межі корисно знати заздалегідь:

• Дії беруться з зовнішнього джерела. За замовчуванням uses: actions/checkout@v4 завантажується з GitHub. Для закритого контуру це доведеться змінити, і нижче ми до цього повернемось.
• Частина можливостей відсутня. Матриці працюють, кеш працює, а от середовища з підтвердженням від рецензента і частина складних конструкцій GitHub реалізовані не повністю або відрізняються поведінкою.
• Дії на JavaScript і композитні працюють, дії на контейнерах теж. А от усе, що звертається до GitHub API, у Gitea не запрацює.

2.3 Act runner: окремий процес

Задачі виконує act runner: окрема програма, побудована на проєкті act, який запускає workflow GitHub Actions локально. Логіка та сама, що у попередніх частинах: runner опитує Gitea, отримує задачу, готує оточення, виконує кроки і повертає логи.

Виконання буває двох типів. У режимі docker кожна задача працює у контейнері з образу, вказаного у мітці runner. У режимі host команди виконуються прямо на сервері, без ізоляції, і тоді все потрібне для збірки має бути встановлене заздалегідь.

2.4 Схема з'єднань

розробник
   │ git push (SSH або HTTPS)
   ↓
┌─────────────────────────────┐
│  Gitea                      │
│  репозиторій + вебінтерфейс │
│  черга задач Actions        │
└─────────────────────────────┘
   ↑ опитування черги по HTTP
   │ логи і статус
┌─────────────────────────────┐
│  act runner                 │
│  docker: контейнер на задачу│
│  host: команди на сервері   │
└─────────────────────────────┘
   │ SSH
   ↓
продакшн-сервер

Обидва компоненти можуть жити на одному VPS, і для невеликої команди так і роблять. Розділення на дві машини має сенс, коли збірки важкі: інтерфейс git не повинен гальмувати через те, що поруч виконується компіляція.

3. Встановлення Gitea на VPS

3.1 Ресурси

Мінімум для роботи це 1 vCPU і 1 ГБ RAM, і у такій конфігурації Gitea справді працює. Але окремо порахуйте runner: збірки споживають більше, ніж сама платформа. Робочі орієнтири:

• Тільки Gitea, невелика команда: 1 vCPU, 1 ГБ RAM, 20 ГБ диска.
• Gitea і act runner на одній машині: 2 vCPU, 4 ГБ RAM, від 40 ГБ диска.
• Збірки з Docker: 4 vCPU, 8 ГБ RAM і окремий погляд на диск, бо образи і шари ростуть швидко.

3.2 Встановлення

Варіант з бінарником прозоріший, коли ви розбираєтеся з системою вперше:

sudo apt update && sudo apt install git sqlite3 -y

# версію і посилання беріть зі сторінки завантажень Gitea
sudo wget -O /usr/local/bin/gitea "<посилання на бінарник linux-amd64>"
sudo chmod +x /usr/local/bin/gitea
gitea --version

# користувач і каталоги
sudo adduser --system --group --disabled-password --home /home/git git
sudo mkdir -p /var/lib/gitea/{custom,data,log} /etc/gitea
sudo chown -R git:git /var/lib/gitea /etc/gitea
sudo chmod 750 /var/lib/gitea
sudo chmod 770 /etc/gitea

Права на /etc/gitea навмисно широкі лише до кінця встановлення: веб-інсталятор запише туди app.ini, після чого каталог закривається.

Варіант з Docker коротший і зручніший для оновлень:

# compose.yaml
services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
    volumes:
      - ./gitea-data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"

3.3 Systemd-сервіс

Цей крок потрібен лише для варіанта зі встановленням бінарником вище. Якщо ви піднімали Gitea через Docker Compose, окремий systemd-юніт не потрібен: перезапуск і автозапуск контейнера вже забезпечує параметр restart: always у самому compose-файлі.

# /etc/systemd/system/gitea.service
[Unit]
Description=Gitea
After=network.target

[Service]
RestartSec=2s
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now gitea
sudo systemctl status gitea

3.4 Перший запуск

Інтерфейс відкривається на порту 3000. Веб-інсталятор запитує тип бази, шляхи до каталогів, домен і адресу інстанса, а внизу сторінки, у розділі з необов'язковими налаштуваннями, створюється адміністратор.

Чотири речі, які варто зробити одразу після встановлення:

• Створіть адміністратора на сторінці інсталятора. Інакше ним стане перший зареєстрований користувач.
• Вимкніть вільну реєстрацію. У app.ini це DISABLE_REGISTRATION = true у секції [service].
• Поставте HTTPS. Робочий варіант це Nginx або Caddy перед Gitea, з сертифікатом від Let's Encrypt і ROOT_URL, який відповідає зовнішній адресі.
• Закрийте права на конфіг. sudo chmod 750 /etc/gitea && sudo chmod 640 /etc/gitea/app.ini

4. Встановлення act runner

4.1 Бінарник

Act runner розповсюджується окремо від Gitea, посилання беріть зі сторінки релізів проєкту:

sudo wget -O /usr/local/bin/act_runner "<посилання на act_runner linux-amd64>"
sudo chmod +x /usr/local/bin/act_runner
act_runner --version

Для режиму docker потрібен встановлений Docker, а користувач, від якого працює runner, має входити до групи docker.

4.2 Реєстрація

Токен береться у одному з трьох місць, залежно від того, наскільки широко runner має обслуговувати систему:

• Репозиторій: Settings → Actions → Runners → Create new runner.
• Організація: той самий шлях у налаштуваннях організації.
• Уся інсталяція: Site Administration → Actions → Runners.

sudo mkdir -p /etc/act_runner && cd /etc/act_runner
act_runner generate-config > config.yaml

act_runner register --no-interactive \
  --instance https://git.example.com \
  --token <токен з інтерфейсу> \
  --name vps-runner-01 \
  --labels ubuntu-latest:docker://gitea/runner-images:ubuntu-latest,deploy:host

Мітки тут працюють інакше, ніж у попередніх частинах, і саме тут найчастіше плутаються. Мітка складається з трьох частин: ім'я, спосіб виконання і образ. Запис ubuntu-latest:docker://gitea/runner-images:ubuntu-latest означає: задача з runs-on: ubuntu-latest виконається у контейнері з цього образу. Запис deploy:host означає: задача з runs-on: deploy виконається прямо на сервері.

Схема з двома мітками повторює рішення з четвертої частини: збірки ізольовані у контейнері, деплой отримує доступ до ключів і мережі хоста.

4.3 Systemd-сервіс

# /etc/systemd/system/act_runner.service
[Unit]
Description=Gitea Act Runner
After=docker.service

[Service]
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
WorkingDirectory=/etc/act_runner
User=act_runner
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now act_runner
journalctl -u act_runner -f

4.4 Перевірка і увімкнення Actions

У списку runner-ів (Settings → Actions → Runners) агент має з'явитися зі станом Idle і переліком міток. Якщо його там немає, дивіться логи сервісу: типові причини це недоступна адреса інстанса, застарілий токен або відсутні права на сокет Docker.

Окремо перевірте, що Actions увімкнені на рівні інсталяції. У сучасних версіях так за замовчуванням, у старіших потрібен явний запис у app.ini:

[actions]
ENABLED = true

Після зміни конфігурації сервіс Gitea перезапускається. Для конкретного репозиторію Actions вмикаються окремо, у Settings → Repository → Advanced Settings.

5. Перший workflow

5.1 Де лежить конфігурація

Файли workflow кладуться у .gitea/workflows/. Каталог .github/workflows/ Gitea теж читає, що зручно при переїзді з GitHub: репозиторій переноситься як є і запускається без правок шляхів.

5.2 Базовий приклад

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npm run lint
      - run: npm test -- --ci

Файл ідентичний тому, що працював би у GitHub Actions. Значення runs-on тут це не назва хмарної машини, а мітка вашого runner, яку ви задали при реєстрації.

5.3 Тригери

Працюють push, pull_request, schedule і workflow_dispatch, а також події, специфічні для Gitea, на кшталт issues і release.

on:
  push:
    branches: [main]
    paths-ignore: ['**.md', 'docs/**']
  pull_request:
  schedule:
    - cron: '0 3 * * *'
  workflow_dispatch:

Розклад у Gitea має перевагу над хмарним варіантом: schedule виконується на вашому сервері без черг, тому запуск відбувається вчасно.

5.4 Перший запуск і логи

Після push відкривайте вкладку Actions у репозиторії: там список запусків, задачі і логи кроків у реальному часі. Інтерфейс упізнаваний з GitHub, хоча простіший.

Дві типові проблеми першого запуску:

• Задача висить у стані Waiting. Немає онлайн-runner з міткою, вказаною у runs-on. Порівняйте рядок у workflow з переліком міток на сторінці Runners.
• Крок з uses падає на завантаженні. Дія тягнеться з GitHub, а сервер не має туди доступу. Про це далі.

6. Практичний приклад: deploy через SSH

6.1 Секрети у Gitea

Механізм повторює GitHub: Settings → Actions → Secrets для значень, які маскуються у логах, і Variables для звичайних налаштувань. Секрети задаються на рівні репозиторію, організації або всієї інсталяції.

Додаємо три значення:

• SSH_PRIVATE_KEY — вміст приватного ключа повністю, разом з рядками BEGIN і END.
• SSH_KNOWN_HOSTS — вивід ssh-keyscan -H your-server.example.com.
• DEPLOY_HOST — адреса продакшн-сервера.

Умови на продакшн-сервері ті самі, що у третій частині: користувач deploy без прав root, ключ у authorized_keys з параметром from і точковий дозвіл на перезапуск сервісу через sudoers.

6.2 Повний workflow

name: Build and deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npm run lint
      - run: npm test -- --ci
      - run: npm run build

      - uses: actions/upload-artifact@v3
        with:
          name: dist
          path: dist/

  deploy:
    needs: build
    runs-on: deploy          # мітка host-режиму
    steps:
      - uses: actions/download-artifact@v3
        with:
          name: dist
          path: dist/

      - name: Підготувати SSH
        run: |
          install -m 700 -d ~/.ssh
          install -m 600 /dev/null ~/.ssh/deploy_key
          echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/deploy_key
          echo "${{ secrets.SSH_KNOWN_HOSTS }}" > ~/.ssh/known_hosts

      - name: Викласти файли
        run: |
          rsync -az --delete \
            -e "ssh -i ~/.ssh/deploy_key" \
            dist/ deploy@${{ secrets.DEPLOY_HOST }}:/var/www/app/

      - name: Перезапустити сервіс
        run: |
          ssh -i ~/.ssh/deploy_key deploy@${{ secrets.DEPLOY_HOST }} \
            "sudo systemctl restart app.service"

      - name: Перевірити, що піднявся
        run: |
          for i in $(seq 1 10); do
            code=$(curl -s -o /dev/null -w "%{http_code}" https://app.example.com/health || true)
            [ "$code" = "200" ] && exit 0
            sleep 3
          done
          echo "Сервіс не відповідає після деплою"
          exit 1

      - name: Прибрати ключ
        if: always()
        run: rm -f ~/.ssh/deploy_key

Порівняйте цей файл з конфігом з третьої частини: відмінності зводяться до версій дій і назви мітки. Це і є головна практична цінність Gitea Actions, бо досвід роботи з GitHub переноситься майже цілком.

Версії дій тут навмисно нижчі, ніж у GitHub. Дії upload-artifact і download-artifact версії v4 покладаються на API GitHub, якого у Gitea немає, тому працюють саме v3. Це типовий випадок: перевіряйте не саму дію, а те, чи звертається вона до платформи.

6.3 Наскільки контур закритий

Тепер про місце, де формулювання «жоден байт не виходить за межі сервера» перестає бути точним. Код, історія, секрети і логи справді лишаються у вас. А от рядок uses: actions/checkout@v4 за замовчуванням тягне дію з github.com, і без доступу туди задача не стартує.

Три робочі рішення:

• Дзеркало дій усередині Gitea. Створюєте організацію, наприклад actions, і копіюєте у неї потрібні репозиторії дій. У app.ini вказуєте DEFAULT_ACTIONS_URL = self, після чого uses шукає дії у вашій інсталяції.
• Явна адреса у workflow. Мітка джерела прописується у самому uses, коли частина дій локальна, а частина ні.
• Відмова від uses. Замість actions/checkout звичайний git clone, замість setup-node потрібний образ контейнера. Багатослівніше, зате без зовнішніх залежностей взагалі.

Перший варіант зручніший у щоденній роботі, третій найпростіший для перевірки на відповідність вимогам. Дзеркало дій потребує оновлення, тому за ним теж треба стежити.

7. Висновок

7.1 Gitea Actions і GitHub Actions

Синтаксис той самий, різниця у тому, де зберігається код і хто відповідає за роботу системи. Практичні відмінності, які варто пам'ятати:

• Мітки описують спосіб виконання. Не просто ім'я агента, а зв'язка «ім'я : docker або host : образ».
• Не всі дії працюють. Усе, що звертається до GitHub API, у Gitea відмовляє, тому версії дій підбираються під платформу.
• Образи легші. Інструменти, які у хмарі є за замовчуванням, тут ставляться окремо.
• Дії за замовчуванням тягнуться ззовні. Для справді закритого контуру потрібне дзеркало або відмова від uses.

7.2 Коли обирати Gitea

Gitea доречна тоді, коли код не повинен покидати вашу інфраструктуру: договірні вимоги, ізольований контур, повний контроль над даними. Другий сценарій це вартість: власний VPS дешевший за оплату кількох десятків акаунтів. Третій це незалежність від рішень постачальника.

Проти неї свідчить те саме, що і за: усе адмініструєте ви. Бекапи, оновлення, доступність, HTTPS-сертифікати, дзеркало дій. Якщо цим ніхто у команді не займатиметься системно, хмарна платформа з self-hosted runner з третьої або четвертої частини дасть кращий результат за менші зусилля.

7.3 Що далі у серії

Тепер у нас є три робочі варіанти, зібрані власноруч: GitHub Actions з власним агентом, GitLab CI з власним runner і повністю локальний контур на Gitea. У шостій частині зведемо їх в одну таблицю і розберемо вибір за конкретними умовами: розмір команди, вимоги до зберігання коду, складність pipeline, бюджет і те, скільки часу команда готова витрачати на адміністрування.

Часті питання