Развёртывание GitLab Runner в Termux для локального CI/CD с поддержкой Docker-executors

Termux позволяет использовать Android-смартфон или планшет как лёгкий «узел сборки» для локальных задач: тестов, линтинга, сборки артефактов и проверки пайплайнов. Это особенно удобно, когда вы разворачиваете GitLab внутри локальной сети и хотите, чтобы часть этапов CI выполнялась на вашем устройстве без облачных затрат.

В этой статье разберём, как развернуть GitLab Runner в Termux с поддержкой Docker-executors. Подход подходит для локального CI/CD при наличии возможностей Docker на стороне Android.

Важные оговорки по платформе Android и Docker

Docker-executor требует, чтобы контейнеры могли запускаться на устройстве. На Android это зависит от:

наличия среды, поддерживающей контейнеры (например, через совместимую подсистему/движок);
доступа к Docker API и корректных привилегий;
ограничений безопасности ОС и сборки (некоторые устройства требуют дополнительных настроек).

Поэтому перед настройкой Runner убедитесь, что на вашем устройстве контейнеры реально запускаются в Termux (или в доступной окружению подсистеме) и вы можете обращаться к Docker сокету.

Архитектура решения

Общий план такой:

Устанавливаем Termux и базовые пакеты.
Скачиваем и устанавливаем GitLab Runner.
Регистрируем runner в вашем GitLab (в локальной сети).
Настраиваем конфигурацию config.toml для docker executor.
Проверяем пайплайном реальную сборку контейнера.
Добавляем автозапуск/устойчивость к перезапускам.

1) Подготовка Termux

Откройте Termux и обновите пакеты:

pkg update && pkg upgrade -y

Установите необходимые зависимости:

pkg install -y git curl ca-certificates unzip tar

Если вы планируете использовать образы контейнеров, понадобятся базовые утилиты для работы с контейнерами/сокетами (в зависимости от вашей Docker-среды). Как минимум, проверьте, что в вашем окружении доступна команда docker (или вы можете обращаться к Docker API).

2) Установка GitLab Runner в Termux

Скачивание и установка Runner обычно зависят от архитектуры. Далее приведён универсальный подход: загрузить бинарный файл для вашей версии.

Определите архитектуру:

uname -m

Затем выберите соответствующий архив GitLab Runner для Android/Linux. Часто подойдёт вариант для linux/arm64 или linux/arm/v7.

Примерно (укажите версию и URL согласно официальным релизам GitLab Runner):

cd $HOME
export RUNNER_VERSION="17.6.0"
curl -L -o runner.zip "https://gitlab-runner-downloads.s3.amazonaws.com/releases/v${RUNNER_VERSION}/binaries/gitlab-runner-linux-arm64-${RUNNER_VERSION}.zip"
unzip runner.zip
chmod +x gitlab-runner
mv gitlab-runner $HOME/bin/

Добавьте путь в переменную окружения (если нужно):

echo 'export PATH=$HOME/bin:$PATH' >> $HOME/.bashrc

Проверьте версию:

gitlab-runner --version

Если команда не найдена — значит, бинарник не попал в PATH. Проверьте наличие файла и повторите шаг с PATH.

3) Регистрация Runner в GitLab (локально)

Откройте ваш GitLab (локальная инсталляция), перейдите в:

Admin Area → Runners (или Settings → CI/CD → Runners в зависимости от конфигурации);
создайте новый runner;
получите registration token.

Далее в Termux выполните:

gitlab-runner register

В интерактивном режиме укажите:

GitLab URL (например, IP вашего GitLab в локальной сети);
Registration token;
Description (например, termux-docker-runner);
Tags (например, termux,docker);
Executor — выберите docker (или shell, если на первом этапе тестируете, но в статье цель — docker executor);
Default docker image — задайте стартовую (например, alpine:3.19 или ваш образ сборки).

После регистрации обычно создаётся конфигурация config.toml.

4) Где лежит конфигурация и базовая проверка

Проверьте наличие конфигурационного файла:

ls -la $HOME/.gitlab-runner/

Обычно файл будет по пути:

$HOME/.gitlab-runner/config.toml

Откройте и убедитесь, что runner зарегистрирован и executor указан как docker.

5) Настройка Docker-executor: config.toml

Откройте файл конфигурации:

nano $HOME/.gitlab-runner/config.toml

Ниже пример ключевых фрагментов. Реальные значения (token, url) будут вашими.

concurrent = 1
check_interval = 0

[[runners]]
  name = "termux-docker-runner"
  url = "http://IP_вашего_GitLab"
  token = "ВАШ_REGISTRATION_TOKEN"
  executor = "docker"
  limit = 1
  output_limit = 100000

  [runners.custom_build_dir]
  [runners.docker]
    tls_verify = false
    image = "alpine:3.19"
    privileged = false
    disable_cache = false
    shm_size = 0

    # Важно: Docker executor использует Docker daemon,
    # поэтому нужно указать, как Runner будет к нему обращаться.
    # В зависимости от вашей Docker-среды может потребоваться один из вариантов.
    #
    # Пример для локального сокета Docker:
    volumes = ["/cache"]
    # Если в вашей среде есть переменная DOCKER_HOST — иногда лучше настроить окружение,
    # но в config.toml для docker executor обычно настраивается доступ к daemon через стандартные пути/окружение.
  [runners.cache]

Ключевые моменты:

image: стартовая базовая картинка для job’ов.
volumes: добавьте кэш (например, /cache) — это ускорит повторные сборки.
privileged: по умолчанию лучше держать false, включайте лишь при необходимости (например, для специфичных операций внутри контейнера).

Если Runner не может подключиться к Docker daemon, ошибки часто связаны с доступом к сокету или отсутствием Docker API в окружении. Тогда либо настройте Docker так, чтобы доступ был доступен из Termux, либо выберите другой executor.

6) Подготовка кэш-пути

Если вы используете volume /cache, убедитесь, что путь существует и доступен. Пример:

mkdir -p $HOME/.cache/gitlab-runner-cache
# В зависимости от того, как именно монтируется /cache, может понадобиться другая схема.
# Если Runner использует том /cache внутри контейнеров, создавайте соответствующие директории на хосте Docker (в вашей среде).

Практика: сначала проверьте минимальный job без кэша, затем добавляйте кэш и volume монтирования.

7) Пример .gitlab-ci.yml для проверки

Создайте простой pipeline, который запускает контейнер и выполняет команды. Пример для проверки, что runner «виден», job исполняется и Docker доступен:

stages:
  - test

docker-smoke:
  stage: test
  tags:
    - termux
    - docker
  image: alpine:3.19
  script:
    - echo "Runner is working on Termux + Docker executor"
    - uname -a
    - cat /etc/os-release
  artifacts:
    when: always
    paths:
      - /etc/os-release

Если вы задали другие теги при регистрации, обновите секцию tags.

8) Запуск GitLab Runner в Termux

Запустите runner:

gitlab-runner run

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

9) Автозапуск и устойчивость

Android не гарантирует стабильность фоновых процессов после блокировки экрана или при ограничениях батареи. Поэтому для «железной» устойчивости используйте:

настройки энергосбережения (исключение Termux или процесса Runner);
«безграничный» режим или правила фоновой работы (в зависимости от прошивки);
проверку поведения после перезагрузки.

Практический вариант: сделать стартовый скрипт и запускать его вручную/через планировщик, если он у вас доступен.

mkdir -p $HOME/bin
cat > $HOME/bin/start-gitlab-runner-termux.sh <<'EOF'
#!/data/data/com.termux/files/usr/bin/bash
set -e
cd $HOME
exec gitlab-runner run
EOF
chmod +x $HOME/bin/start-gitlab-runner-termux.sh

Запуск:

$HOME/bin/start-gitlab-runner-termux.sh

10) Типовые проблемы и их диагностика

10.1 Runner зарегистрирован, но job не стартует

Проверьте теги: в .gitlab-ci.yml и при регистрации.
Проверьте, что runner активен в UI GitLab.
Убедитесь, что runner не «упирается» в лимиты (concurrent, limit).

10.2 Ошибки доступа к Docker daemon

Проверьте доступность Docker API из Termux.
Проверьте, что сокет Docker доступен и корректно смонтирован в вашей среде.
Сначала протестируйте простую команду с docker (если она доступна), затем запускайте runner.

10.3 Контейнер стартует, но сборка падает

Проверьте, что образ содержит нужные пакеты (или используйте Dockerfile в job).
Если нужны дополнительные утилиты — либо ставьте их внутри job, либо делайте кастомный образ.

Локальная сеть и безопасный доступ (без обхода блокировок)

Если GitLab и Termux находятся в одной локальной сети, обычно достаточно правильно настроить адресацию и доступ. В некоторых случаях можно использовать VPN для создания локальной сети между устройствами, чтобы обеспечить прозрачный обмен данными только в рамках локального подключения. Не применяйте VPN для обхода блокировок и не используйте сомнительные схемы доступа.

Заключение

Развёртывание GitLab Runner в Termux для локального CI/CD с поддержкой Docker-executors позволяет организовать «карманный» сборочный узел: быстрые проверки пайплайнов, локальные тесты и сборку артефактов без зависимости от облачных ресурсов. Ключевой фактор успеха — корректный доступ к Docker daemon из окружения Termux и точная настройка config.toml (executor, образ, volumes, теги и лимиты).

Хотите настроить всё под вашу инфраструктуру (локальный GitLab, Docker-среда на Android, теги/кэш/устойчивый запуск)? Обратитесь в РыбинскЛАБ — поможем спроектировать и внедрить решение под ваши задачи.