Прокси для CI/CD пайплайнов: настройка GitHub Actions, GitLab CI и Jenkins для доступа к закрытым ресурсам

Ваш пайплайн падает с ошибкой 403 Forbidden или Connection refused при попытке обратиться к внешнему API или скачать зависимость? Скорее всего, проблема в том, что IP-адрес вашего CI/CD сервера заблокирован на стороне ресурса. Прокси решает эту проблему: вы маршрутизируете трафик через нужный IP и пайплайн работает без сбоев. В этой статье — пошаговые инструкции для GitHub Actions, GitLab CI и Jenkins.

Зачем прокси в CI/CD: реальные сценарии

CI/CD пайплайны работают на серверах с фиксированными IP-адресами — облачных раннерах GitHub, GitLab или на собственных Jenkins-агентах. Эти IP хорошо известны, и многие внешние сервисы либо блокируют их, либо ограничивают количество запросов. Вот конкретные ситуации, когда без прокси не обойтись:

Доступ к гео-ограниченным ресурсам

Многие корпоративные npm-реестры, Maven-репозитории и внутренние API доступны только из определённых стран или IP-диапазонов. Если ваш GitHub Actions раннер находится в регионе, который заблокирован на уровне firewall целевого сервиса, пайплайн не сможет скачать зависимости или отправить данные. Прокси с нужной геолокацией решает эту задачу без изменения инфраструктуры.

Rate limiting и блокировки по IP

Облачные раннеры GitHub Actions используют IP из диапазонов Microsoft Azure. Многие публичные API знают эти диапазоны и применяют к ним жёсткие лимиты — или блокируют полностью. Например, парсинг публичных данных, запросы к сторонним API во время тестов, скачивание дистрибутивов с ограниченных CDN — всё это регулярно ломается именно из-за IP облачных раннеров. Ротация через прокси позволяет обойти rate limiting.

Интеграционное тестирование с реальными сайтами

Если ваши интеграционные тесты обращаются к реальным веб-сайтам или маркетплейсам (Wildberries, Ozon, Авито, Amazon), эти сайты видят один и тот же IP из раннера при каждом запуске и быстро блокируют его. Прокси с ротацией IP позволяет тестам проходить стабильно без капч и блокировок.

Доступ к внутренним корпоративным ресурсам

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

Тестирование рекламных и маркетинговых интеграций

Команды, работающие с Facebook Ads API, TikTok Ads API или Google Ads API, нередко автоматизируют создание кампаний через CI/CD. Эти платформы имеют строгие правила по IP: запросы с IP дата-центров могут блокироваться или требовать дополнительной верификации. Резидентные прокси в пайплайне делают запросы похожими на обычный пользовательский трафик.

Какой тип прокси выбрать для пайплайна

Выбор типа прокси зависит от задачи. Для CI/CD пайплайнов актуальны три варианта — у каждого свои плюсы и ограничения:

Настройка прокси в GitHub Actions

GitHub Actions — самый популярный CI/CD инструмент на сегодня. Настройка прокси здесь делается через переменные окружения и секреты репозитория. Разберём пошагово.

Шаг 1: Добавьте данные прокси в секреты репозитория

Никогда не вписывайте логин и пароль прокси прямо в YAML-файл workflow. Используйте GitHub Secrets:

1. Откройте репозиторий → Settings → Secrets and variables → Actions
2. Нажмите New repository secret
3. Создайте секрет PROXY_URL со значением вида http://user:[email protected]:port

Шаг 2: Используйте переменные окружения в workflow

Большинство инструментов (curl, wget, npm, pip, Maven) автоматически подхватывают стандартные переменные окружения HTTP_PROXY, HTTPS_PROXY и NO_PROXY. Пример workflow:

name: Build with Proxy

on: [push]

env:
  HTTP_PROXY: ${{ secrets.PROXY_URL }}
  HTTPS_PROXY: ${{ secrets.PROXY_URL }}
  NO_PROXY: localhost,127.0.0.1,internal.company.com

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

      - name: Install dependencies
        run: npm ci

      - name: Run integration tests
        run: npm test

      - name: Call external API
        run: |
          curl -v https://api.example.com/data

Шаг 3: SOCKS5 прокси в GitHub Actions

Если вы используете SOCKS5 (рекомендуется для большинства задач), стандартных переменных окружения недостаточно — нужен локальный туннель. Используйте утилиту proxychains или настройте microsocks:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Setup SOCKS5 proxy tunnel
        run: |
          sudo apt-get install -y proxychains4
          echo "socks5 proxy.host 1080 user password" >> /etc/proxychains4.conf

      - name: Run command through SOCKS5
        run: proxychains4 curl https://restricted-resource.com/api

Настройка прокси для конкретных инструментов

Некоторые инструменты игнорируют системные переменные и требуют отдельной настройки:

Настройка прокси в GitLab CI

GitLab CI предоставляет несколько уровней для задания переменных окружения: на уровне проекта, группы или инстанса. Это делает управление прокси более гибким по сравнению с GitHub Actions.

Шаг 1: Добавьте переменные в GitLab CI/CD Variables

1. Откройте проект → Settings → CI/CD → раздел Variables
2. Нажмите Add variable
3. Добавьте переменную PROXY_URL с типом Masked (скрывает значение в логах)
4. Значение: http://user:[email protected]:port

Шаг 2: Используйте переменные в .gitlab-ci.yml

variables:
  HTTP_PROXY: $PROXY_URL
  HTTPS_PROXY: $PROXY_URL
  NO_PROXY: "localhost,127.0.0.1,.internal.company.com"

stages:
  - build
  - test
  - deploy

build:
  stage: build
  image: node:20-alpine
  script:
    - npm ci
    - npm run build

integration_tests:
  stage: test
  image: python:3.11
  script:
    - pip install -r requirements.txt
    - pytest tests/integration/

deploy:
  stage: deploy
  script:
    - curl -X POST https://api.external-service.com/deploy
      -H "Authorization: Bearer $DEPLOY_TOKEN"
      -d '{"version": "$CI_COMMIT_SHA"}'

Прокси только для отдельных джобов

Если прокси нужен не везде (например, только для интеграционных тестов, но не для сборки), задавайте переменные на уровне конкретного джоба, а не глобально:

integration_tests:
  stage: test
  variables:
    HTTP_PROXY: $PROXY_URL
    HTTPS_PROXY: $PROXY_URL
  script:
    - pytest tests/integration/

build:
  stage: build
  # Здесь прокси не задан — прямое подключение
  script:
    - npm ci && npm run build

Self-hosted GitLab Runner: настройка прокси на уровне раннера

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

[[runners]]
  name = "my-runner"
  url = "https://gitlab.com/"
  token = "TOKEN"
  executor = "docker"
  environment = [
    "HTTP_PROXY=http://user:[email protected]:port",
    "HTTPS_PROXY=http://user:[email protected]:port",
    "NO_PROXY=localhost,127.0.0.1"
  ]

Это удобно, когда все пайплайны на данном раннере должны использовать прокси — не нужно прописывать его в каждом .gitlab-ci.yml.

Настройка прокси в Jenkins

Jenkins — самый гибкий из трёх инструментов, но и самый сложный в настройке. Прокси здесь можно задать на нескольких уровнях: глобально для всего Jenkins, для конкретного Pipeline или для отдельного шага.

Способ 1: Глобальные настройки прокси в Jenkins

1. Откройте Manage Jenkins → System
2. Найдите раздел HTTP Proxy Configuration
3. Заполните поля: Server, Port, Username, Password
4. В поле No Proxy Host укажите внутренние адреса через запятую
5. Нажмите Test URL для проверки и сохраните

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

Способ 2: Прокси в Declarative Pipeline через environment

pipeline {
    agent any

    environment {
        HTTP_PROXY  = credentials('proxy-url-credential')
        HTTPS_PROXY = credentials('proxy-url-credential')
        NO_PROXY    = 'localhost,127.0.0.1,internal.company.com'
    }

    stages {
        stage('Build') {
            steps {
                sh 'npm ci'
                sh 'npm run build'
            }
        }

        stage('Integration Tests') {
            steps {
                sh 'pytest tests/integration/'
            }
        }

        stage('Deploy') {
            steps {
                sh '''
                    curl -X POST https://api.external-service.com/deploy \
                    -H "Authorization: Bearer ${DEPLOY_TOKEN}" \
                    -d "version=${GIT_COMMIT}"
                '''
            }
        }
    }
}

Шаг 3: Добавьте учётные данные прокси в Jenkins Credentials

1. Откройте Manage Jenkins → Credentials → System → Global credentials
2. Нажмите Add Credentials
3. Тип: Secret text
4. ID: proxy-url-credential
5. Secret: http://user:[email protected]:port

Способ 3: Прокси через JVM-параметры для Java-проектов

Если ваш пайплайн строит Java-проект (Maven, Gradle), системные переменные окружения могут не работать — JVM использует собственные системные свойства. Добавьте их в JAVA_OPTS:

environment {
    JAVA_OPTS = '-Dhttps.proxyHost=proxy.host -Dhttps.proxyPort=8080 -Dhttps.proxyUser=user -Dhttps.proxyPassword=password -Dhttp.nonProxyHosts=localhost|127.0.0.1|*.internal.com'
}

Прокси внутри Docker-контейнеров в пайплайне

Большинство современных CI/CD пайплайнов запускают шаги внутри Docker-контейнеров. Передача прокси в контейнер — отдельная задача, которая решается несколькими способами.

Передача прокси через --build-arg при сборке образа

Если прокси нужен только во время сборки Docker-образа (например, для установки пакетов внутри Dockerfile), используйте build arguments:

# В .github/workflows/build.yml или .gitlab-ci.yml
docker build \
  --build-arg HTTP_PROXY=$HTTP_PROXY \
  --build-arg HTTPS_PROXY=$HTTPS_PROXY \
  --build-arg NO_PROXY=$NO_PROXY \
  -t myapp:latest .

# В Dockerfile
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

RUN apt-get update && apt-get install -y curl
RUN npm ci

Глобальная настройка Docker daemon для прокси

На self-hosted раннерах можно настроить прокси для всего Docker daemon — тогда все контейнеры автоматически получат прокси без изменений в Dockerfile:

# /etc/systemd/system/docker.service.d/http-proxy.conf
[Service]
Environment="HTTP_PROXY=http://user:[email protected]:port"
Environment="HTTPS_PROXY=http://user:[email protected]:port"
Environment="NO_PROXY=localhost,127.0.0.1,registry.internal.com"

# Применить изменения:
# systemctl daemon-reload
# systemctl restart docker

Безопасность: как хранить учётные данные прокси

Учётные данные прокси — это такие же секреты, как API-ключи или пароли от баз данных. Их утечка означает, что кто угодно сможет использовать ваш прокси за ваш счёт. Вот правила безопасного хранения:

Чек-лист безопасности

• ✅ Никогда не вписывайте логин/пароль прокси прямо в YAML-файлы пайплайна
• ✅ Используйте Masked variables в GitLab и Encrypted secrets в GitHub — они скрываются в логах
• ✅ В Jenkins используйте тип Secret text или Username with password в Credentials Store
• ✅ Добавьте NO_PROXY для внутренних адресов — трафик к своей инфраструктуре не должен идти через прокси
• ✅ Регулярно ротируйте пароли прокси — обновляйте только в хранилище секретов, не меняя код пайплайна
• ✅ Используйте IP-аутентификацию прокси (whitelist IP раннера) там, где это поддерживается — это надёжнее пароля
• ✅ Проверяйте логи прокси на предмет необычной активности

Формат URL прокси: что куда вставлять

Частые ошибки и как их исправить

Даже после правильной настройки могут возникнуть проблемы. Вот самые распространённые ошибки и их решения:

Ошибка: Proxy Authentication Required (407)

Ошибка: SSL Certificate Verification Failed

Ошибка: Connection Timeout через прокси

Ошибка: Инструмент игнорирует переменные HTTP_PROXY

Ошибка: Внутренние сервисы тоже идут через прокси

Заключение

Настройка прокси в CI/CD пайплайне — это не разовая задача, а часть правильной архитектуры автоматизации. Мы разобрали три основных инструмента: GitHub Actions (через Secrets и переменные окружения), GitLab CI (через Variables с маскированием) и Jenkins (через Credentials Store и Declarative Pipeline). Ключевые принципы одинаковы для всех: никогда не хранить учётные данные в коде, использовать NO_PROXY для внутренних адресов и выбирать тип прокси под конкретную задачу.

Выбор правильного типа прокси критически важен для стабильности пайплайна. Для скачивания зависимостей и обращений к стандартным API достаточно быстрых прокси дата-центров. Если же ваш пайплайн проводит интеграционное тестирование на реальных сайтах, работает с рекламными платформами (Facebook Ads API, TikTok Ads API) или обращается к маркетплейсам — используйте резидентные прокси: их IP воспринимаются как обычный пользовательский трафик и крайне редко попадают под блокировки или rate limiting.

Главное правило: тестируйте прокси отдельным шагом в начале пайплайна — это позволит быстро диагностировать проблемы и не тратить время на поиск ошибки в конце долгой сборки. Добавьте шаг curl -v https://api.ipify.org сразу после настройки прокси — он покажет IP, с которого уходят запросы, и подтвердит, что проксирование работает корректно.