Перейти до змістуЯкщо ви намагаєтеся розібратися, як налаштувати проксі в GitHub Actions, або шукаєте практичний підхід до proxy settings GitHub Actions, почніть із простого питання: що саме має проходити через проксі, а що — ні? Від відповіді залежить, чи задаватимете ви змінні для одного кроку, одного завдання чи всього workflow. Помилитеся — і runner спокійно відправить трафік не туди, куди ви планували.
На перший погляд GitHub Actions здається простим: YAML-файл, runner і кілька команд. Проблеми починаються тоді, коли завантаження пакета зависає по тайм-ауту, приватний registry відмовляє в підключенні або скануванню безпеки потрібен вихідний доступ через корпоративний проксі. Тоді проксі стає частиною workflow, а не просто мережевою деталлю.
1. Визначте точну область дії проксі у вашому workflow
Починати потрібно з області дії, тому що GitHub Actions — це не один суцільний shell. Один workflow може містити 1 job, 5 кроків і кілька різних мережевих маршрутів, і кожному з них може знадобитися свій набір правил. Крок збірки, який тягне залежності, може йти через проксі, а крок деплою до внутрішнього хоста має обходити його.
Думайте шарами. Якщо проксі потрібен лише одній команді, задайте його там. Якщо він потрібен кожному кроку в job, визначте його на рівні job. Якщо від нього залежить увесь workflow, розмістіть змінні на рівні workflow, а потім додайте короткий список винятків у NO_PROXY. Звучить нудно — але економить години.
Практичний приклад: Node-збірка може потребувати проксі для npm install, але пізніший крок, який надсилає дані до внутрішнього webhook, не повинен проходити через той самий шлюз. У такому разі проксі належить кроку або job збірки, а не етапу розгортання. Універсального рішення тут майже не буває.
2. Зберігайте налаштування проксі в secrets репозиторію або організації
Не вставляйте облікові дані проксі прямо у workflow-файли. Адреса та порт можуть бути не критичними, але ім’я користувача й пароль мають зберігатися в GitHub Secrets або в змінних рівня середовища, захищених так само. Залишайте YAML читабельним і не тягніть секретні дані в історію комітів.
Зручний підхід — зберегти повний URL проксі або розбити значення на окремі secrets, наприклад PROXY_HOST, PROXY_PORT, PROXY_USER і PROXY_PASS. У будь-якому випадку файл workflow залишається коротким. Це важливо, коли через пів року той самий файл відкриють п’ять людей, і один із них буде дуже поспішати.
Для одного проєкту достатньо repository secrets. Organization secrets більше підходять тоді, коли один і той самий проксі-політик використовується в кількох репозиторіях, особливо в компанії зі спільною CI-мережею. Для ширшого порівняння інструментів приватності та проксі-зв’язок дивіться розділ VPN, proxy & privacy guides.
3. Додайте змінні середовища проксі до job або кроку
Більшість інструментів у GitHub Actions розуміють стандартні змінні проксі. Використовуйте HTTP_PROXY, HTTPS_PROXY і NO_PROXY, а також варіанти в нижньому регістрі, якщо інструмент до них прискіпується; іншими словами, враховуйте GitHub Actions HTTP_PROXY HTTPS_PROXY NO_PROXY як базову схему сумісності. Деякі скрипти читають лише назви в верхньому регістрі, тоді як деякі старі бібліотеки віддають перевагу нижньому. Щоб уникнути сюрпризів, задавайте обидва варіанти.
На рівні job змінні застосовуються до кожного кроку всередині нього. На рівні step вони діють лише для команди, що йде далі. Цю різницю легко прогавити під час швидкого редагування, і тоді виникає помилка, коли один пакет встановлюється нормально, а наступний падає вже на наступному рядку.
Чистий блок job на практиці часто виглядає так: проксі визначається в env, облікові дані зберігаються в secrets, а команди успадковують середовище. Якщо один крок має обійти проксі, краще перевизначити змінну саме там, а не переписувати весь job. Коротко, прямо і зручно для перевірки.
Якщо вивід runner'а взагалі не згадує проксі, перевірте, чи справді інструмент читає змінні середовища. Деякі CLI це роблять, деякі ігнорують їх, а деяким потрібен власний конфіг-файл. Глосарій VPN і проксі допоможе, якщо хочете розібратися в термінах, перш ніж змінювати налаштування.
4. Передайте налаштування проксі для job на основі контейнерів і сервісів
Контейнерні job трохи відрізняються, тому що job виконується всередині контейнера, а не напряму на хості runner'а. У багатьох випадках потрібно дублювати змінні проксі всередині середовища контейнера, і іноді те саме стосується service containers. Якщо пропустити цей крок, хост зможе дістатися проксі, а контейнер — ні.
Ця різниця важлива у workflow, де поруч із основним job працюють бази даних, браузери або тестові сервіси. Контейнер бази даних може взагалі не потребувати проксі, а тестовому контейнеру, який завантажує бінарник браузера, він, ймовірно, потрібен. Правило має бути явним, а не припущеним.
Є ще практична особливість із контейнерними образами. Якщо образ має власний менеджер пакетів або bootstrap-скрипт, він може зробити вихідні запити ще до того, як виконається перший крок workflow. У такому разі змінні проксі треба вбудувати в опис контейнера, а не додавати пізніше в shell-команді. Ранній трафік — теж трафік.
5. Налаштуйте типові пакети та інструменти всередині Actions
Налаштування, яке залежить від конкретного інструмента, — це місце, де ховається багато CI-проблем із проксі. Node, npm, Python-інструменти, Git-операції, curl і менеджери пакетів для різних мов можуть поводитися по-різному. Деякі коректно читають змінні середовища. Деякі надають перевагу власному конфігураційному файлу. Деяким потрібні обидва варіанти.
Для Node-workflow перша перевірка зазвичай пов’язана зі встановленням пакетів. Якщо npm не може дістатися registry, перевірте, чи проксі було задано до кроку встановлення, а також чи самому registry не потрібна окрема конфігурація. Те саме стосується встановлення Python-пакетів, які падають лише після першого запиту. Проксі був, але інструмент його не слухав.
Git може бути не менш вибагливим. Дія checkout може пройти успішно, а пізніший git fetch всередині скрипта — зірватися, особливо якщо скрипт працює в іншому середовищі. Менеджер пакетів в одному кроці та команда Git в іншому — це не один і той самий клієнт, тому не припускайте, що один параметр покриє обидва випадки.
Якщо ваш workflow залежить від доступу до пакетів через фільтровану мережу, корисно спершу прочитати вузький гайд, наприклад статтю як обрати VPN, перш ніж визначатися з ширшою схемою підключення. Проксі — лише одна частина; інша — це маршрут виходу з runner'а.
6. Обробка автентифікованих проксі та прихованих облікових даних
Автентифіковані проксі — звична річ у корпоративному CI, і URL часто містить ім’я користувача та пароль. Зберігайте ці значення в secrets, а потім збирайте URL під час виконання, замість того щоб жорстко прописувати його у workflow-файлі. Одного витоку в лог достатньо.
GitHub маскує secrets у логах, але маскування — це не магія. Якщо скрипт виведе повний URL проксі в debug-рядку або покаже значення змінних під час діагностики, ви можете відкрити більше, ніж планували. Обмежуйте debug-вивід і не скидайте всі змінні лише для того, щоб подивитися одну.
Краще спершу тестувати безпечну команду, наприклад запит до пакета або metadata-запит, і переконатися, що команда спрацьовує без виводу самого проксі. Якщо проксі потребує автентифікації, скористайтеся гідом із найкращих практик автентифікації проксі, щоб безпечніше все організувати ще до того, як щось потрапить у CI.
Ще одне невелике застереження: якщо ви покладете облікові дані в secret репозиторію і потім використовуватимете цей secret у кількох job, кожен job, який може читати secret, зможе й надсилати трафік через проксі. Це нормально, але має бути свідомим рішенням. Облікові дані проксі — це все одно облікові дані.
7. Виключайте внутрішні хости та endpoints GitHub через NO_PROXY
NO_PROXY — це та частина, яку люди відкладають, аж доки щось не зламається. Потім додають один хост, тестують знову і знаходять ще один хост, який слід було виключити одразу. Додайте localhost, loopback-адреси, внутрішні домени та будь-які service names, які мають залишатися прямими. Зазвичай такий список довший, ніж очікуєш.
GitHub-орієнтовані endpoints також можуть потребувати окремої обробки. Деякі workflow мають звертатися до сервісів GitHub напряму, тоді як інші запити повинні проходити через проксі. Якщо без перевірки гнати весь трафік через проксі, можна отримати повільний checkout, затримки webhook або неочікувані скарги на сертифікати. Проксі — не завжди правильний шлях.
До внутрішніх імен варто ставитися уважно, бо вони часто відрізняються від публічних лише одним суфіксом. Наприклад, build-сервер може бути доступний як build.local у внутрішній мережі й бути повністю непридатним через проксі. Додайте цей хост у NO_PROXY, а не сподівайтеся, що DNS сам усе владнає.
Якщо хочете глибше розібратися в правилах обходу, перегляньте як приховати IP-адресу — там добре пояснено логіку, які запити мають іти напряму, а які ні. Та сама звичка розділяти внутрішній і зовнішній трафік тут теж працює, лише вже в CI-контексті.
8. Перевірте workflow і усуньте збої проксі
Спершу протестуйте все на одному маленькому кроці, перш ніж довіряти всьому workflow. Просте завантаження, перевірка версії або запит заголовка скаже більше, ніж довгий build-log. Якщо цей крок не проходить, не міняйте одразу три налаштування. Змініть одне, запустіть ще раз і подивіться на результат.
Тайм-аути зазвичай вказують на проблему з маршрутизацією, заблокований destination або адресу проксі, до якої runner не може дістатися. Помилки сертифікатів часто означають, що проксі перехоплює TLS, а runner не довіряє ланцюжку видавця. Помилки пакетів можуть означати, що з проксі все гаразд, але інструмент ігнорує змінні середовища. У кожної помилки свій «запах».
Також корисно відділяти проблему проксі від обмежень runner'а. У GitHub-hosted runner'ів є мережеві правила, які ви не можете змінити, а self-hosted runner'и можуть мати правила firewall, що зовні виглядають як проблема з проксі. Якщо один runner працює, а інший падає на тому самому workflow, причина може бути зовсім не в проксі.
Для швидкої перевірки здорового глузду перевірте вихідну адресу після завершення workflow. Якщо вам потрібен чекліст для цього, стаття як перевірити, чи приховано вашу IP-адресу все ще є корисним зразком, навіть якщо середовище інше. Числа, endpoints і коди відповіді розповідають історію краще, ніж здогадки.
Коли ви порівнюєте типи збоїв, тримайте одне правило: якщо помилка з’являється до першого мережевого запиту, дивіться на YAML і secrets; якщо вона виникає під час отримання пакета, перевіряйте змінні проксі та конфігурацію інструмента; якщо вона трапляється лише на одному хості, дивіться на NO_PROXY і DNS. Такий поділ на три випадки економить час. І так, дуже багато часу.