При автоматизации развертывания и тестирования часто возникает необходимость использовать прокси-серверы в CI/CD процессах. Это может быть связано с корпоративными политиками безопасности, тестированием геолокационных функций или обходом rate-limiting при загрузке зависимостей. В этом руководстве разберем практическую настройку прокси для популярных CI/CD платформ с готовыми примерами конфигураций.
Зачем нужны прокси в CI/CD процессах
Использование прокси-серверов в автоматизированных процессах развертывания решает несколько критических задач. Во-первых, многие корпоративные сети требуют прохождения всего исходящего трафика через корпоративные прокси для контроля безопасности и логирования. Без правильной настройки CI/CD pipeline просто не сможет загрузить зависимости или подключиться к внешним сервисам.
Во-вторых, при тестировании приложений с геолокационной логикой необходимо проверять работу из разных стран. Например, если вы разрабатываете сервис с региональным контентом или ценообразованием, автоматические тесты должны имитировать пользователей из разных локаций. Здесь помогают резидентные прокси с IP-адресами из нужных регионов.
Третья причина — обход rate-limiting и блокировок. При частых запусках pipeline, особенно в крупных командах, CI/CD серверы могут попадать под ограничения API внешних сервисов. Например, GitHub API или реестры пакетов могут временно блокировать IP при превышении лимита запросов. Ротация прокси помогает распределить нагрузку.
Важно: Для CI/CD процессов критична стабильность соединения. Используйте прокси с uptime не менее 99.5% и быстрым откликом (менее 200ms). Нестабильные прокси приведут к случайным падениям сборок и потере времени команды на расследование.
Настройка прокси в GitHub Actions
GitHub Actions — одна из самых популярных платформ для CI/CD. Настройка прокси здесь выполняется через переменные окружения, которые можно задать на уровне workflow или всей организации. Рассмотрим несколько способов интеграции.
Базовая настройка через переменные окружения
Самый простой способ — установить переменные окружения HTTP_PROXY и HTTPS_PROXY в начале job. Большинство инструментов (curl, wget, npm, pip) автоматически используют эти переменные:
name: CI with Proxy
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
env:
HTTP_PROXY: http://proxy.example.com:8080
HTTPS_PROXY: http://proxy.example.com:8080
NO_PROXY: localhost,127.0.0.1,.internal.domain
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- name: Install dependencies
run: npm install
- name: Run tests
run: npm test
Переменная NO_PROXY критически важна — она исключает локальные адреса и внутренние сервисы из проксирования. Без неё могут возникнуть проблемы с подключением к localhost или внутренним Docker-контейнерам.
Безопасное хранение credentials через GitHub Secrets
Если прокси требует аутентификации, никогда не храните логин и пароль в открытом виде в workflow файле. Используйте GitHub Secrets:
name: CI with Authenticated Proxy
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Configure Proxy
run: |
echo "HTTP_PROXY=http://${{ secrets.PROXY_USER }}:${{ secrets.PROXY_PASS }}@${{ secrets.PROXY_HOST }}:${{ secrets.PROXY_PORT }}" >> $GITHUB_ENV
echo "HTTPS_PROXY=http://${{ secrets.PROXY_USER }}:${{ secrets.PROXY_PASS }}@${{ secrets.PROXY_HOST }}:${{ secrets.PROXY_PORT }}" >> $GITHUB_ENV
echo "NO_PROXY=localhost,127.0.0.1" >> $GITHUB_ENV
- name: Test proxy connection
run: curl -I https://api.github.com
- name: Install dependencies
run: npm ci
Создайте secrets в настройках репозитория: Settings → Secrets and variables → Actions → New repository secret. Добавьте PROXY_USER, PROXY_PASS, PROXY_HOST и PROXY_PORT. Эти значения будут зашифрованы и недоступны в логах.
Настройка прокси для конкретных шагов
Иногда нужно использовать прокси только для определенных операций, например, только для загрузки зависимостей, но не для деплоя. Устанавливайте переменные на уровне конкретного step:
steps:
- name: Download dependencies via proxy
env:
HTTP_PROXY: http://proxy.example.com:8080
HTTPS_PROXY: http://proxy.example.com:8080
run: npm install
- name: Deploy without proxy
run: ./deploy.sh
Интеграция прокси с GitLab CI/CD
GitLab CI/CD предоставляет несколько уровней настройки прокси: на уровне runner, на уровне проекта и на уровне конкретного job. Выбор зависит от того, нужен ли прокси для всех проектов или только для конкретных.
Настройка прокси на уровне GitLab Runner
Если используете self-hosted GitLab Runner и все проекты должны работать через прокси, настройте его в конфигурации runner. Отредактируйте файл /etc/gitlab-runner/config.toml:
[[runners]]
name = "docker-runner"
url = "https://gitlab.com/"
token = "YOUR_TOKEN"
executor = "docker"
[runners.docker]
image = "alpine:latest"
privileged = false
[runners.docker.services_environment]
HTTP_PROXY = "http://proxy.example.com:8080"
HTTPS_PROXY = "http://proxy.example.com:8080"
NO_PROXY = "localhost,127.0.0.1,.gitlab.com"
После изменения конфигурации перезапустите runner: sudo gitlab-runner restart. Теперь все jobs на этом runner будут автоматически использовать прокси.
Настройка через .gitlab-ci.yml
Для настройки прокси на уровне конкретного проекта используйте переменные в файле .gitlab-ci.yml. Это более гибкий подход, позволяющий разным проектам использовать разные прокси:
variables:
HTTP_PROXY: "http://proxy.example.com:8080"
HTTPS_PROXY: "http://proxy.example.com:8080"
NO_PROXY: "localhost,127.0.0.1,.internal"
stages:
- build
- test
- deploy
build:
stage: build
script:
- echo "Proxy configured: $HTTP_PROXY"
- npm install
- npm run build
artifacts:
paths:
- dist/
test:
stage: test
script:
- npm test
dependencies:
- build
Использование GitLab CI/CD Variables для credentials
Для хранения чувствительных данных используйте CI/CD Variables в настройках проекта: Settings → CI/CD → Variables. Создайте protected и masked переменные:
- PROXY_URL — полный URL с credentials (masked)
- PROXY_HOST — хост прокси-сервера
- PROXY_PORT — порт
- PROXY_USER и PROXY_PASS — для раздельного хранения
Затем используйте их в .gitlab-ci.yml:
build:
stage: build
before_script:
- export HTTP_PROXY="http://${PROXY_USER}:${PROXY_PASS}@${PROXY_HOST}:${PROXY_PORT}"
- export HTTPS_PROXY="http://${PROXY_USER}:${PROXY_PASS}@${PROXY_HOST}:${PROXY_PORT}"
script:
- npm install
- npm run build
Конфигурация прокси в Jenkins
Jenkins предлагает несколько способов настройки прокси в зависимости от архитектуры: глобальные настройки для Jenkins master, настройки для конкретных агентов или настройки на уровне отдельных pipeline.
Глобальная настройка прокси для Jenkins
Для настройки прокси, который будет использоваться Jenkins для обновлений плагинов и других внутренних операций, перейдите в Manage Jenkins → Manage Plugins → Advanced. В разделе HTTP Proxy Configuration укажите:
- Server: proxy.example.com
- Port: 8080
- User name и Password (если требуется аутентификация)
- No Proxy Host: localhost,127.0.0.1,.internal
Эта настройка влияет только на сам Jenkins, но не на jobs. Для jobs нужна отдельная конфигурация.
Настройка прокси для Jenkins Pipeline
В Jenkinsfile можно задать переменные окружения для всего pipeline или для конкретных stages:
pipeline {
agent any
environment {
HTTP_PROXY = 'http://proxy.example.com:8080'
HTTPS_PROXY = 'http://proxy.example.com:8080'
NO_PROXY = 'localhost,127.0.0.1,.internal'
}
stages {
stage('Build') {
steps {
sh 'npm install'
sh 'npm run build'
}
}
stage('Test') {
steps {
sh 'npm test'
}
}
}
}
Использование Jenkins Credentials для прокси
Для безопасного хранения credentials прокси используйте Jenkins Credentials Store. Создайте credentials типа "Username with password" в Manage Jenkins → Manage Credentials, затем используйте их в pipeline:
pipeline {
agent any
stages {
stage('Build with Authenticated Proxy') {
steps {
withCredentials([usernamePassword(
credentialsId: 'proxy-credentials',
usernameVariable: 'PROXY_USER',
passwordVariable: 'PROXY_PASS'
)]) {
sh '''
export HTTP_PROXY="http://${PROXY_USER}:${PROXY_PASS}@proxy.example.com:8080"
export HTTPS_PROXY="http://${PROXY_USER}:${PROXY_PASS}@proxy.example.com:8080"
npm install
'''
}
}
}
}
}
Настройка прокси для Jenkins агентов
Если используете отдельные Jenkins агенты (nodes), настройте прокси для каждого агента отдельно. В конфигурации агента (Manage Jenkins → Manage Nodes → Configure) добавьте в Environment variables:
HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080
NO_PROXY=localhost,127.0.0.1
Прокси для Docker в CI/CD
Docker — неотъемлемая часть современных CI/CD процессов. Настройка прокси для Docker имеет свои особенности, так как нужно настроить прокси и для Docker daemon, и для контейнеров.
Настройка прокси для Docker daemon
Чтобы Docker daemon мог скачивать образы через прокси, создайте systemd drop-in файл. На Linux системе создайте директорию и файл:
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf
Добавьте следующее содержимое:
[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080"
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,.internal,docker.io"
Перезагрузите конфигурацию и Docker:
sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl show --property=Environment docker
Прокси для контейнеров во время сборки
Если контейнерам нужен доступ через прокси во время сборки (например, для установки пакетов), передайте переменные через build args в Dockerfile:
FROM node:18-alpine
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY
ENV HTTP_PROXY=${HTTP_PROXY}
ENV HTTPS_PROXY=${HTTPS_PROXY}
ENV NO_PROXY=${NO_PROXY}
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
# Удаляем прокси переменные для runtime
ENV HTTP_PROXY=
ENV HTTPS_PROXY=
CMD ["npm", "start"]
В CI/CD pipeline передавайте build args:
# GitHub Actions
- name: Build Docker image with proxy
run: |
docker build \
--build-arg HTTP_PROXY=${{ secrets.PROXY_URL }} \
--build-arg HTTPS_PROXY=${{ secrets.PROXY_URL }} \
--build-arg NO_PROXY=localhost,127.0.0.1 \
-t myapp:latest .
# GitLab CI
docker build:
script:
- docker build
--build-arg HTTP_PROXY="${PROXY_URL}"
--build-arg HTTPS_PROXY="${PROXY_URL}"
-t myapp:latest .
Docker Compose с прокси
При использовании Docker Compose в CI/CD настройте прокси через environment в docker-compose.yml:
version: '3.8'
services:
app:
build:
context: .
args:
- HTTP_PROXY=${HTTP_PROXY}
- HTTPS_PROXY=${HTTPS_PROXY}
environment:
- HTTP_PROXY=${HTTP_PROXY}
- HTTPS_PROXY=${HTTPS_PROXY}
- NO_PROXY=localhost,127.0.0.1
ports:
- "3000:3000"
Настройка прокси для пакетных менеджеров
Пакетные менеджеры часто требуют дополнительной настройки прокси, особенно если используют собственные конфигурационные файлы. Рассмотрим настройку для популярных менеджеров пакетов.
NPM и Yarn
NPM может использовать как переменные окружения HTTP_PROXY/HTTPS_PROXY, так и собственную конфигурацию. Для явной настройки в CI/CD:
# В GitHub Actions или GitLab CI
- name: Configure npm proxy
run: |
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080
npm config set noproxy "localhost,127.0.0.1"
- name: Install dependencies
run: npm install
# Для Yarn
- name: Configure yarn proxy
run: |
yarn config set proxy http://proxy.example.com:8080
yarn config set https-proxy http://proxy.example.com:8080
Альтернативный способ — создать .npmrc файл в корне проекта (но не коммитьте credentials!):
# .npmrc (генерируется в CI)
proxy=http://proxy.example.com:8080
https-proxy=http://proxy.example.com:8080
noproxy=localhost,127.0.0.1
Python pip и Poetry
Pip использует переменные окружения, но можно также настроить через конфигурацию:
# Через переменные окружения (рекомендуется для CI)
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
pip install -r requirements.txt
# Или через параметры pip
pip install --proxy http://proxy.example.com:8080 -r requirements.txt
# Для Poetry
poetry config http-basic.proxy http://proxy.example.com:8080
poetry install
Maven и Gradle
Для Java-проектов настройка прокси требует создания конфигурационных файлов. Для Maven создайте settings.xml в CI pipeline:
- name: Configure Maven proxy
run: |
mkdir -p ~/.m2
cat > ~/.m2/settings.xml << EOF
<settings>
<proxies>
<proxy>
<id>http-proxy</id>
<active>true</active>
<protocol>http</protocol>
<host>proxy.example.com</host>
<port>8080</port>
<nonProxyHosts>localhost|127.0.0.1</nonProxyHosts>
</proxy>
</proxies>
</settings>
EOF
- name: Build with Maven
run: mvn clean install
Для Gradle добавьте настройки в gradle.properties:
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080
systemProp.http.nonProxyHosts=localhost|127.0.0.1
Безопасное хранение credentials прокси
Хранение credentials прокси — критический аспект безопасности CI/CD. Утечка этих данных может привести к несанкционированному использованию прокси и финансовым потерям. Рассмотрим best practices для разных платформ.
GitHub Actions Secrets
GitHub Actions предлагает три уровня секретов: repository, environment и organization. Для прокси credentials используйте:
- Repository secrets — для проектов, где прокси нужен только в одном репозитории
- Organization secrets — если один прокси используется во всех проектах организации
- Environment secrets — для разных прокси в staging/production окружениях
Важные правила безопасности:
- Никогда не выводите секреты в логи: GitHub автоматически маскирует их, но лучше избегать echo
- Используйте разные credentials для разных окружений
- Регулярно ротируйте пароли прокси (раз в 90 дней минимум)
- Ограничивайте доступ к секретам через branch protection rules
GitLab CI/CD Variables
GitLab предлагает дополнительные опции защиты переменных:
- Protected — переменная доступна только в protected branches (main, production)
- Masked — значение автоматически скрывается в логах
- Environment scope — ограничение использования конкретными окружениями
Рекомендуемая конфигурация для прокси credentials:
# Settings → CI/CD → Variables
PROXY_USER: myuser (Protected: Yes, Masked: Yes)
PROXY_PASS: secret123 (Protected: Yes, Masked: Yes)
PROXY_HOST: proxy.example.com (Protected: No, Masked: No)
PROXY_PORT: 8080 (Protected: No, Masked: No)
Jenkins Credentials Store
Jenkins Credentials Store поддерживает несколько типов хранения credentials. Для прокси рекомендуется:
- Использовать "Username with password" для логина/пароля прокси
- Настроить Folder-level credentials для разных команд/проектов
- Включить Credentials Binding Plugin для безопасного использования в Pipeline
- Настроить audit logging для отслеживания использования credentials
Внешние системы управления секретами
Для enterprise-окружений рекомендуется использовать специализированные системы управления секретами: HashiCorp Vault, AWS Secrets Manager, Azure Key Vault или Google Secret Manager. Пример интеграции с HashiCorp Vault в GitHub Actions:
- name: Import Secrets from Vault
uses: hashicorp/vault-action@v2
with:
url: https://vault.example.com
token: ${{ secrets.VAULT_TOKEN }}
secrets: |
secret/data/proxy proxy_user | PROXY_USER ;
secret/data/proxy proxy_pass | PROXY_PASS ;
secret/data/proxy proxy_host | PROXY_HOST
- name: Configure Proxy
run: |
export HTTP_PROXY="http://${PROXY_USER}:${PROXY_PASS}@${PROXY_HOST}:8080"
npm install
Решение типичных проблем
При интеграции прокси в CI/CD часто возникают одни и те же проблемы. Рассмотрим самые распространенные и способы их решения.
Проблема: Connection timeout при загрузке зависимостей
Симптомы: npm install, pip install или docker pull завершаются с ошибкой timeout после 30-60 секунд.
Причины:
- Прокси-сервер недоступен или перегружен
- Неправильный формат URL прокси (забыли http:// в начале)
- Прокси требует аутентификацию, но credentials не переданы
- Firewall блокирует соединение от CI/CD runner к прокси
Решение:
# 1. Проверьте доступность прокси
- name: Test proxy connectivity
run: |
curl -v -x http://proxy.example.com:8080 https://www.google.com
echo "Proxy test completed"
# 2. Увеличьте timeout для npm
- name: Install with increased timeout
run: |
npm config set fetch-timeout 300000
npm install
# 3. Проверьте формат URL
- name: Debug proxy configuration
run: |
echo "HTTP_PROXY: $HTTP_PROXY"
echo "HTTPS_PROXY: $HTTPS_PROXY"
# Должно быть: http://user:pass@host:port
Проблема: SSL certificate verification failed
Симптомы: Ошибки вида "SSL certificate problem: unable to get local issuer certificate" или "CERT_UNTRUSTED".
Причина: Корпоративные прокси часто выполняют SSL inspection, подменяя сертификаты. CI/CD runner не доверяет корпоративному CA.
Решение:
# Вариант 1: Добавить корпоративный CA сертификат
- name: Install corporate CA certificate
run: |
sudo cp corporate-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
# Вариант 2: Отключить проверку SSL (НЕ рекомендуется для production!)
- name: Install with SSL verification disabled
run: |
npm config set strict-ssl false
npm install
env:
NODE_TLS_REJECT_UNAUTHORIZED: 0
# Вариант 3: Использовать прокси только для HTTP, HTTPS напрямую
- name: Selective proxy usage
run: npm install
env:
HTTP_PROXY: http://proxy.example.com:8080
# HTTPS_PROXY не устанавливаем
Предупреждение: Отключение проверки SSL сертификатов создает серьезный риск безопасности. Используйте этот подход только для внутренних корпоративных сетей и обязательно добавьте корпоративный CA в доверенные.
Проблема: Прокси работает для одних команд, но не для других
Симптомы: npm install работает через прокси, но git clone или docker pull игнорируют настройки прокси.
Причина: Разные инструменты используют разные механизмы настройки прокси. Git и Docker имеют собственные конфигурационные файлы.
Решение:
# Настройка Git proxy
- name: Configure Git proxy
run: |
git config --global http.proxy http://proxy.example.com:8080
git config --global https.proxy http://proxy.example.com:8080
# Настройка Docker proxy (см. раздел Docker выше)
# Для wget/curl
- name: Configure wget/curl
run: |
echo "use_proxy = on" >> ~/.wgetrc
echo "http_proxy = http://proxy.example.com:8080" >> ~/.wgetrc
echo "https_proxy = http://proxy.example.com:8080" >> ~/.wgetrc
Проблема: Внутренние сервисы недоступны при включенном прокси
Симптомы: После настройки прокси перестали работать подключения к localhost, внутренним Docker контейнерам или корпоративным сервисам.
Причина: Неправильно настроена переменная NO_PROXY, все запросы идут через прокси, включая локальные.
Решение:
# Правильная настройка NO_PROXY
env:
HTTP_PROXY: http://proxy.example.com:8080
HTTPS_PROXY: http://proxy.example.com:8080
NO_PROXY: |
localhost,
127.0.0.1,
0.0.0.0,
.internal,
.local,
.corp.example.com,
docker.internal,
host.docker.internal
# Для Docker Compose также добавьте
services:
app:
environment:
- NO_PROXY=localhost,127.0.0.1,db,redis
# db и redis — имена других сервисов в compose
Проблема: Прокси credentials попадают в логи
Симптомы: В логах CI/CD видны пароли прокси в открытом виде.
Причина: Вывод переменных окружения через echo или verbose режим команд.
Решение:
# ❌ ПЛОХО - credentials в логах
- name: Debug proxy
run: |
echo "Proxy: $HTTP_PROXY" # Покажет http://user:pass@host:port
curl -v ... # Verbose режим показывает credentials
# ✅ ХОРОШО - безопасный вывод
- name: Debug proxy (safe)
run: |
echo "Proxy host configured: $(echo $HTTP_PROXY | cut -d'@' -f2)"
# Покажет только host:port
# Используйте secrets для маскирования
- name: Configure proxy
env:
PROXY_URL: ${{ secrets.PROXY_URL }} # GitHub автоматически маскирует
run: |
export HTTP_PROXY="$PROXY_URL"
Заключение
Интеграция прокси в CI/CD pipeline — важный аспект автоматизации, который обеспечивает безопасность, соответствие корпоративным политикам и возможность тестирования геолокационных функций. В этом руководстве мы рассмотрели практические способы настройки прокси для GitHub Actions, GitLab CI, Jenkins, Docker и популярных пакетных менеджеров.
Ключевые моменты, которые следует помнить при настройке прокси в CI/CD: всегда используйте безопасное хранение credentials через встроенные механизмы секретов платформ, правильно настраивайте NO_PROXY для исключения локальных и внутренних сервисов, тестируйте подключение к прокси перед основными операциями и мониторьте логи на предмет утечки чувствительных данных. Для критичных production окружений рекомендуется использовать внешние системы управления секретами типа HashiCorp Vault.
Выбор типа прокси зависит от ваших задач: для корпоративных сетей обычно используются существующие HTTP/HTTPS прокси, для тестирования геолокационных функций подходят резидентные прокси с IP из нужных стран, а для высокоскоростной загрузки зависимостей можно использовать прокси дата-центров. Важно обеспечить высокий uptime прокси-серверов, так как их недоступность приведет к падению всех сборок и блокировке работы команды разработки.
При возникновении проблем начинайте с проверки базовой доступности прокси через curl или wget, затем проверяйте правильность формата URL и credentials, и только после этого переходите к специфичным настройкам конкретных инструментов. Большинство проблем решается правильной настройкой переменных окружения HTTP_PROXY, HTTPS_PROXY и NO_PROXY.