Прокси для GitLab: настройка для команд и CI/CD

GitLab — популярная платформа для хранения кода и управления DevOps-процессами, которую используют тысячи команд по всему миру. Но что делать, если доступ к GitLab заблокирован на уровне провайдера, корпоративной сети или целой страны? А ещё хуже — когда CI/CD пайплайн падает посреди ночи просто потому, что runner не может достучаться до репозитория.

В этой статье разберём, как настроить прокси для GitLab на уровне Git-клиента, GitLab Runner и корпоративного сервера — так, чтобы вся команда работала стабильно из любой точки мира.

Зачем нужен прокси для GitLab: реальные сценарии

Прежде чем настраивать прокси, важно понять, какую именно проблему вы решаете. Ситуации бывают разные, и от этого зависит выбор типа прокси и способ его подключения.

Сценарий 1: GitLab заблокирован провайдером или на уровне страны

В ряде стран и корпоративных сетях доступ к gitlab.com ограничен. Разработчик открывает терминал, пишет git pull — и получает timeout. Прокси в этом случае работает как посредник: трафик идёт не напрямую на gitlab.com, а через промежуточный сервер в стране, где ограничений нет.

Сценарий 2: Распределённая команда в разных странах

Представьте: часть команды работает из России, часть — из Казахстана, часть — из Европы. У каждого разные сетевые условия, разные ограничения. Чтобы все работали стабильно и с одинаковой скоростью, компании разворачивают корпоративный прокси-сервер, через который весь трафик к GitLab идёт по единому каналу.

Сценарий 3: CI/CD runner не может достучаться до внешних зависимостей

GitLab Runner запускает пайплайн, и на этапе npm install или pip install всё падает — потому что сервер, на котором крутится runner, находится в закрытой сети без прямого доступа в интернет. Прокси позволяет runner'у получать внешние зависимости, не открывая полный доступ в интернет для всего сервера.

Сценарий 4: Self-hosted GitLab за корпоративным файрволом

Компания держит собственный GitLab-сервер во внутренней сети. Разработчики на удалёнке должны к нему подключаться. Вместо VPN для всего трафика можно настроить прокси только для GitLab-трафика — это быстрее и проще в администрировании.

Сценарий 5: Мониторинг и аудит трафика

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

Важно понять до настройки:

Прокси для GitLab может потребоваться на трёх уровнях одновременно: на машине разработчика (Git-клиент), на сервере с GitLab Runner (CI/CD), и на самом GitLab-сервере (если self-hosted). Каждый уровень настраивается отдельно.

Какой тип прокси подходит для GitLab

GitLab работает по протоколам HTTPS и SSH. Это сразу определяет, какие типы прокси применимы, а какие — нет. Разберём варианты.

Тип прокси	Протокол	Подходит для GitLab	Когда использовать
HTTP/HTTPS прокси	HTTP, HTTPS	✓ Да	Git over HTTPS, веб-интерфейс GitLab
SOCKS5 прокси	TCP (любой)	✓ Да (лучший вариант)	Git over HTTPS и SSH, CI/CD
SOCKS4 прокси	TCP	~ Частично	Только если нет SOCKS5
Прозрачный прокси	HTTP	✗ Нет	Не подходит — не обходит блокировки

Для работы с GitLab оптимальный выбор — SOCKS5. Он работает на уровне TCP, поэтому одинаково хорошо проксирует как HTTPS-соединения (веб-интерфейс, git clone по HTTPS), так и SSH-соединения (git push/pull по SSH на порту 22 или 443).

Резидентные vs дата-центровые прокси для GitLab

Здесь всё зависит от задачи. Если цель — обойти блокировку по GeoIP или получить стабильный IP для авторизации, подойдут прокси дата-центров — они быстрее, дешевле и обеспечивают низкую задержку, что критично при работе с большими репозиториями.

Если же ваш корпоративный IP попал в блок-лист GitLab (бывает при агрессивном сканировании или после инцидентов безопасности), тогда стоит рассмотреть резидентные прокси — их IP-адреса принадлежат реальным домашним пользователям и крайне редко блокируются платформами.

Настройка прокси для Git-клиента (глобально)

Это самый частый сценарий: разработчик на своей машине не может подключиться к GitLab. Настройка делается через конфигурацию самого Git — один раз, и работает для всех репозиториев.

Вариант A: HTTPS-прокси для Git

Если вы работаете с GitLab по HTTPS (адрес репозитория начинается с https://), выполните в терминале:

# Установить HTTP прокси глобально
git config --global http.proxy http://ВАШ_ПРОКСИ_IP:ПОРТ

# Если прокси требует авторизацию
git config --global http.proxy http://ЛОГИН:ПАРОЛЬ@ВАШ_ПРОКСИ_IP:ПОРТ

# Для SOCKS5 прокси (рекомендуется)
git config --global http.proxy socks5://ВАШ_ПРОКСИ_IP:ПОРТ

# Проверить, что настройка применилась
git config --global --get http.proxy

Вариант B: Прокси только для gitlab.com (не затрагивает другие репозитории)

Если вы не хотите, чтобы прокси применялся ко всем Git-операциям (например, GitHub или Bitbucket работают нормально), можно настроить прокси только для конкретного домена:

# Прокси только для gitlab.com
git config --global http.https://gitlab.com.proxy socks5://ВАШ_ПРОКСИ_IP:ПОРТ

# Или для вашего self-hosted GitLab
git config --global http.https://git.yourcompany.com.proxy socks5://ВАШ_ПРОКСИ_IP:ПОРТ

Вариант C: SSH через прокси (для тех, кто работает по SSH)

Если вы клонируете репозитории по SSH ([email protected]:...), настройка прокси делается в SSH-конфиге, а не в Git. Откройте файл ~/.ssh/config и добавьте:

# Для Linux/macOS — через nc (netcat)
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand nc -X 5 -x ВАШ_ПРОКСИ_IP:ПОРТ %h %p

# Для Windows — через connect.exe (Git for Windows)
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand connect -S ВАШ_ПРОКСИ_IP:ПОРТ %h %p

После настройки проверьте соединение командой ssh -T [email protected]. Если всё настроено правильно, вы увидите приветственное сообщение от GitLab.

Как отключить прокси, когда он больше не нужен

# Удалить глобальный прокси
git config --global --unset http.proxy

# Удалить прокси для конкретного домена
git config --global --unset http.https://gitlab.com.proxy

Прокси для GitLab Runner и CI/CD пайплайнов

GitLab Runner — это агент, который выполняет задания из .gitlab-ci.yml. Если runner находится в закрытой сети или на сервере с ограниченным интернет-доступом, нужно настроить прокси отдельно. Настройки Git-клиента разработчика здесь не помогут — runner работает на другой машине.

Способ 1: Переменные окружения в конфигурации runner

Откройте файл конфигурации GitLab Runner (обычно /etc/gitlab-runner/config.toml) и добавьте переменные окружения в секцию [runners.env]:

[[runners]]
  name = "my-runner"
  url = "https://gitlab.com/"
  token = "ВАШ_ТОКЕН"
  executor = "shell"
  environment = [
    "HTTP_PROXY=http://ВАШ_ПРОКСИ_IP:ПОРТ",
    "HTTPS_PROXY=http://ВАШ_ПРОКСИ_IP:ПОРТ",
    "NO_PROXY=localhost,127.0.0.1,ваш-внутренний-домен.com"
  ]

После изменения конфига перезапустите runner: sudo gitlab-runner restart

Способ 2: Переменные в .gitlab-ci.yml (на уровне пайплайна)

Если вы не администратор runner'а или хотите настроить прокси только для конкретного проекта, добавьте переменные прямо в файл пайплайна:

variables:
  HTTP_PROXY: "http://ВАШ_ПРОКСИ_IP:ПОРТ"
  HTTPS_PROXY: "http://ВАШ_ПРОКСИ_IP:ПОРТ"
  NO_PROXY: "localhost,127.0.0.1,.internal.company.com"

stages:
  - build
  - test
  - deploy

build:
  stage: build
  script:
    - npm install   # теперь пойдёт через прокси
    - npm run build

Способ 3: Переменные в настройках проекта GitLab (без коммита в репозиторий)

Лучший способ для чувствительных данных (прокси с авторизацией): перейдите в Settings → CI/CD → Variables вашего проекта и добавьте переменные HTTP_PROXY, HTTPS_PROXY, NO_PROXY как защищённые (masked) переменные. Они автоматически будут доступны во всех пайплайнах, но не будут видны в логах.

Про NO_PROXY — не забывайте!

Переменная NO_PROXY критически важна. В неё нужно добавить все внутренние домены и IP, к которым runner должен подключаться напрямую, минуя прокси. Иначе runner будет пытаться идти через прокси даже к внутренним сервисам — и пайплайн упадёт.

Прокси для Docker executor

Если runner использует Docker executor, контейнеры по умолчанию не наследуют прокси-настройки хоста. Нужно либо добавить переменные в config.toml в секцию [runners.docker], либо создать файл /etc/systemd/system/docker.service.d/proxy.conf на хосте с runner'ом:

[Service]
Environment="HTTP_PROXY=http://ВАШ_ПРОКСИ_IP:ПОРТ"
Environment="HTTPS_PROXY=http://ВАШ_ПРОКСИ_IP:ПОРТ"
Environment="NO_PROXY=localhost,127.0.0.1"

После этого: sudo systemctl daemon-reload && sudo systemctl restart docker

Прокси для self-hosted GitLab сервера

Если вы администрируете собственный GitLab-сервер (установленный через Omnibus или Helm), прокси нужен для того, чтобы сам GitLab мог обращаться к внешним сервисам: отправлять уведомления, подключаться к внешним CI-системам, загружать аватары пользователей, интегрироваться с Jira или Slack.

Настройка в gitlab.rb (Omnibus-установка)

Откройте файл /etc/gitlab/gitlab.rb и добавьте или раскомментируйте следующие строки:

# Прокси для GitLab (Omnibus)
gitlab_rails['env'] = {
  "http_proxy" => "http://ВАШ_ПРОКСИ_IP:ПОРТ",
  "https_proxy" => "http://ВАШ_ПРОКСИ_IP:ПОРТ",
  "no_proxy" => "localhost,127.0.0.1,ВАШ_ВНУТРЕННИЙ_ДОМЕН"
}

# Если прокси с авторизацией:
gitlab_rails['env'] = {
  "http_proxy" => "http://ЛОГИН:ПАРОЛЬ@ВАШ_ПРОКСИ_IP:ПОРТ",
  "https_proxy" => "http://ЛОГИН:ПАРОЛЬ@ВАШ_ПРОКСИ_IP:ПОРТ",
  "no_proxy" => "localhost,127.0.0.1"
}

После изменения конфига примените настройки: sudo gitlab-ctl reconfigure

Настройка исходящих соединений через Admin Area

В GitLab 15.0+ появилась возможность настроить прокси прямо через веб-интерфейс: перейдите в Admin Area → Settings → Network → Outbound requests. Здесь можно указать прокси для исходящих вебхуков и ограничить диапазоны IP, к которым GitLab может обращаться. Это полезно для безопасности — предотвращает SSRF-атаки через вебхуки.

Организация доступа для всей команды через прокси

Когда нужно обеспечить стабильный доступ к GitLab для команды из 5–50 человек, индивидуальная настройка на каждой машине — не лучший подход. Рассмотрим более масштабируемые решения.

Подход 1: Корпоративный прокси-сервер

Разворачивается один прокси-сервер (например, Squid или 3proxy) с доступом в интернет. Все разработчики настраивают Git на использование этого сервера. Преимущества: централизованное управление, единая точка контроля, можно логировать трафик. Недостаток: сервер становится единой точкой отказа.

Подход 2: Зеркало (mirror) репозитория

GitLab поддерживает зеркалирование репозиториев. Можно настроить self-hosted GitLab во внутренней сети как зеркало gitlab.com. Разработчики работают с внутренним сервером, а он синхронизируется с внешним через прокси. Это снижает зависимость от качества прокси-соединения для каждого разработчика.

Подход 3: Автоматическая настройка через dotfiles или onboarding-скрипт

Для команд, где каждый разработчик настраивает окружение сам, удобно создать onboarding-скрипт, который автоматически прописывает нужные настройки Git. Скрипт хранится в корпоративном репозитории и запускается при настройке нового рабочего места.

#!/bin/bash
# setup-git-proxy.sh — запускать при настройке нового рабочего места

PROXY_HOST="proxy.company.com"
PROXY_PORT="3128"

echo "Настройка Git прокси для доступа к GitLab..."
git config --global http.https://gitlab.com.proxy "socks5://${PROXY_HOST}:${PROXY_PORT}"
git config --global http.sslVerify true
echo "Готово! Проверьте: git config --global --list | grep proxy"

Чек-лист для командного развёртывания

Определить, нужен ли прокси на уровне разработчиков, runner'ов или GitLab-сервера (или всех трёх)
Выбрать тип прокси: SOCKS5 для максимальной совместимости
Настроить NO_PROXY для всех внутренних доменов и сервисов
Проверить работу SSH-ключей через прокси (отдельный шаг!)
Задокументировать настройки в корпоративной wiki
Создать onboarding-скрипт для новых сотрудников
Настроить мониторинг доступности прокси-сервера

Частые проблемы и их решение

Даже после правильной настройки иногда что-то идёт не так. Вот самые распространённые проблемы и способы их диагностики.

Проблема 1: SSL certificate problem: unable to get local issuer certificate

Эта ошибка возникает, когда прокси-сервер (особенно корпоративный) выполняет SSL-инспекцию — подменяет сертификат GitLab своим. Git не доверяет этому сертификату. Решение: добавить корпоративный корневой сертификат в доверенные.

# Временное решение (для отладки, не для продакшна!)
git config --global http.sslVerify false

# Правильное решение: добавить корпоративный сертификат
git config --global http.sslCAInfo /путь/до/corporate-ca-bundle.crt

Проблема 2: Прокси работает для HTTPS, но SSH не работает

Это классическая ситуация: настроили http.proxy в Git, HTTPS-клонирование заработало, но SSH-операции по-прежнему не проходят. Причина: SSH-трафик не идёт через HTTP-прокси. Нужно отдельно настроить ~/.ssh/config как описано в разделе про Git-клиент.

Альтернатива: переключиться на работу с GitLab по HTTPS вместо SSH. Для этого измените remote URL:

# Проверить текущий remote
git remote -v

# Изменить с SSH на HTTPS
git remote set-url origin https://gitlab.com/username/repo.git

Проблема 3: CI/CD пайплайн зависает на этапе клонирования репозитория

Runner клонирует репозиторий напрямую с GitLab, используя токен. Если runner находится за прокси, это клонирование тоже должно идти через прокси. Убедитесь, что переменные HTTP_PROXY и HTTPS_PROXY установлены в config.toml, а не только в .gitlab-ci.yml — переменные из CI-файла применяются после клонирования, а не до.

Проблема 4: Прокси работает, но очень медленно

Если push/pull работают, но занимают в 5–10 раз больше времени, чем обычно, проблема может быть в пропускной способности прокси-сервера или в его географическом расположении. Для работы с большими репозиториями (100+ МБ) важно выбирать прокси с низкой задержкой и высокой пропускной способностью. Прокси дата-центров в этом случае предпочтительнее резидентных — они обеспечивают более стабильный канал.

Проблема 5: Аутентификация через прокси требует повторного ввода пароля

Если прокси требует Basic-аутентификацию, и Git каждый раз запрашивает пароль, настройте credential helper:

# macOS — использовать Keychain
git config --global credential.helper osxkeychain

# Windows — использовать Windows Credential Manager
git config --global credential.helper manager

# Linux — кэшировать на 1 час
git config --global credential.helper "cache --timeout=3600"

Как быстро диагностировать проблему с прокси:

Используйте GIT_TRACE=1 GIT_CURL_VERBOSE=1 git clone https://gitlab.com/... — это выведет подробный лог всех HTTP-запросов и ответов, включая информацию о прокси.

Заключение и рекомендации

Настройка прокси для GitLab — задача, которая решается на нескольких уровнях одновременно. Разработчику на рабочей машине достаточно прописать пару строк в конфиге Git или SSH. Для CI/CD нужно добавить переменные окружения в конфиг runner'а или настройки проекта. А для self-hosted GitLab — обновить gitlab.rb и пересобрать конфигурацию.

Главные правила, которые помогут избежать большинства проблем:

Используйте SOCKS5 — он работает и с HTTPS, и с SSH
Всегда настраивайте NO_PROXY для внутренних сервисов
Не отключайте SSL-верификацию в продакшне — добавьте корпоративный сертификат
Для CI/CD устанавливайте прокси в config.toml, а не только в .gitlab-ci.yml
Документируйте настройки — новый разработчик в команде скажет спасибо

Если вы ищете надёжный прокси для организации стабильного доступа к GitLab из любой точки мира, рекомендуем рассмотреть прокси дата-центров — они обеспечивают высокую скорость передачи данных и низкую задержку, что особенно важно при работе с большими репозиториями и интенсивными CI/CD пайплайнами. Для команд, которым важна максимальная анонимность или обход GeoIP-блокировок, подойдут резидентные прокси с IP реальных домашних пользователей.