پروکسی برای گیت لب: چگونه دسترسی تیم و پایپ‌لاین‌های CI/CD را بدون مشکل تنظیم کنیم

```html

GitLab — یک پلتفرم محبوب برای ذخیره‌سازی کد و مدیریت فرآیندهای DevOps است که هزاران تیم در سرتاسر جهان از آن استفاده می‌کنند. اما اگر دسترسی به GitLab در سطح ارائه‌دهنده، شبکه شرکتی یا یک کشور به طور کلی مسدود شده باشد، چه باید کرد؟ و بدتر از آن — زمانی که پایپ‌لاین CI/CD در وسط شب به دلیل اینکه runner نمی‌تواند به مخزن دسترسی پیدا کند، دچار افت می‌شود.

در این مقاله بررسی می‌کنیم که چگونه پروکسی را برای GitLab در سطح Git-client، GitLab Runner و سرور شرکتی تنظیم کنیم — به طوری که تمام تیم از هر نقطه‌ای از جهان به طور پایدار کار کند.

چرا به پروکسی برای GitLab نیاز داریم: سناریوهای واقعی

قبل از تنظیم پروکسی، مهم است که بفهمید دقیقاً چه مشکلی را حل می‌کنید. وضعیت‌ها متفاوت هستند و این بر انتخاب نوع پروکسی و روش اتصال آن تأثیر می‌گذارد.

سناریو 1: GitLab توسط ارائه‌دهنده یا در سطح کشور مسدود شده است

در برخی کشورها و شبکه‌های شرکتی، دسترسی به gitlab.com محدود شده است. توسعه‌دهنده ترمینال را باز می‌کند، git pull را می‌نویسد — و timeout دریافت می‌کند. در این حالت، پروکسی به عنوان واسطه عمل می‌کند: ترافیک به طور مستقیم به gitlab.com نمی‌رود، بلکه از طریق یک سرور میانی در کشوری که محدودیتی وجود ندارد، عبور می‌کند.

سناریو 2: تیم توزیع‌شده در کشورهای مختلف

تصور کنید: بخشی از تیم از روسیه کار می‌کند، بخشی از قزاقستان، و بخشی از اروپا. هر کدام شرایط شبکه‌ای متفاوت و محدودیت‌های مختلفی دارند. برای اینکه همه به طور پایدار و با سرعت یکسان کار کنند، شرکت‌ها یک سرور پروکسی شرکتی راه‌اندازی می‌کنند که از طریق آن تمام ترافیک به GitLab از یک کانال واحد عبور می‌کند.

سناریو 3: CI/CD runner نمی‌تواند به وابستگی‌های خارجی دسترسی پیدا کند

GitLab Runner پایپ‌لاین را راه‌اندازی می‌کند و در مرحله npm install یا pip install همه چیز دچار افت می‌شود — زیرا سروری که runner روی آن اجرا می‌شود، در یک شبکه بسته بدون دسترسی مستقیم به اینترنت قرار دارد. پروکسی به runner این امکان را می‌دهد که وابستگی‌های خارجی را دریافت کند، بدون اینکه دسترسی کامل به اینترنت برای کل سرور باز شود.

سناریو 4: GitLab خود میزبانی شده در پشت فایروال شرکتی

شرکت یک سرور GitLab خود را در شبکه داخلی نگه می‌دارد. توسعه‌دهندگان از راه دور باید به آن متصل شوند. به جای VPN برای تمام ترافیک، می‌توان پروکسی را فقط برای ترافیک GitLab تنظیم کرد — این سریع‌تر و ساده‌تر در مدیریت است.

سناریو 5: نظارت و حسابرسی ترافیک

شرکت‌های بزرگ تمام ترافیک به مخازن را از طریق پروکسی شرکتی هدایت می‌کنند تا فعالیت‌ها را ثبت کنند، کنترل کنند که چه کسی و چه چیزی را push می‌کند و عملیات‌های ناخواسته را مسدود کنند. این یک نیاز امنیتی است، نه دور زدن مسدودیت‌ها.

مهم است که قبل از تنظیم درک کنید:

پروکسی برای GitLab ممکن است به طور همزمان در سه سطح نیاز باشد: بر روی ماشین توسعه‌دهنده (Git-client)، بر روی سرور با GitLab Runner (CI/CD)، و بر روی خود سرور GitLab (اگر خود میزبانی شده باشد). هر سطح به طور جداگانه تنظیم می‌شود.

کدام نوع پروکسی برای GitLab مناسب است

GitLab بر روی پروتکل‌های HTTPS و SSH کار می‌کند. این به طور خودکار تعیین می‌کند که کدام نوع پروکسی قابل استفاده است و کدام نیست. بیایید گزینه‌ها را بررسی کنیم.

نوع پروکسی	پروتکل	مناسب برای GitLab	کی استفاده کنیم
پروکسی HTTP/HTTPS	HTTP, HTTPS	✓ بله	Git over HTTPS, رابط وب GitLab
پروکسی SOCKS5	TCP (هر نوع)	✓ بله (بهترین گزینه)	Git over HTTPS و SSH, CI/CD
پروکسی SOCKS4	TCP	~ به طور جزئی	فقط اگر SOCKS5 وجود نداشته باشد
پروکسی شفاف	HTTP	✗ خیر	مناسب نیست — مسدودیت‌ها را دور نمی‌زند

برای کار با GitLab، انتخاب بهینه — SOCKS5 است. این پروکسی در سطح TCP کار می‌کند، بنابراین به طور یکسان هم اتصالات HTTPS (رابط وب، git clone از طریق HTTPS) و هم اتصالات SSH (git push/pull از طریق SSH در پورت 22 یا 443) را پروکسی می‌کند.

پروکسی‌های مسکونی در مقابل پروکسی‌های مرکز داده برای GitLab

اینجا همه چیز به وظیفه بستگی دارد. اگر هدف — دور زدن مسدودیت بر اساس GeoIP یا دریافت IP پایدار برای احراز هویت باشد، پروکسی‌های مرکز داده مناسب هستند — آن‌ها سریع‌تر، ارزان‌تر و تأخیر کمتری دارند، که در کار با مخازن بزرگ حیاتی است.

اما اگر IP شرکتی شما در لیست مسدود شده GitLab قرار گرفته باشد (که ممکن است در اثر اسکن‌های تهاجمی یا پس از حوادث امنیتی اتفاق بیفتد)، باید به پروکسی‌های مسکونی فکر کنید — آدرس‌های IP آن‌ها متعلق به کاربران واقعی خانگی است و به ندرت توسط پلتفرم‌ها مسدود می‌شود.

تنظیم پروکسی برای Git-client (به صورت جهانی)

این رایج‌ترین سناریو است: توسعه‌دهنده نمی‌تواند به GitLab از ماشین خود متصل شود. تنظیمات از طریق پیکربندی خود Git انجام می‌شود — یک بار، و برای تمام مخازن کار می‌کند.

گزینه A: پروکسی HTTPS برای Git

اگر با GitLab از طریق HTTPS کار می‌کنید (آدرس مخزن با https:// شروع می‌شود)، در ترمینال اجرا کنید:

# تنظیم پروکسی HTTP به صورت جهانی
git config --global http.proxy http://آدرس_پروکسی_شما:پورت

# اگر پروکسی نیاز به احراز هویت دارد
git config --global http.proxy http://نام_کاربری:رمز_عبور@آدرس_پروکسی_شما:پورت

# برای پروکسی SOCKS5 (توصیه می‌شود)
git config --global http.proxy socks5://آدرس_پروکسی_شما:پورت

# بررسی کنید که تنظیمات اعمال شده است
git config --global --get http.proxy

گزینه B: پروکسی فقط برای gitlab.com (دیگر مخازن را تحت تأثیر قرار نمی‌دهد)

اگر نمی‌خواهید پروکسی برای تمام عملیات‌های Git اعمال شود (برای مثال، GitHub یا Bitbucket به خوبی کار می‌کنند)، می‌توانید پروکسی را فقط برای یک دامنه خاص تنظیم کنید:

# پروکسی فقط برای gitlab.com
git config --global http.https://gitlab.com.proxy socks5://آدرس_پروکسی_شما:پورت

# یا برای GitLab خود میزبانی شده
git config --global http.https://git.yourcompany.com.proxy socks5://آدرس_پروکسی_شما:پورت

گزینه C: SSH از طریق پروکسی (برای کسانی که از SSH استفاده می‌کنند)

اگر مخازن را از طریق SSH ([email protected]:... ) کلون می‌کنید، تنظیم پروکسی در پیکربندی SSH انجام می‌شود، نه در Git. فایل ~/.ssh/config را باز کنید و اضافه کنید:

# برای Linux/macOS — از طریق nc (netcat)
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand nc -X 5 -x آدرس_پروکسی_شما:پورت %h %p

# برای Windows — از طریق connect.exe (Git for Windows)
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand connect -S آدرس_پروکسی_شما:پورت %h %p

پس از تنظیم، اتصال را با دستور ssh -T [email protected] بررسی کنید. اگر همه چیز به درستی تنظیم شده باشد، پیام خوشامدگویی از GitLab را مشاهده خواهید کرد.

چگونه پروکسی را غیرفعال کنیم، زمانی که دیگر نیازی نیست

# حذف پروکسی جهانی
git config --global --unset http.proxy

# حذف پروکسی برای دامنه خاص
git config --global --unset http.https://gitlab.com.proxy

پروکسی برای GitLab Runner و پایپ‌لاین‌های CI/CD

GitLab Runner یک عامل است که وظایف را از .gitlab-ci.yml اجرا می‌کند. اگر runner در یک شبکه بسته یا بر روی سروری با دسترسی محدود به اینترنت قرار داشته باشد، باید پروکسی را به طور جداگانه تنظیم کنید. تنظیمات Git-client توسعه‌دهنده در اینجا کمک نخواهد کرد — runner بر روی ماشین دیگری کار می‌کند.

روش 1: متغیرهای محیطی در پیکربندی runner

فایل پیکربندی GitLab Runner را باز کنید (معمولاً /etc/gitlab-runner/config.toml) و متغیرهای محیطی را در بخش [runners.env] اضافه کنید:

[[runners]]
  name = "my-runner"
  url = "https://gitlab.com/"
  token = "توکن_شما"
  executor = "shell"
  environment = [
    "HTTP_PROXY=http://آدرس_پروکسی_شما:پورت",
    "HTTPS_PROXY=http://آدرس_پروکسی_شما:پورت",
    "NO_PROXY=localhost,127.0.0.1,دامنه_داخلی_شما.com"
  ]

پس از تغییر پیکربندی، runner را دوباره راه‌اندازی کنید: sudo gitlab-runner restart

روش 2: متغیرها در .gitlab-ci.yml (در سطح پایپ‌لاین)

اگر شما مدیر runner نیستید یا می‌خواهید پروکسی را فقط برای یک پروژه خاص تنظیم کنید، متغیرها را مستقیماً در فایل پایپ‌لاین اضافه کنید:

variables:
  HTTP_PROXY: "http://آدرس_پروکسی_شما:پورت"
  HTTPS_PROXY: "http://آدرس_پروکسی_شما:پورت"
  NO_PROXY: "localhost,127.0.0.1,.internal.company.com"

stages:
  - build
  - test
  - deploy

build:
  stage: build
  script:
    - npm install   # حالا از طریق پروکسی خواهد رفت
    - npm run build

روش 3: متغیرها در تنظیمات پروژه GitLab (بدون کامیت در مخزن)

بهترین روش برای داده‌های حساس (پروکسی با احراز هویت): به Settings → CI/CD → Variables پروژه خود بروید و متغیرهای HTTP_PROXY، HTTPS_PROXY، NO_PROXY را به عنوان متغیرهای محافظت‌شده (masked) اضافه کنید. آن‌ها به طور خودکار در تمام پایپ‌لاین‌ها در دسترس خواهند بود، اما در لاگ‌ها قابل مشاهده نخواهند بود.

پروکسی برای Docker executor

اگر runner از Docker executor استفاده می‌کند، به طور پیش‌فرض، کانتینرها تنظیمات پروکسی میزبان را به ارث نمی‌برند. باید یا متغیرها را در config.toml در بخش [runners.docker] اضافه کنید، یا یک فایل /etc/systemd/system/docker.service.d/proxy.conf در میزبان با runner ایجاد کنید:

[Service]
Environment="HTTP_PROXY=http://آدرس_پروکسی_شما:پورت"
Environment="HTTPS_PROXY=http://آدرس_پروکسی_شما:پورت"
Environment="NO_PROXY=localhost,127.0.0.1"

پس از آن: sudo systemctl daemon-reload && sudo systemctl restart docker

پروکسی برای سرور GitLab خود میزبانی شده

اگر شما سرور GitLab خود را مدیریت می‌کنید (که از طریق Omnibus یا Helm نصب شده است)، پروکسی برای این است که خود GitLab بتواند به سرویس‌های خارجی دسترسی پیدا کند: ارسال اعلان‌ها، اتصال به سیستم‌های CI خارجی، بارگذاری آواتارهای کاربران، ادغام با Jira یا Slack.

تنظیم در gitlab.rb (نصب Omnibus)

فایل /etc/gitlab/gitlab.rb را باز کنید و خطوط زیر را اضافه یا uncomment کنید:

# پروکسی برای GitLab (Omnibus)
gitlab_rails['env'] = {
  "http_proxy" => "http://آدرس_پروکسی_شما:پورت",
  "https_proxy" => "http://آدرس_پروکسی_شما:پورت",
  "no_proxy" => "localhost,127.0.0.1,دامنه_داخلی_شما"
}

# اگر پروکسی با احراز هویت باشد:
gitlab_rails['env'] = {
  "http_proxy" => "http://نام_کاربری:رمز_عبور@آدرس_پروکسی_شما:پورت",
  "https_proxy" => "http://نام_کاربری:رمز_عبور@آدرس_پروکسی_شما:پورت",
  "no_proxy" => "localhost,127.0.0.1"
}

پس از تغییر پیکربندی، تنظیمات را اعمال کنید: sudo gitlab-ctl reconfigure

تنظیم اتصالات خروجی از طریق Admin Area

در GitLab 15.0+ این امکان وجود دارد که پروکسی را مستقیماً از طریق رابط وب تنظیم کنید: به Admin Area → Settings → Network → Outbound requests بروید. در اینجا می‌توانید پروکسی را برای وب‌هوک‌های خروجی تنظیم کنید و دامنه‌های IP را که GitLab می‌تواند به آن‌ها دسترسی پیدا کند، محدود کنید. این برای امنیت مفید است — از حملات SSRF از طریق وب‌هوک‌ها جلوگیری می‌کند.

سازماندهی دسترسی برای تمام تیم از طریق پروکسی

وقتی نیاز به تأمین دسترسی پایدار به GitLab برای تیمی از 5 تا 50 نفر دارید، تنظیمات فردی بر روی هر ماشین — بهترین رویکرد نیست. بیایید راه‌حل‌های مقیاس‌پذیرتری را بررسی کنیم.

رویکرد 1: سرور پروکسی شرکتی

یک سرور پروکسی (برای مثال، Squid یا 3proxy) با دسترسی به اینترنت راه‌اندازی می‌شود. تمام توسعه‌دهندگان Git را برای استفاده از این سرور تنظیم می‌کنند. مزایا: مدیریت متمرکز، نقطه کنترل واحد، امکان ثبت ترافیک. معایب: سرور به یک نقطه شکست تبدیل می‌شود.

رویکرد 2: آینه (mirror) مخزن

GitLab از آینه‌سازی مخازن پشتیبانی می‌کند. می‌توان GitLab خود میزبانی شده را در شبکه داخلی به عنوان آینه gitlab.com تنظیم کرد. توسعه‌دهندگان با سرور داخلی کار می‌کنند و آن با پروکسی با خارجی همگام‌سازی می‌شود. این وابستگی به کیفیت اتصال پروکسی را برای هر توسعه‌دهنده کاهش می‌دهد.

رویکرد 3: تنظیم خودکار از طریق dotfiles یا اسکریپت onboarding

برای تیم‌هایی که هر توسعه‌دهنده خود محیط را تنظیم می‌کند، راحت است که یک اسکریپت onboarding ایجاد کنید که به طور خودکار تنظیمات مورد نیاز Git را وارد کند. این اسکریپت در مخزن شرکتی ذخیره می‌شود و هنگام تنظیم محل کار جدید اجرا می‌شود.

#!/bin/bash
# setup-git-proxy.sh — در هنگام تنظیم محل کار جدید اجرا شود

PROXY_HOST="proxy.company.com"
PROXY_PORT="3128"

echo "تنظیم پروکسی Git برای دسترسی به GitLab..."
git config --global http.https://gitlab.com.proxy "socks5://${PROXY_HOST}:${PROXY_PORT}"
git config --global http.sslVerify true
echo "آماده است! بررسی کنید: git config --global --list | grep proxy"

چک‌لیست برای استقرار تیمی

• تعیین کنید که آیا پروکسی در سطح توسعه‌دهندگان، runnerها یا سرور GitLab (یا هر سه) نیاز است
• نوع پروکسی را انتخاب کنید: SOCKS5 برای حداکثر سازگاری
• تنظیم NO_PROXY برای تمام دامنه‌ها و سرویس‌های داخلی
• عملکرد کلیدهای SSH را از طریق پروکسی بررسی کنید (یک مرحله جداگانه!)
• تنظیمات را در ویکی شرکتی مستند کنید
• یک اسکریپت onboarding برای کارمندان جدید ایجاد کنید
• نظارت بر دسترسی پروکسی سرور را تنظیم کنید

مشکلات رایج و راه‌حل‌های آن‌ها

حتی پس از تنظیم صحیح، گاهی اوقات چیزی درست پیش نمی‌رود. در اینجا رایج‌ترین مشکلات و روش‌های تشخیص آن‌ها آورده شده است.

مشکل 1: مشکل گواهی SSL: قادر به دریافت گواهی‌دهنده محلی نیست

این خطا زمانی رخ می‌دهد که پروکسی (به ویژه پروکسی شرکتی) بازرسی SSL را انجام می‌دهد — گواهی GitLab را با گواهی خود جایگزین می‌کند. Git به این گواهی اعتماد ندارد. راه‌حل: گواهی ریشه شرکتی را به لیست گواهی‌های معتبر اضافه کنید.

# راه‌حل موقت (برای اشکال‌زدایی، نه برای تولید!)
git config --global http.sslVerify false

# راه‌حل صحیح: افزودن گواهی شرکتی
git config --global http.sslCAInfo /مسیر/به/corporate-ca-bundle.crt

مشکل 2: پروکسی برای HTTPS کار می‌کند، اما SSH کار نمی‌کند

این یک وضعیت کلاسیک است: http.proxy را در Git تنظیم کرده‌اید، کلون کردن HTTPS کار کرده، اما عملیات‌های SSH هنوز انجام نمی‌شوند. دلیل: ترافیک SSH از طریق پروکسی HTTP نمی‌رود. باید ~/.ssh/config را به طور جداگانه تنظیم کنید، همانطور که در بخش Git-client توضیح داده شده است.

گزینه دیگر: به کار با GitLab از طریق HTTPS به جای SSH سوئیچ کنید. برای این کار URL از راه دور را تغییر دهید:

# بررسی URL از راه دور فعلی
git remote -v

# تغییر از SSH به HTTPS
git remote set-url origin https://gitlab.com/username/repo.git

مشکل 3: پایپ‌لاین CI/CD در مرحله کلون کردن مخزن متوقف می‌شود

Runner مخزن را به طور مستقیم از GitLab کلون می‌کند، با استفاده از توکن. اگر runner در پشت پروکسی قرار داشته باشد، این کلون کردن نیز باید از طریق پروکسی انجام شود. اطمینان حاصل کنید که متغیرهای HTTP_PROXY و HTTPS_PROXY در config.toml تنظیم شده‌اند، نه فقط در .gitlab-ci.yml — متغیرهای فایل CI پس از کلون کردن اعمال می‌شوند، نه قبل از آن.

مشکل 4: پروکسی کار می‌کند، اما بسیار کند است

اگر push/pull کار می‌کند، اما 5 تا 10 برابر بیشتر از معمول زمان می‌برد، مشکل ممکن است در ظرفیت پروکسی یا موقعیت جغرافیایی آن باشد. برای کار با مخازن بزرگ (بیش از 100 مگابایت) مهم است که پروکسی با تأخیر کم و ظرفیت بالا انتخاب کنید. پروکسی‌های مرکز داده در این مورد بر پروکسی‌های مسکونی ترجیح داده می‌شوند — آن‌ها کانال پایدارتر و بهتری را فراهم می‌کنند.

مشکل 5: احراز هویت از طریق پروکسی نیاز به ورود مجدد رمز عبور دارد

اگر پروکسی نیاز به احراز هویت Basic دارد و Git هر بار رمز عبور را درخواست می‌کند، helper اعتبارنامه را تنظیم کنید:

# macOS — استفاده از Keychain
git config --global credential.helper osxkeychain

# Windows — استفاده از Windows Credential Manager
git config --global credential.helper manager

# Linux — کش کردن به مدت 1 ساعت
git config --global credential.helper "cache --timeout=3600"

نتیجه‌گیری و توصیه‌ها

تنظیم پروکسی برای GitLab — وظیفه‌ای است که به طور همزمان در چند سطح انجام می‌شود. برای توسعه‌دهنده در ماشین کاری، کافی است چند خط در پیکربندی Git یا SSH وارد کند. برای CI/CD باید متغیرهای محیطی را به پیکربندی runner یا تنظیمات پروژه اضافه کنید. و برای GitLab خود میزبانی شده — باید gitlab.rb را به‌روزرسانی کرده و پیکربندی را دوباره بسازید.

قوانین اصلی که به شما کمک می‌کند تا از بیشتر مشکلات جلوگیری کنید:

• از SOCKS5 استفاده کنید — هم با HTTPS و هم با SSH کار می‌کند
• همیشه NO_PROXY را برای سرویس‌های داخلی تنظیم کنید
• در تولید SSL-احراز هویت را غیرفعال نکنید — گواهی شرکتی را اضافه کنید
• برای CI/CD پروکسی را در config.toml تنظیم کنید، نه فقط در .gitlab-ci.yml
• تنظیمات را مستند کنید — توسعه‌دهنده جدید در تیم از شما تشکر خواهد کرد

اگر به دنبال یک پروکسی مطمئن برای سازماندهی دسترسی پایدار به GitLab از هر نقطه‌ای از جهان هستید، پیشنهاد می‌کنیم به پروکسی‌های مرکز داده فکر کنید — آن‌ها سرعت انتقال داده بالا و تأخیر کم را فراهم می‌کنند، که به ویژه در کار با مخازن بزرگ و پایپ‌لاین‌های CI/CD فشرده مهم است. برای تیم‌هایی که حریم خصوصی حداکثری یا دور زدن مسدودیت‌های GeoIP برایشان مهم است، پروکسی‌های مسکونی با IP‌های کاربران واقعی خانگی مناسب هستند.