Налаштування проксі у GitHub Actions та CI/CD

Налаштування проксі в GitHub Actions та CI/CD передбачає конфігурацію стандартних змінних середовища проксі, таких як HTTP_PROXY, HTTPS_PROXY та NO_PROXY, у визначенні вашого робочого процесу, зазвичай на рівні завдання або кроку. Це дозволяє діям, скриптам та інструментам, що виконуються в конвеєрі CI/CD, направляти свій мережевий трафік через вказаний проксі-сервер.

Організації часто розгортають проксі-сервери для контролю вихідного мережевого доступу, забезпечення політик безпеки, фільтрації контенту та кешування часто використовуваних ресурсів. Для конвеєрів CI/CD, що працюють у таких середовищах, конфігурація налаштувань проксі є важливою, щоб дозволити інструментам збірки, менеджерам залежностей та тестовим скриптам досягати зовнішніх сервісів, репозиторіїв пакетів або API. Ранери GitHub Actions, особливо самостійно розміщені ранери, можуть вимагати конфігурації проксі для доступу до самого GitHub або інших інтернет-ресурсів.

Налаштування змінних середовища проксі

Найпоширеніший і загальновизнаний метод конфігурації проксі в середовищі на базі Linux (яке переважно використовують ранери, розміщені на GitHub) — це змінні середовища.

• HTTP_PROXY: Вказує проксі-сервер для HTTP-запитів.
• HTTPS_PROXY: Вказує проксі-сервер для HTTPS-запитів.
• NO_PROXY: Розділений комами список імен хостів, доменів або IP-адрес, які повинні обходити проксі. Це критично важливо для прямого доступу до внутрішніх ресурсів.

Формат для HTTP_PROXY та HTTPS_PROXY зазвичай http://[user:password@]host:port.
Як великі (HTTP_PROXY), так і малі (http_proxy) версії цих змінних часто підтримуються різними інструментами; використання великих літер є стандартною практикою для змінних середовища.

Конфігурація проксі на рівні робочого процесу

Застосування налаштувань проксі на рівні завдання гарантує, що всі кроки в межах цього завдання успадкують конфігурацію.

name: CI with Proxy
on: [push]

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.company.com,github.com
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Node.js dependencies
        run: npm install

      - name: Download a file via curl
        run: curl -v https://api.example.com/data

      - name: Access internal service (bypasses proxy)
        run: curl -v http://internal-service.internal.company.com/status

Конфігурація проксі на рівні кроку

Для сценаріїв, що вимагають різних налаштувань проксі для конкретних кроків, або для перевизначення налаштувань на рівні завдання, змінні середовища можуть бути визначені на рівні кроку.

name: CI with Specific Step Proxy
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env: # Default proxy for the job (if any)
      HTTP_PROXY: http://default-proxy:8080
      HTTPS_PROXY: http://default-proxy:8080
      NO_PROXY: localhost,127.0.0.1
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Step using default proxy
        run: curl https://external-api.com/v1

      - name: Step using a different proxy
        env:
          HTTP_PROXY: http://special-proxy:3128
          HTTPS_PROXY: http://special-proxy:3128
          NO_PROXY: localhost,127.0.0.1,api.special-domain.com
        run: curl https://api.special-domain.com/v2

Аутентифікація проксі за допомогою секретів

Якщо ваш проксі вимагає аутентифікації, включіть ім'я користувача та пароль безпосередньо в URL проксі. Для безпеки зберігайте облікові дані як секрети GitHub Actions і посилайтеся на них у робочому процесі.

Спочатку створіть секрети репозиторію (наприклад, PROXY_USER, PROXY_PASS) у налаштуваннях вашого репозиторію GitHub.

name: Authenticated Proxy Workflow
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://${{ secrets.PROXY_USER }}:${{ secrets.PROXY_PASS }}@proxy.example.com:8080
      HTTPS_PROXY: http://${{ secrets.PROXY_USER }}:${{ secrets.PROXY_PASS }}@proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1,.internal.company.com
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Perform network operation
        run: npm install # or curl, etc.

Поширені інструменти та взаємодія з проксі

Хоча HTTP_PROXY та HTTPS_PROXY широко підтримуються, деякі інструменти пропонують специфічні методи конфігурації.

Команди git

git зазвичай враховує HTTP_PROXY та HTTPS_PROXY для віддалених операцій. Для явної конфігурації або у випадках, коли змінних середовища недостатньо, можна використовувати git config.

# Set proxy for HTTP and HTTPS git operations
git config --global http.proxy http://proxy.example.com:8080
git config --global https.proxy http://proxy.example.com:8080

# Configure a specific proxy for a particular remote
git config http.https://github.com/.proxy http://github-proxy:8080

npm, yarn

Менеджери пакетів Node.js, такі як npm та yarn, враховують змінні середовища HTTP_PROXY та HTTPS_PROXY. Вони також надають власні команди конфігурації для постійних налаштувань.

# Using npm config
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080
npm config set no-proxy localhost,127.0.0.1,.internal.com

# Using yarn config
yarn config set proxy http://proxy.example.com:8080
yarn config set httpsProxy http://proxy.example.com:8080
yarn config set no-proxy localhost,127.0.0.1,.internal.com

docker (Збірка образу та виконання контейнера)

Налаштування проксі для Docker вимагають специфічної обробки як для часу збірки образу, так і для часу виконання контейнера.

Проксі під час збірки Docker

Для команд, що виконуються під час docker build (наприклад, RUN apk add, RUN apt-get update), налаштування проксі повинні бути передані як аргументи збірки.

Приклад Dockerfile:

FROM alpine:latest

# Define build arguments for proxy settings
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# Set environment variables for subsequent RUN commands
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

# Example: Use proxy for package installation
RUN apk add --no-cache curl

# ... rest of your Dockerfile

Крок робочого процесу GitHub Actions:

- name: Build Docker image with proxy
  run: |
    docker build . \
      --build-arg HTTP_PROXY=${{ env.HTTP_PROXY }} \
      --build-arg HTTPS_PROXY=${{ env.HTTPS_PROXY }} \
      --build-arg NO_PROXY=${{ env.NO_PROXY }} \
      -t my-app:latest

Проксі під час виконання контейнера Docker

Якщо ваш робочий процес запускає контейнер Docker (наприклад, використовуючи ключ container: або docker run), налаштування проксі повинні бути передані як змінні середовища до контейнера.

Використання ключа container::

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: my-custom-image:latest
      env:
        HTTP_PROXY: ${{ env.HTTP_PROXY }}
        HTTPS_PROXY: ${{ env.HTTPS_PROXY }}
        NO_PROXY: ${{ env.NO_PROXY }}
    steps:
      - name: Run command inside container
        run: curl https://external-api.com/data

Використання docker run у кроці:

- name: Run Docker container with proxy
  run: |
    docker run \
      -e HTTP_PROXY=${{ env.HTTP_PROXY }} \
      -e HTTPS_PROXY=${{ env.HTTPS_PROXY }} \
      -e NO_PROXY=${{ env.NO_PROXY }} \
      my-app:latest /app/script.sh

Java-додатки (Maven, Gradle)

Java-додатки, включаючи інструменти збірки, такі як Maven та Gradle, зазвичай вимагають передачі налаштувань проксі як системних властивостей Java. Це зазвичай робиться за допомогою змінних середовища MAVEN_OPTS або _JAVA_OPTIONS.

# For Maven
export MAVEN_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts='localhost|127.0.0.1|*.internal.com'"

# For Gradle (also applies to other JVM-based tools)
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts='localhost|127.0.0.1|*.internal.com'"

Крім того, Maven можна налаштувати через ~/.m2/settings.xml, а Gradle – через gradle.properties у каталозі проекту або домашньому каталозі користувача.

Усунення несправностей проксі

• Перевірте змінні середовища: Використовуйте run: env | grep -i proxy у кроці, щоб переконатися, що змінні середовища проксі правильно встановлені та видимі для оболонки ранера.
• Перевірте NO_PROXY: Переконайтеся, що будь-які внутрішні хости або домени GitHub правильно перераховані в NO_PROXY, щоб запобігти непотрібному проксіюванню або проблемам маршрутизації.
• Журнали проксі-сервера: Якщо можливо, перевірте журнали проксі-сервера на наявність спроб підключення з IP-адреси ранера GitHub Actions. Це допомагає визначити, чи досягає запит проксі та чому він може бути відхилений (наприклад, помилка аутентифікації, відмовлено в доступі).
• Мережеве підключення: Використовуйте curl -v --proxy <your-proxy-url> <target-url> з кроку робочого процесу, щоб явно перевірити підключення через проксі до відомої зовнішньої кінцевої точки.
• Проблеми з сертифікатами SSL/TLS: Якщо ви використовуєте HTTPS-проксі або отримуєте доступ до HTTPS-сайтів через HTTP-проксі, і проксі виконує перевірку SSL, ранер може зіткнутися з помилками перевірки сертифіката. Це вимагає додавання кореневого сертифіката CA проксі до сховища довіри ранера. Це складна конфігурація, яка часто керується налаштуваннями самостійно розміщених ранерів.

Підсумок конфігурації проксі