Назад к блогу

Интеграция прокси в CI/CD pipeline: настройка для GitHub Actions, GitLab и Jenkins

Полное руководство по интеграции прокси в CI/CD pipeline для разработчиков: настройка GitHub Actions, GitLab CI, Jenkins с примерами кода и решением типичных проблем.

📅17 февраля 2026 г.

При автоматизации развертывания и тестирования часто возникает необходимость использовать прокси-серверы в 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.