GitLab용 프록시: 팀 및 CI/CD 설정

```html

GitLab은 전 세계 수천 개 팀이 사용하는 인기 있는 코드 저장 및 DevOps 프로세스 관리 플랫폼입니다. 그러나 제공업체, 기업 네트워크 또는 국가 차원에서 GitLab에 대한 접근이 차단된 경우 어떻게 해야 할까요? 더 나쁜 것은 CI/CD 파이프라인이 밤중에 중단되는 경우입니다. 이는 러너가 리포지토리에 접근할 수 없기 때문입니다.

이 기사에서는 Git 클라이언트, GitLab 러너 및 기업 서버 수준에서 GitLab용 프록시를 설정하는 방법을 알아보겠습니다. 이를 통해 팀 전체가 전 세계 어디에서나 안정적으로 작업할 수 있습니다.

GitLab용 프록시가 필요한 이유: 실제 시나리오

프록시를 설정하기 전에 해결하려는 문제가 무엇인지 이해하는 것이 중요합니다. 상황은 다양하며, 이에 따라 프록시 유형과 연결 방법이 달라집니다.

시나리오 1: GitLab이 제공업체 또는 국가 차원에서 차단됨

일부 국가 및 기업 네트워크에서는 gitlab.com에 대한 접근이 제한됩니다. 개발자가 터미널을 열고 git pull을 입력하면 타임아웃이 발생합니다. 이 경우 프록시는 중개자 역할을 합니다: 트래픽이 gitlab.com으로 직접 가지 않고, 제한이 없는 국가의 중간 서버를 통해 이동합니다.

시나리오 2: 다양한 국가의 분산 팀

상상해 보세요: 팀의 일부는 러시아에서, 일부는 카자흐스탄에서, 일부는 유럽에서 작업하고 있습니다. 각자 다른 네트워크 조건과 제한이 있습니다. 모든 사람이 안정적으로 동일한 속도로 작업할 수 있도록 기업은 모든 트래픽이 단일 채널을 통해 GitLab로 이동하도록 기업 프록시 서버를 배포합니다.

시나리오 3: CI/CD 러너가 외부 종속성에 접근할 수 없음

GitLab 러너가 파이프라인을 시작하고 npm install 또는 pip install 단계에서 모든 것이 중단됩니다. 이는 러너가 인터넷에 대한 직접 접근이 없는 폐쇄 네트워크에 있기 때문입니다. 프록시는 러너가 외부 종속성을 받을 수 있도록 하여 전체 서버에 대한 인터넷 접근을 열지 않습니다.

시나리오 4: 기업 방화벽 뒤에 있는 자체 호스팅 GitLab

기업은 내부 네트워크에 자체 GitLab 서버를 유지합니다. 원격 개발자는 이에 연결해야 합니다. 전체 트래픽에 대해 VPN을 사용하는 대신 GitLab 트래픽에 대해서만 프록시를 설정할 수 있습니다. 이는 더 빠르고 관리가 간편합니다.

시나리오 5: 트래픽 모니터링 및 감사

대기업은 모든 트래픽을 기업 프록시를 통해 리포지토리로 전송하여 활동을 기록하고 누가 무엇을 푸시하는지 모니터링하며 원하지 않는 작업을 차단합니다. 이는 보안 요구 사항이지 차단 우회가 아닙니다.

설정 전에 이해해야 할 사항:

GitLab용 프록시는 동시에 세 가지 수준에서 필요할 수 있습니다: 개발자의 머신(Git 클라이언트), GitLab 러너가 있는 서버(CI/CD), 그리고 자체 호스팅 GitLab 서버. 각 수준은 별도로 설정됩니다.

GitLab에 적합한 프록시 유형

GitLab은 HTTPS 및 SSH 프로토콜을 사용합니다. 이는 어떤 유형의 프록시가 적용 가능한지, 어떤 것은 적용되지 않는지를 즉시 결정합니다. 옵션을 살펴보겠습니다.

프록시 유형	프로토콜	GitLab에 적합	사용 시기
HTTP/HTTPS 프록시	HTTP, HTTPS	✓ 예	HTTPS를 통한 Git, GitLab 웹 인터페이스
SOCKS5 프록시	TCP (모든)	✓ 예 (최고의 옵션)	HTTPS 및 SSH를 통한 Git, CI/CD
SOCKS4 프록시	TCP	~ 부분적으로	SOCKS5가 없을 경우에만
투명 프록시	HTTP	✗ 아니요	적합하지 않음 — 차단 우회를 하지 않음

GitLab과 작업할 때 최적의 선택은 SOCKS5입니다. 이는 TCP 수준에서 작동하므로 HTTPS 연결(웹 인터페이스, HTTPS를 통한 git clone)과 SSH 연결(포트 22 또는 443에서 SSH를 통한 git push/pull)을 모두 잘 프록시합니다.

거주지 vs 데이터 센터 프록시

여기서는 작업에 따라 다릅니다. 목표가 GeoIP 차단을 우회하거나 인증을 위한 안정적인 IP를 얻는 것이라면 데이터 센터 프록시가 적합합니다. 이들은 더 빠르고 저렴하며 지연 시간이 낮아 대규모 리포지토리 작업에 중요합니다.

그러나 귀하의 기업 IP가 GitLab의 차단 목록에 포함된 경우(공격적인 스캔 또는 보안 사고 후 발생할 수 있음), 거주지 프록시를 고려해야 합니다. 이들의 IP 주소는 실제 가정 사용자에게 속하며 플랫폼에서 차단되는 경우가 드뭅니다.

Git 클라이언트용 프록시 설정 (전역)

가장 일반적인 시나리오입니다: 개발자가 자신의 머신에서 GitLab에 연결할 수 없습니다. 설정은 Git 자체의 구성 파일을 통해 이루어지며, 한 번만 설정하면 모든 리포지토리에 적용됩니다.

옵션 A: Git용 HTTPS 프록시

GitLab을 HTTPS를 통해 사용하는 경우(리포지토리 주소가 https://로 시작함), 터미널에서 다음을 실행합니다:

# 전역적으로 HTTP 프록시 설정
git config --global http.proxy http://귀하의_프록시_IP:포트

# 프록시가 인증을 요구하는 경우
git config --global http.proxy http://사용자명:비밀번호@귀하의_프록시_IP:포트

# SOCKS5 프록시의 경우 (권장)
git config --global http.proxy socks5://귀하의_프록시_IP:포트

# 설정이 적용되었는지 확인
git config --global --get http.proxy

옵션 B: gitlab.com 전용 프록시 (다른 리포지토리에는 적용되지 않음)

모든 Git 작업에 프록시가 적용되기를 원하지 않는 경우(예: GitHub 또는 Bitbucket은 정상적으로 작동), 특정 도메인에 대해서만 프록시를 설정할 수 있습니다:

# gitlab.com 전용 프록시
git config --global http.https://gitlab.com.proxy socks5://귀하의_프록시_IP:포트

# 또는 귀하의 자체 호스팅 GitLab에 대해
git config --global http.https://git.yourcompany.com.proxy socks5://귀하의_프록시_IP:포트

옵션 C: SSH를 통한 프록시 (SSH로 작업하는 경우)

SSH를 통해 리포지토리를 클론하는 경우([email protected]:...), 프록시 설정은 Git이 아닌 SSH 구성 파일에서 이루어집니다. ~/.ssh/config 파일을 열고 다음을 추가합니다:

# Linux/macOS의 경우 — nc (netcat)를 통해
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand nc -X 5 -x 귀하의_프록시_IP:포트 %h %p

# Windows의 경우 — connect.exe (Git for Windows)를 통해
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand connect -S 귀하의_프록시_IP:포트 %h %p

설정 후 ssh -T [email protected] 명령어로 연결을 확인하세요. 모든 것이 올바르게 설정되었다면 GitLab에서 환영 메시지를 볼 수 있습니다.

더 이상 필요하지 않을 때 프록시 비활성화하는 방법

# 전역 프록시 제거
git config --global --unset http.proxy

# 특정 도메인에 대한 프록시 제거
git config --global --unset http.https://gitlab.com.proxy

GitLab 러너 및 CI/CD 파이프라인용 프록시

GitLab 러너는 .gitlab-ci.yml에서 작업을 실행하는 에이전트입니다. 러너가 폐쇄 네트워크에 있거나 제한된 인터넷 접근이 있는 서버에 있는 경우, 프록시를 별도로 설정해야 합니다. 개발자의 Git 클라이언트 설정은 여기서 도움이 되지 않습니다 — 러너는 다른 머신에서 작동합니다.

방법 1: 러너 구성에서 환경 변수 설정

GitLab 러너 구성 파일(/etc/gitlab-runner/config.toml 일반적으로) 을 열고 [runners.env] 섹션에 환경 변수를 추가합니다:

[[runners]]
  name = "my-runner"
  url = "https://gitlab.com/"
  token = "귀하의_토큰"
  executor = "shell"
  environment = [
    "HTTP_PROXY=http://귀하의_프록시_IP:포트",
    "HTTPS_PROXY=http://귀하의_프록시_IP:포트",
    "NO_PROXY=localhost,127.0.0.1,귀하의_내부_도메인.com"
  ]

구성을 변경한 후 러너를 재시작하세요: sudo gitlab-runner restart

방법 2: .gitlab-ci.yml에서 변수 설정 (파이프라인 수준)

러너의 관리자가 아니거나 특정 프로젝트에 대해서만 프록시를 설정하려는 경우, 파이프라인 파일에 직접 변수를 추가합니다:

variables:
  HTTP_PROXY: "http://귀하의_프록시_IP:포트"
  HTTPS_PROXY: "http://귀하의_프록시_IP:포트"
  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를 보호된(마스킹된) 변수로 추가합니다. 이들은 모든 파이프라인에서 자동으로 사용 가능하지만 로그에는 표시되지 않습니다.

NO_PROXY에 대해 잊지 마세요!

변수 NO_PROXY는 매우 중요합니다. 이 변수에는 러너가 프록시를 우회하여 직접 연결해야 하는 모든 내부 도메인 및 IP를 추가해야 합니다. 그렇지 않으면 러너가 내부 서비스에 대해서도 프록시를 통해 접근하려고 시도하여 파이프라인이 중단될 수 있습니다.

Docker executor용 프록시

러너가 Docker executor를 사용하는 경우, 기본적으로 컨테이너는 호스트의 프록시 설정을 상속받지 않습니다. config.toml의 [runners.docker] 섹션에 변수를 추가하거나 러너가 있는 호스트에 /etc/systemd/system/docker.service.d/proxy.conf 파일을 생성해야 합니다:

[Service]
Environment="HTTP_PROXY=http://귀하의_프록시_IP:포트"
Environment="HTTPS_PROXY=http://귀하의_프록시_IP:포트"
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 파일을 열고 다음 줄을 추가하거나 주석을 제거합니다:

# GitLab용 프록시 (Omnibus)
gitlab_rails['env'] = {
  "http_proxy" => "http://귀하의_프록시_IP:포트",
  "https_proxy" => "http://귀하의_프록시_IP:포트",
  "no_proxy" => "localhost,127.0.0.1,귀하의_내부_도메인"
}

# 프록시가 인증을 요구하는 경우:
gitlab_rails['env'] = {
  "http_proxy" => "http://사용자명:비밀번호@귀하의_프록시_IP:포트",
  "https_proxy" => "http://사용자명:비밀번호@귀하의_프록시_IP:포트",
  "no_proxy" => "localhost,127.0.0.1"
}

구성을 변경한 후 설정을 적용하세요: sudo gitlab-ctl reconfigure

관리 영역을 통한 아웃바운드 연결 설정

GitLab 15.0 이상에서는 웹 인터페이스를 통해 프록시를 설정할 수 있는 기능이 추가되었습니다: Admin Area → Settings → Network → Outbound requests로 이동하세요. 여기에서 아웃바운드 웹훅을 위한 프록시를 지정하고 GitLab이 접근할 수 있는 IP 범위를 제한할 수 있습니다. 이는 보안에 유용하며, 웹훅을 통한 SSRF 공격을 방지합니다.

팀 전체에 대한 접근 조직화

5~50명의 팀이 GitLab에 안정적으로 접근해야 할 경우, 각 머신에 개별적으로 설정하는 것은 최선의 접근 방식이 아닙니다. 더 확장 가능한 솔루션을 살펴보겠습니다.

접근 방식 1: 기업 프록시 서버

하나의 프록시 서버(예: Squid 또는 3proxy)를 배포하여 인터넷에 접근합니다. 모든 개발자는 이 서버를 사용하도록 Git을 설정합니다. 장점: 중앙 집중식 관리, 단일 제어 지점, 트래픽 로깅 가능. 단점: 서버가 단일 실패 지점이 됩니다.

접근 방식 2: 리포지토리 미러링

GitLab은 리포지토리 미러링을 지원합니다. 내부 네트워크에서 자체 호스팅 GitLab을 gitlab.com의 미러로 설정할 수 있습니다. 개발자는 내부 서버와 작업하고, 이 서버는 프록시를 통해 외부와 동기화됩니다. 이는 각 개발자에 대한 프록시 연결 품질에 대한 의존도를 줄입니다.

접근 방식 3: dotfiles 또는 온보딩 스크립트를 통한 자동 설정

각 개발자가 환경을 직접 설정하는 팀의 경우, 필요한 Git 설정을 자동으로 작성하는 온보딩 스크립트를 만드는 것이 편리합니다. 스크립트는 기업 리포지토리에 저장되며 새로운 작업 공간 설정 시 실행됩니다.

#!/bin/bash
# setup-git-proxy.sh — 새로운 작업 공간 설정 시 실행

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

echo "GitLab 접근을 위한 Git 프록시 설정 중..."
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"

팀 배포를 위한 체크리스트

개발자, 러너 또는 GitLab 서버 수준에서 프록시가 필요한지 확인합니다 (또는 세 가지 모두)
최대 호환성을 위해 SOCKS5 프록시 유형을 선택합니다
모든 내부 도메인 및 서비스에 대해 NO_PROXY를 설정합니다
프록시를 통한 SSH 키 작동을 확인합니다 (별도의 단계!)
기업 위키에 설정을 문서화합니다
신규 직원용 온보딩 스크립트를 생성합니다
프록시 서버의 가용성을 모니터링합니다

자주 발생하는 문제 및 해결 방법

올바르게 설정한 후에도 가끔 문제가 발생할 수 있습니다. 가장 일반적인 문제와 진단 방법은 다음과 같습니다.

문제 1: SSL 인증서 문제: 로컬 발급자 인증서를 가져올 수 없음

이 오류는 프록시 서버(특히 기업 프록시)가 SSL 검사(인증서를 GitLab의 것으로 대체)를 수행할 때 발생합니다. Git은 이 인증서를 신뢰하지 않습니다. 해결 방법: 기업 루트 인증서를 신뢰할 수 있는 인증서로 추가합니다.

# 임시 해결 방법 (디버깅용, 프로덕션용 아님!)
git config --global http.sslVerify false

# 올바른 해결 방법: 기업 인증서 추가
git config --global http.sslCAInfo /경로/까지/corporate-ca-bundle.crt

문제 2: 프록시는 HTTPS에서 작동하지만 SSH는 작동하지 않음

이는 전형적인 상황입니다: Git에서 http.proxy를 설정했지만 HTTPS 클론은 작동하지만 SSH 작업은 여전히 실패합니다. 이유: SSH 트래픽은 HTTP 프록스를 통해 이동하지 않습니다. ~/.ssh/config를 별도로 설정해야 합니다.

대안: SSH 대신 HTTPS를 통해 GitLab과 작업하도록 전환합니다. 이를 위해 원격 URL을 변경합니다:

# 현재 원격 확인
git remote -v

# SSH에서 HTTPS로 변경
git remote set-url origin https://gitlab.com/username/repo.git

문제 3: CI/CD 파이프라인이 리포지토리 클론 단계에서 멈춤

러너가 GitLab에서 직접 리포지토리를 클론하고 토큰을 사용합니다. 러너가 프록시 뒤에 있다면 이 클론도 프록스를 통해 진행되어야 합니다. HTTP_PROXY 및 HTTPS_PROXY 변수가 config.toml에 설정되어 있는지 확인하세요. .gitlab-ci.yml에만 설정되어 있어서는 안 됩니다. CI 파일의 변수는 클론 후에 적용되기 때문입니다.

문제 4: 프록시는 작동하지만 매우 느림

push/pull이 작동하지만 일반적으로보다 5~10배 더 많은 시간이 소요되는 경우, 문제는 프록시 서버의 대역폭이나 지리적 위치에 있을 수 있습니다. 대규모 리포지토리(100MB 이상) 작업 시 지연 시간이 낮고 대역폭이 높은 프록시를 선택하는 것이 중요합니다. 이 경우 데이터 센터 프록시가 거주지 프록시보다 선호됩니다. 데이터 센터 프록시는 더 안정적인 채널을 제공합니다.

문제 5: 프록시를 통한 인증이 비밀번호 재입력을 요구함

프록시가 기본 인증을 요구하고 Git이 매번 비밀번호를 요청하는 경우, 자격 증명 헬퍼를 설정합니다:

# 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"

프록시 문제를 신속하게 진단하는 방법:

다음 명령어를 사용하세요: GIT_TRACE=1 GIT_CURL_VERBOSE=1 git clone https://gitlab.com/... — 이는 모든 HTTP 요청 및 응답의 자세한 로그를 출력하며, 프록시에 대한 정보도 포함됩니다.

결론 및 권장 사항

GitLab용 프록시 설정은 여러 수준에서 동시에 해결해야 하는 작업입니다. 개발자는 작업 머신에서 Git 또는 SSH 구성 파일에 몇 줄을 입력하면 됩니다. CI/CD의 경우 러너 구성이나 프로젝트 설정에 환경 변수를 추가해야 합니다. 자체 호스팅 GitLab의 경우 gitlab.rb를 업데이트하고 구성을 다시 빌드해야 합니다.

대부분의 문제를 피하는 데 도움이 되는 주요 규칙은 다음과 같습니다:

SOCKS5를 사용하세요 — HTTPS와 SSH 모두에서 작동합니다
항상 내부 서비스에 대한 NO_PROXY를 설정하세요
프로덕션에서는 SSL 검증을 비활성화하지 마세요 — 기업 인증서를 추가하세요
CI/CD의 경우 config.toml에 프록시를 설정하고 .gitlab-ci.yml에만 설정하지 마세요
설정을 문서화하세요 — 팀의 새로운 개발자가 감사할 것입니다

GitLab에 안정적으로 접근하기 위한 신뢰할 수 있는 프록시를 찾고 있다면, 데이터 센터 프록시를 고려해 보세요. 이들은 높은 데이터 전송 속도와 낮은 지연 시간을 제공하여 대규모 리포지토리 및 집중적인 CI/CD 파이프라인 작업 시 특히 중요합니다. 최대한의 익명성이나 GeoIP 차단 우회를 원하는 팀의 경우, 실제 가정 사용자에게 속한 IP를 가진 거주지 프록시가 적합합니다.