GitLab 초기 관리자 설정¶

작성 기준: GitLab Community Edition v18.9.2

GitLab 설치 직후 초기 root 로그인부터 기본 운영 정책 적용까지의 흐름을 정리함.

아래 항목은 사내 GitLab 운영을 위한 권장 설정 기준임. 설정은 가능하면 Admin UI 우선으로 하고, 필요 시 runbook용 CLI 명령으로 일괄 적용함. CLI 명령은 운영 편의를 위한 예시이며, GitLab의 공식 관리 기준은 Admin UI 또는 Application Settings API로 봄.

적용 시 주의사항¶

일부 Application Setting 변경은 즉시 반영되지 않을 수 있으며, 기본적으로 최대 60초 정도 캐시될 수 있음
즉시 일관된 반영 여부가 중요하면 적용 후 UI 또는 API 기준으로 재확인함
모든 설정이 GitLab 재시작을 요구하는 것은 아님
관리자 UI의 일반 설정은 저장 후 반영되는 경우가 많지만, 세션/애플리케이션 캐시/구성 파일(gitlab.rb) 관련 변경은 재시작 또는 재구성이 필요할 수 있음
CLI 설정 키는 GitLab 버전에 따라 달라질 수 있으므로, 실행 후 반드시 반영 상태를 확인함

설정 반영 확인 방법¶

설정 적용 후에는 아래 순서로 반영 상태를 확인함.

GitLab 서비스 상태 확인

sudo gitlab-ctl status

운영 기준: - 주요 서비스가 모두 run 상태여야 함

브라우저에서 Admin UI 재확인
설정을 변경한 동일 경로로 다시 진입
저장한 값이 유지되는지 확인
필요 시 60초 정도 대기 후 재확인
일부 Application Setting은 캐시로 인해 즉시 반영되지 않을 수 있음
기능 단위 검증
예: Sign-up 비활성화 시 회원가입 화면 접근 확인
예: PAT 만료 정책 변경 시 새 토큰 생성 화면에서 만료일 요구 여부 확인
예: Instance Runner 비활성화 시 신규 프로젝트에서 기본 활성 여부 확인
세션/보안/인증 계열 설정은 별도 동작 확인
예: 2FA 강제, Admin Mode, Session timeout, Remember me, 로그인 알림 등은 테스트 계정으로 실제 로그인/로그아웃 흐름까지 검증함

재시작 / 재구성 필요 시 처리 방법¶

일부 설정은 즉시 반영되지 않거나, 서비스 재시작 또는 재구성이 필요할 수 있음. 특히 /etc/gitlab/gitlab.rb 변경 또는 세션/애플리케이션 레벨 설정 변경 시 해당함.

1. 재구성 (gitlab.rb 변경 시)¶

sudo gitlab-ctl reconfigure

/etc/gitlab/gitlab.rb 설정 변경 후 반드시 실행
내부 서비스 설정 재적용
일반적으로 서비스 중단 없이 적용됨 (일부 순간적 영향 가능)

2. GitLab 서비스 재시작¶

sudo gitlab-ctl restart

운영 기준:

다음 경우에만 수행함:
- 설정 반영이 지연되거나 정상 동작하지 않는 경우
- 세션 / 인증 / 캐시 관련 설정 변경 후 즉시 반영이 필요한 경우
- 서비스 상태가 비정상일 경우

주의 사항:

전체 GitLab 서비스가 재시작되므로 짧은 시간 동안 서비스 중단 발생
운영 환경에서는 가능하면 점검 시간에 수행 권장

3. 서비스 상태 재확인¶

sudo gitlab-ctl status

운영 기준:

모든 주요 서비스가 run 상태인지 확인
일부 서비스가 down 상태이면 로그 확인 필요

운영 메모¶

대부분의 Admin UI 설정은 재시작 없이 반영됨
Application Setting은 최대 약 60초 캐시로 인해 반영 지연이 있을 수 있음
무조건 restart 하지 말고, 먼저 UI 반영 여부 → 기능 검증 → 필요 시 재시작 순서로 진행함

1. 초기 관리자 접근 및 필수 작업¶

GitLab 설치 직후에는 먼저 초기 root 비밀번호를 확인해야 함.

sudo cat /etc/gitlab/initial_root_password

이 비밀번호로 아래 주소에 접속하여 root 로그인 수행:

https://gitlab.example.com

최초 로그인 후 바로 해야 할 것:

root 비밀번호 변경
root 이메일 수정

`/etc/gitlab/initial_root_password` 주의사항¶

최초 설치 직후 root 비밀번호를 알려주기 위해 생성되는 임시 파일
GitLab 설치 후 약 24시간 동안 /etc/gitlab/initial_root_password 에 저장되며, 이후 자동 제거됨.
root 비밀번호 변경 완료 후 즉시 삭제

sudo rm /etc/gitlab/initial_root_password

2. 기본 점검¶

설정 변경 전 아래 항목을 우선 확인함.

sudo gitlab-ctl status
sudo gitlab-rake gitlab:check SANITIZE=true
sudo ss -tulnp | grep 8081
sudo ss -tulnp | grep 2222

운영 기준:

모든 서비스 run 상태
gitlab:check Warning / Fail 제거

3. 회원가입 및 계정 생성 정책¶

사내용 GitLab은 기본적으로 관리자 초대 / 생성 방식으로 운영함. 외부 또는 무분별한 가입을 막는 것이 우선임.

경로¶

Admin Area → Settings → General → Sign-up restrictions

설정 방법¶

Admin Area → Settings → General
Sign-up restrictions 펼침
Sign-up enabled → 비활성화
Save changes

sudo gitlab-rails runner "ApplicationSetting.last.update(signup_enabled: false)"

운영 메모¶

비활성화 후 신규 사용자는 관리자가 직접 생성하거나 초대로만 가입 가능
사내용 GitLab 기본 운영 기준

4. 회사 도메인 설정¶

회원가입이 비활성화되어 있어도, 회사 도메인 정책을 함께 정해두면 운영 기준이 명확해짐.

단, - 초대 기반에서는 email domain validation 이 별도 로직임 - Sign-up 이 비활성화된 상태에서는 직접적인 영향은 없음 - 향후 self-signup 활성화 시 적용됨

경로¶

Admin Area → Settings → General → Sign-up restrictions

설정 방법¶

Admin Area → Settings → General
Sign-up restrictions 펼침
Allowed domains for sign-ups 항목에 회사 도메인 입력 (예: example.com)
Save changes

sudo gitlab-rails runner "ApplicationSetting.last.update(domain_allowlist: ['example.com'])"

운영 메모¶

회원가입이 꺼져 있어도 도메인 기준을 명시해두면 추후 정책 변경 시 기준이 명확함
초대 기반 운영에서도 이메일 도메인 기준으로 내부/외부 구분 가능

5. 기본 공개 범위¶

프로젝트 및 그룹의 기본 공개 범위를 제한하여 실수로 인한 외부 노출을 방지함.

경로¶

Admin Area → Settings → General → Visibility and access controls

설정 방법¶

Admin Area → Settings → General
Visibility and access controls 펼침
Default project visibility → Private
Default group visibility → Private
Restricted visibility levels → Public
Save changes

sudo gitlab-rails runner "ApplicationSetting.last.update(default_project_visibility: 0, default_group_visibility: 0)"

Restricted visibility levels 설명¶

이 항목은 일반 사용자가 선택할 수 없는 공개 범위를 지정하는 설정임. 체크된 항목은 일반 사용자가 선택 불가능해짐.

값	의미	restricted_visibility_levels
`Private`	초대된 멤버만 접근 가능	0
`Internal`	GitLab 로그인 사용자 전체 공개	10
`Public`	인터넷 전체 공개. 제한 권장	20

sudo gitlab-rails runner "ApplicationSetting.last.update(restricted_visibility_levels: [20])"

운영 메모¶

사내용 GitLab에서 가장 일반적인 기준은 Public 제한만 적용하는 방식
더 보수적으로 운영하려면 Internal 까지 제한하여 사실상 Private only 로 운영 가능

6. 프로젝트 생성 권한¶

무분별한 프로젝트 생성을 방지하고 최소 권한 원칙을 적용함.

경로¶

Admin Area → Settings → General → Visibility and access controls

설정 방법¶

Admin Area → Settings → General
Visibility and access controls 펼침
Default minimum role required to create projects → Developers
Save changes

UI 옵션	내부 값 (default_project_creation)	설명
No one	0	아무도 프로젝트 생성 불가
Administrators	(UI 전용)	관리자만 생성 가능
Owners	(UI 전용 / 1 기반)	Owner 이상
Maintainers	1	Maintainer 이상
Developers	2	Developer 이상 (권장)

sudo gitlab-rails runner "ApplicationSetting.last.update(default_project_creation: 2)"

운영 메모¶

Developer 이상만 프로젝트 생성 가능
개인 namespace 난립 방지
그룹 중심 프로젝트 구조 유지
최소 권한 원칙 적용

7. Git 프로토콜¶

경로¶

Admin Area → Settings → General → Visibility and access controls

설정 방법¶

Admin Area → Settings → General
Visibility and access controls 펼침
Enabled Git access protocols → Both SSH and HTTP(S)
Save changes

운영 메모¶

개발자는 SSH 기반 clone / push 선호
CI/CD, 토큰 기반 자동화는 HTTPS 사용 빈도가 높음
둘 다 열어두는 것이 운영 유연성 측면에서 유리함

8. 로그인 보안 (2FA)¶

경로¶

Admin Area → Settings → General → Sign-in restrictions

설정 방법¶

Admin Area → Settings → General
Sign-in restrictions 펼침
Enforce two-factor authentication → 활성화
Two-factor grace period → 48 입력
Enforce two-factor authentication for administrators → 활성화
Enable Admin Mode → 활성화
Enable email notification → 활성화
Save changes

설명:

Enforce two-factor authentication
- 전체 사용자 로그인에 2FA를 강제함
Enforce two-factor authentication for administrators
- 관리자 계정에만 2FA를 강제함
Two-factor grace period
- 기존 사용자가 2FA를 등록할 수 있도록 허용하는 유예 시간(시간 단위)임
- 0이면 다음 로그인부터 즉시 강제됨
Enable Admin Mode
- 관리자 계정이 기본적으로 항상 관리자 권한 상태로 동작하지 않도록 함
- 일반 그룹/프로젝트 작업은 평상시 계정 권한으로 사용 가능하며, 관리자 기능 수행 시 추가 인증이 필요함
- 단, 일부 기능은 예외가 있을 수 있으므로 모든 관리자 행위를 완전히 별도 보호하는 기능으로 간주하지는 않음
Enable email notification
- 익숙하지 않은 로그인 위치가 감지되면 사용자에게 메일 알림을 보냄

sudo gitlab-rails runner "ApplicationSetting.last.update(require_two_factor_authentication: true, two_factor_grace_period: 48)"
sudo gitlab-rails runner "ApplicationSetting.last.update(admin_mode: true)"
sudo gitlab-rails runner "ApplicationSetting.last.update(notify_on_unknown_sign_in: true)"

2FA grace period 설명¶

2FA 강제 설정 후 기존 사용자에게 설정 완료까지 허용하는 유예 시간. 이 시간 내에 2FA를 등록하지 않으면 로그인이 제한됨.

운영 메모¶

사내용 GitLab은 전체 사용자 2FA 강제가 권장됨
기존 사용자 전환 시 Two-factor grace period = 48 정도가 무난함
관리자 계정은 2FA와 함께 Admin Mode 활성화를 권장함
단, Admin Mode는 모든 관리자 행위를 완전히 차단/분리하는 절대적 보호 장치는 아님
관리자 기능 진입 시 추가 인증을 요구하는 보조 통제 수단으로 이해해야 함

명령어로 2FA 비활성화 (긴급 시)¶

UI 접근이 불가한 상황에서 관리자가 2FA를 강제 비활성화해야 할 경우:

sudo gitlab-rails runner "ApplicationSetting.last.update(require_two_factor_authentication: false)"

적용 확인:

sudo gitlab-rails runner "puts ApplicationSetting.last.require_two_factor_authentication"

false 출력 시 비활성화 완료.

9. 비밀번호 정책¶

경로¶

Admin Area → Settings → General → Sign-up restrictions

설정 방법¶

Admin Area → Settings → General
Sign-up restrictions 펼침
Minimum password length → 8
(선택) Allowed domains for sign-ups → 회사 도메인 example.com 추가
(선택) Email confirmation settings → hard
Save changes

CLI 설정¶

sudo gitlab-rails runner "ApplicationSetting.last.update(minimum_password_length: 8)"
sudo gitlab-rails runner "ApplicationSetting.last.update(email_confirmation_setting: 'hard')"
sudo gitlab-rails runner "ApplicationSetting.last.update(domain_allowlist: ['example.com'])"

설정 항목 설명¶

Minimum password length
- 사용자 비밀번호 최소 길이를 설정함
- 기본값은 8이며, 보안을 위해 12 이상 권장
Allowed domains for sign-ups
- 특정 도메인(email domain)만 가입 허용
- 예: sncompany.com
- 사내 GitLab에서는 필수 설정 권장
Email confirmation settings
- Off: 이메일 인증 없이 가입 가능
- Soft: 로그인은 가능하지만 3일 내 이메일 인증 필요
- Hard: 이메일 인증 완료 후에만 로그인 가능

적용 범위¶

비밀번호 정책은 다음 시점에 적용됨:
- 신규 사용자 가입 시
- 기존 사용자가 비밀번호 변경 시
기존 사용자 비밀번호에는 즉시 강제되지 않음

운영 기준¶

최소 길이 8 이상 권장. 원래는 12 이상
이메일 인증은 Hard 권장
사내 도메인(example.com)만 가입 허용
공개 GitLab이 아니라면 회원가입 자체 비활성화도 고려 가능

sudo gitlab-rails runner "ApplicationSetting.last.update(signup_enabled: false)"

주의 사항¶

비밀번호 복잡도(숫자, 대소문자, 특수문자 강제)는 Premium / Ultimate 전용 기능임
CE 환경에서는 최소 길이 중심으로 정책 구성해야 함

10. 계정 운영 원칙¶

root 이메일 수정¶

root 계정 로그인
우측 상단 사용자 메뉴 → Edit profile
이메일 주소 수정
Update profile settings

최고 관리자 계정 생성¶

Admin Area → Overview → Users
New user
개인 계정 생성
필요 시 Admin 권한 부여

운영 메모¶

root 계정은 일상 사용 금지
관리자 변경 이력은 개인 계정 기준으로 남기는 것이 추적에 유리함
GitLab 시스템 설정용 계정으로 어떠한 Group 및 Project 에도 속하지 않음.

11. Access Token 만료 및 정리 정책¶

토큰을 무기한 방치하지 않기 위한 최소 기준을 설정함.

경로¶

Admin Area → Settings → General → Account and limit

설정 방법¶

Admin Area → Settings → General
Account and limit 펼침
Require expiration date → 활성화. 최대 90일
(선택) Inactive project and group access token retention period → 30. 일(days) 단위
Save changes

CLI 설정¶

sudo gitlab-rails runner "ApplicationSetting.last.update(require_personal_access_token_expiry: true)"
sudo gitlab-rails runner "ApplicationSetting.last.update(max_personal_access_token_lifetime: 90)"

설정 항목 설명¶

Require expiration date
- 새로 생성되는 Access Token에 만료일 설정을 강제함
Inactive project and group access token retention period
- 일정 기간 동안 사용되지 않은 Project / Group Access Token을 자동 삭제함
- 비워두면 자동 삭제되지 않음

운영 기준¶

발급 시점 통제 정책임
기존 토큰에는 소급 적용되지 않음

주의 사항¶

max_personal_access_token_lifetime는 일부 버전/에디션에서 UI에 표시되지 않을 수 있음
CLI 설정은 여전히 적용됨
기존 토큰에는 정책이 소급 적용되지 않음
만료된 토큰은 자동으로 사용 불가 처리됨

12. SMTP 설정 (선택)¶

메일 기능이 필요하면 /etc/gitlab/gitlab.rb 에 SMTP 설정을 추가함.

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = 'smtp.example.com'
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = 'gitlab@example.com'
gitlab_rails['smtp_password'] = 'password'
gitlab_rails['smtp_domain'] = 'example.com'
gitlab_rails['smtp_authentication'] = 'login'
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['gitlab_email_from'] = 'gitlab@example.com'

적용:

sudo gitlab-ctl reconfigure

발송 테스트:

sudo gitlab-rails runner "Notify.test_email('admin@example.com', 'GitLab Test', 'Test').deliver_now"

운영 메모¶

SMTP 설정 없이도 GitLab 자체 기능은 동작하나, 이메일 알림 / 초대 / 비밀번호 재설정 등이 모두 비활성화됨
사내 메일 서버 또는 외부 SMTP 릴레이 어느 쪽이든 동일한 구조로 설정 가능

13. SSH Key 알고리즘 및 길이 제한¶

보안이 취약한 오래된 알고리즘의 키 사용을 차단하고, 강력한 SSH 키 사용을 강제함.

경로¶

Admin Area → Settings → General → Visibility and access controls

설정 방법¶

Admin Area → Settings → General
Visibility and access controls 펼침
SSH 키 제한 설정:
- RSA SSH keys → Must be at least 3072 bits
- DSA SSH keys → Are forbidden
- ECDSA SSH keys → Are allowed
- ED25519 SSH keys → Are allowed
- ECDSA_SK SSH keys → Are allowed
- ED25519_SK SSH keys → Are allowed
Save changes

CLI 설정¶

sudo gitlab-rails runner "ApplicationSetting.last.update(dsa_key_restriction: -1, rsa_key_restriction: 3072)"

적용 확인:

sudo gitlab-rails runner "s=ApplicationSetting.last; puts \"dsa=#{s.dsa_key_restriction}, rsa=#{s.rsa_key_restriction}\""

운영 메모¶

제한이 걸린 키 타입은 새로 업로드할 수 없음
기존에 등록된 키도 정책에 맞지 않으면 삭제되지는 않지만 비활성화되며, 해당 키로 push/pull 할 수 없음
GitLab Self-Managed 기본값은 DSA 금지, RSA 허용, ECDSA 허용, ED25519 허용임
사내 표준은 ED25519 권장, RSA 사용 시 3072 bits 이상 권장

14. IP 필터링 참고사항¶

외부망 접속이 필요한 경우¶

재택근무나 외부 협력사 접속이 필요할 경우, 다음 중 하나의 방법을 선택함:

VPN 권장: 사내 VPN 접속 후 할당받는 내부 IP 대역을 allow 목록에 포함.
공인 IP 추가: 접속자의 공인 IP를 deny all; 상단에 allow [IP]; 형태로 추가.

차단 확인 (Troubleshooting)¶

외부에서 접속 시 Nginx error.log에 directory index of "..." is forbidden 또는 access forbidden by rule 메시지가 찍히며 클라이언트에 403 Forbidden이 반환되는지 확인.

15. Outbound request 차단 설정¶

내부망 SSRF(Server-Side Request Forgery) 공격을 방지함. Webhook, Integration, System Hook이 내부 네트워크에 요청을 보내는 것을 차단함.

⚠️ 주의: 만약 사내 Jira나 Slack 대용으로 쓰는 내부 메신저와 Webhook 연동이 필요하다면, 이 설정 때문에 연동이 막힘

경로¶

Admin Area → Settings → Network → Outbound requests

설정 방법¶

Admin Area → Settings → Network
Outbound requests 펼침
Allow requests to the local network from webhooks and integrations → 비활성화
Allow requests to the local network from system hooks → 비활성화
Save changes

sudo gitlab-rails runner "
settings = ApplicationSetting.last
settings.update(
    allow_local_requests_from_web_hooks_and_services: false,
    allow_local_requests_from_system_hooks: false
)
"

운영 메모¶

이 설정이 열려 있으면 공격자가 Webhook을 이용해 내부망 서비스(메타데이터 서버, DB 등)에 접근 가능
사내 GitLab일수록 내부망과 인접해 있어 반드시 닫아야 함
만약 사내 Jira나 Slack 대용으로 쓰는 내부 메신저와 Webhook 연동이 필요하다면, 이 설정 때문에 연동이 막힘 즉, 신뢰할 수 있는 사내 서비스 IP 들은 allowlist 에 추가 등록이 필요함

16. Runner 등록 정책¶

GitLab Runner 등록은 보안 강화를 위해 기존 Registration Token 방식이 아닌 Runner Authentication Token 기반으로 운영함.

경로¶

Admin Area → CI/CD → Runners

설정 방법¶

Admin Area → CI/CD → Runners
Allow runner registration token → 비활성화
Runner는 개별 생성 후 Authentication Token으로 등록

변경 사항¶

기존 Registration token 방식은 deprecated 되었으며 사용 금지 (Disabled 유지)
최신 GitLab에서는 Runner별 Authentication Token 방식 사용
GitLab 17.0부터 기본 비활성화됨. 특별한 이유가 없으면 사용하지 않음. GitLab 20.0에서 제거 예정임.

Runner 등록 방식 (권장)¶

GitLab UI에서 Runner 생성
생성된 Runner의 Authentication Token 확인
서버에서 Runner 등록:

gitlab-runner register

입력 시: - GitLab URL - Authentication Token 입력

운영 기준¶

Registration Token 방식 사용 금지
Runner는 반드시 개별 생성 후 등록
토큰은 Runner 단위로 관리 (공용 토큰 금지)
GitLab 최신 정책 기준 기본 비활성화 권장

보안 포인트¶

기존 Registration Token은 유출 시 모든 Runner 등록 가능 (위험)
Authentication Token은 Runner 단위로 제한됨 (안전)

Legacy 설정 (비권장)¶

Allow runner registration token

가능하면 비활성화 유지
필요한 경우에만 임시로 활성화

17. Instance Runner 제어¶

사내 인프라 리소스를 보호하고, 공용 Runner 사용을 최소화하기 위한 정책을 적용함.

※ Instance Runner는 과거 Shared Runner 개념과 유사하나, GitLab 공식 문서에서는 Instance Runner 용어를 사용함

경로¶

Admin Area → Settings → CI/CD → Continuous Integration and Deployment

설정 방법¶

Admin Area → Settings → CI/CD
Continuous Integration and Deployment 펼침
Enable instance runners for new projects 비활성화
Save changes

CLI 설정¶

sudo gitlab-rails runner "ApplicationSetting.last.update(instance_runners_enabled: false)"

운영 메모¶

신규 프로젝트는 기본적으로 Instance Runner를 사용할 수 없음
Runner가 필요한 경우:
- 프로젝트에서 수동으로 활성화하거나
- Group Runner 또는 Project Runner를 별도로 등록하도록 유도함
공용 Runner 남용 방지 및 리소스 보호 목적

용어 정리¶

Instance Runner
- 인스턴스 전체 범위에서 사용할 수 있는 Runner
Group Runner
- 특정 그룹 및 하위 범위에서 사용할 수 있는 Runner
Project Runner
- 특정 프로젝트에 한정되는 Runner
Shared Runner
- 과거 문맥에서 사용되던 표현으로 이해할 수 있으나, 본 문서에서는 최신 공식 용어인 Instance Runner를 사용함

18. 세션 및 쿠키 보안 (Session Security)¶

사내망이라도 세션 하이재킹을 방지하고 계정 탈취 위험을 최소화하기 위한 설정임. GitLab은 external_url이 https://로 설정된 경우 세션 쿠키에 Secure 속성을 자동으로 부여함. 별도 설정 불필요. 단, Remember me 옵션이 활성화되어 있으면 사용자는 특정 브라우저에서 장기간 로그인 상태를 유지할 수 있음. 따라서 세션 만료 정책을 엄격하게 운영하려면 Session timeout duration 설정만으로는 부족하며, Remember me 비활성화 여부를 함께 관리해야 함.

Remember me 설정 및 세션 만료 시간 설정:

경로¶

Admin Area → Settings → General → Account and limit

설정 방법¶

Account and limit 펼침
Remember me → 비활성화
(권장) Expire session from creation date → 활성화
Session timeout duration → 480 (8시간) 입력
Save changes

sudo gitlab-rails runner "ApplicationSetting.last.update(session_expire_delay: 480)"

운영 메모¶

업무 시간 기준 하루치 세션 운영 기준으로 적절함
단, Remember me가 활성화되어 있으면 세션 만료 의도가 약화될 수 있으므로 함께 점검해야 함
필요 시 Expire session from creation date까지 활성화하여 세션 생성 시점 기준 강제 만료 정책을 적용함
보안 또는 컴플라이언스 목적으로 세션이 반드시 종료되어야 하는 환경에서는 Remember me 비활성화를 권장함
보다 엄격한 운영이 필요하면 Expire session from creation date까지 함께 활성화하여, 세션 생성 시점 기준으로 강제 만료되도록 구성할 수 있음

19. 외부 서비스 연동 제한 (Gravatar 비활성화)¶

사용자 이메일의 해시값이 외부 서버(gravatar.com)로 전송되는 것을 차단하여 내부 정보 유출을 방지함.

경로¶

Admin Area → Settings → General → Account and limit

설정 방법¶

Account and limit 펼침
Gravatar enabled → 비활성화
Save changes

sudo gitlab-rails runner "ApplicationSetting.last.update(gravatar_enabled: false)"

운영 메모¶

폐쇄망 또는 엄격한 보안이 필요한 환경에서는 필수 설정임. 프로필 이미지는 GitLab 내부 업로드 기능만 사용하도록 제한됨.

20. 로그인 Rate Limit 및 Brute-force 방어¶

무차별 대입 공격(Brute-force) 및 Credential Stuffing 공격을 방지하기 위해 GitLab의 Network Rate Limit 정책을 점검하고 필요한 항목을 설정함.

최신 GitLab에서는 Rate Limit 관련 설정이 하나의 단일 섹션에만 묶여 있지 않고, Admin Area → Settings → Network 및 기능별 설정 영역에 나뉘어 관리될 수 있음. 또한 일부 제한은 UI 설정 외에도 Rack::Attack, application-level rate limit, 기능별 개별 제한으로 나뉘어 동작함. 따라서 GitLab UI 설정은 기본 관리 지점으로 사용하되, 실제 운영에서는 Reverse Proxy / WAF / Fail2ban 등 외부 제어 계층과 함께 구성해야 함.

경로¶

Admin Area → Settings → Network

설정 방법¶

Admin Area → Settings → Network
필요한 개별 Rate Limit 섹션을 확인
운영 환경에 맞게 제한값 설정
Save changes

주요 확인 대상¶

Users API rate limit
Projects API rate limit
Git HTTP rate limits
Import and export rate limits
Pipelines Rate Limits
Package registry rate limits
기타 Network 하위 rate limit 관련 항목

운영 기준¶

로그인 공격 방어는 GitLab 내부 Rate Limit만으로 충분하지 않음
GitLab 내부 제한과 함께 Reverse Proxy / WAF / Fail2ban을 병행 구성하는 것을 기본 운영 기준으로 함
각 항목은 인증 사용자 기준(per user)과 비인증 요청 기준(per IP)이 다를 수 있으므로 항목별 적용 기준을 확인함
프록시 또는 NAT 환경에서는 여러 사용자가 동일 IP로 보일 수 있으므로, 너무 낮은 IP 기반 제한은 정상 사용자나 관리자까지 차단할 수 있어 주의함
GitLab 자체 Rate Limit은 보조 방어 수단으로 간주하며, 외부 네트워크 레벨 차단이 1차 방어선임

운영 메모¶

Rate Limit은 항목별로 적용 기준이 다를 수 있음
- 일부는 사용자 기준
- 일부는 IP 기준
0 입력 시 비활성화되는 항목이 있을 수 있음
설정값은 서비스 특성(API 사용량, Runner 수, 내부 자동화 사용 여부)을 고려해 조정함
GitLab UI 설정은 1차 통제 수단으로 사용하고, 외부 공격 방어는 반드시 프록시/WAF/차단 도구와 함께 운영함

고급 운영¶

Nginx / Reverse Proxy 레벨 Rate Limit 추가
Fail2ban으로 /users/sign_in 관련 공격 패턴 탐지 및 IP 차단
필요 시 WAF와 병행 운영

로그 확인 예시¶

sudo grep -Ei "Failed login|rate limit|429 Too Many Requests" /var/log/gitlab/gitlab-rails/production*.log
sudo grep -Ei "throttle|rate limit" /var/log/gitlab/gitlab-rails/production_json.log

21. 저장소 및 업로드 용량 제한¶

리소스 남용 및 디스크 고갈을 방지하기 위한 정책임.

21.1. 첨부파일 및 Push 제한¶

경로¶

Admin Area → Settings → General → Account and limit

설정 방법¶

Admin Area → Settings → General
Account and limit 펼침
아래 항목 설정:
- Maximum attachment size (MiB) → 100
- Maximum push size (MiB) → 1024
Save changes

CLI 설정¶

sudo gitlab-rails runner "
ApplicationSetting.last.update(
    max_attachment_size: 100,
    receive_max_input_size: 1024
)
"

Maximum push size (MiB)는 UI 기준으로 관리할 것. GitLab 설정은 캐시될 수 있어 즉시 반영되지 않을 수 있음.

21.2. CI/CD Artifacts 제한¶

경로¶

Admin Area → Settings → CI/CD → Continuous Integration and Deployment

설정 방법¶

Admin Area → Settings → CI/CD
Continuous Integration and Deployment 펼침
아래 항목 설정:
- Maximum artifacts size (MB) → 500
Save changes

운영 메모¶

Maximum artifacts size (MB)는 Job Artifacts 최대 업로드 크기 제한임
Keep the latest artifacts for all jobs in the latest successful pipelines가 활성화되면 최신 성공 파이프라인 artifacts는 만료되지 않을 수 있으므로 저장소 증가를 고려해야 함

참고 사항¶

Repository size limit는 GitLab Self-Managed에서 관리자 설정이 가능함
프로젝트 특성에 따라 일괄 고정값을 두기보다, 운영 정책에 맞춰 선택적으로 적용함
저장소 전체 크기 정책과 별개로 아래 항목은 계속 개별 관리가 필요함
- Maximum push size (MiB)
- Maximum attachment size (MiB)
- Maximum artifacts size (MB)
대용량 바이너리는 Git 저장소 대신 S3, AIStor 같은 외부 스토리지 사용을 권장함

21.3. CI/CD Dotenv Artifacts 변수 개수 제한¶

경로¶

Admin Area → Settings → CI/CD → Continuous Integration and Deployment → CI/CD limits

설정 방법¶

Admin Area → Settings → CI/CD
Continuous Integration and Deployment 펼침
CI/CD limits 섹션 확인
Maximum number of variables in a dotenv artifact 값을 조정
- 기본값: 20
- 권장값: 50
- 0: 제한 비활성화
Save Default limits

CLI 설정¶

sudo gitlab-rails runner "
Plan.default.actual_limits.update!(
  dotenv_variables: 50
)
"

22. Web IDE 보안 정책 (Domain Isolation)¶

Web IDE에서 VS Code 확장 프로그램을 실행할 때, GitLab 메인 도메인과의 보안 격리를 설정함. 별도의 호스트 도메인을 사용함으로써 확장 프로그램이 GitLab의 세션 쿠키 등에 접근하는 것을 방지함.

경로¶

Admin Area → Settings → General → Web IDE

설정 방법¶

Admin Area → Settings → General
Web IDE 섹션 확장
Extension host domain 확인: cdn.web-ide.gitlab-static.net (기본값)
Enable single origin fallback → 비활성화
Save changes

CLI 설정¶

sudo gitlab-rails runner "ApplicationSetting.last.update(vscode_extension_marketplace_single_origin_fallback_enabled: false)"

설정 항목 설명¶

Extension host domain: VS Code 확장 프로그램이 실행되는 샌드박스 도메인.
Enable single origin fallback: 설정된 호스트 도메인에 접근할 수 없을 때, 보안 격리를 포기하고 GitLab 메인 도메인에서 정적 자산을 직접 서빙하는 기능임. 보안상 취약하므로 비활성화를 강력 권장함.

운영 메모¶

보안 리스크: Fallback이 활성화된 상태에서 악성 확장 프로그램이 실행될 경우, GitLab 메인 도메인의 권한을 탈취하는 XSS 공격에 노출될 수 있음.
네트워크 확인: 이 옵션을 끄려면 GitLab 서버가 설정된 Extension host domain에 접근 가능해야 함. 폐쇄망 환경에서 외부 CDN 접근이 차단된 경우 Web IDE 확장이 로드되지 않을 수 있으므로 주의.

23. 운영 필수 사항¶

⚠️ [필독] gitlab-secrets.json 및 gitlab.rb

경로¶

/etc/gitlab/gitlab-secrets.json
/etc/gitlab/gitlab.rb

외부 백업 예시:

sudo cp /etc/gitlab/gitlab-secrets.json /[PATH]/gitlab-secrets-$(date +%F).json
sudo cp /etc/gitlab/gitlab.rb /[PATH]/gitlab-$(date +%F).rb

sudo chmod 600 /[PATH]/gitlab-secrets-$(date +%F).json
sudo chmod 600 /[PATH]/gitlab-$(date +%F).rb

중요성:

gitlab-secrets.json: 데이터베이스 암호화 키, 2FA 복구 키 등 마스터 키 포함. 분실 시 백업이 있어도 암호화된 데이터 복구 불가
gitlab.rb: SMTP 비밀번호 등 민감 설정값 포함. 분실 시 전체 설정을 처음부터 재구성해야 함
외부 백업본은 root 또는 지정된 관리자만 읽을 수 있도록 600 권한으로 보관함.

결과:

이 파일을 분실하면 백업 파일이 있어도 데이터를 복구할 수 없음. (복구 시 암호화된 데이터가 깨짐)

운영 메모¶

반드시 서버 외부(보안 USB, 팀 내 암호 관리 도구 등)에 별도로 이중 백업할 것.

24. 설정 체크리스트¶

항목	목표 값
root 비밀번호 변경	완료
root 이메일 수정	완료
개인 관리자 계정 생성	완료
Sign-up enabled	OFF
Allowed domains for sign-ups	example.com
Default project visibility	Private
Default group visibility	Private
Restricted visibility levels	Public 제한
Minimum role for project creation	Developers
Git access protocol	SSH + HTTPS
Require two-factor authentication	ON
Two-factor grace period	48시간
Admin Mode	ON
Login notification (unknown location)	ON
Password 최소 길이	8
Password 복잡도	N/A (CE 미지원)
Email confirmation	Hard
Personal access token expiry	ON
Personal access token 최대 수명	90일
DSA SSH keys	Forbidden
RSA SSH keys 최소 길이	3072 bits
ED25519 SSH keys	Allow
ECDSA SSH keys	Allow
Outbound requests (webhooks/integrations)	OFF
Outbound requests (system hooks)	OFF
Runner registration token	Disabled
Shared Runners (신규 프로젝트)	OFF
Instance runners	OFF
Gravatar	OFF
Web IDE Single origin fallback	OFF
Session duration (세션 만료)	480분
Max artifacts size	500 MB
Max attachment size	100 MB
Repository size limit	Self-Managed에서 관리자 설정 가능
SMTP 설정	Optional (Configured / Not used)
gitlab-secrets.json 외부 백업	완료
gitlab.rb 외부 백업	완료
CI/CD dotenv variables limit	50

25. GitLab Policy Check Script¶

gitlab-policy-check.sh 참고.

GitLab 초기 관리자 설정¶

적용 시 주의사항¶

설정 반영 확인 방법¶

재시작 / 재구성 필요 시 처리 방법¶

1. 재구성 (gitlab.rb 변경 시)¶

2. GitLab 서비스 재시작¶

3. 서비스 상태 재확인¶

운영 메모¶

1. 초기 관리자 접근 및 필수 작업¶

/etc/gitlab/initial_root_password 주의사항¶

2. 기본 점검¶

3. 회원가입 및 계정 생성 정책¶

경로¶

설정 방법¶

운영 메모¶

4. 회사 도메인 설정¶

경로¶

설정 방법¶

운영 메모¶

5. 기본 공개 범위¶

경로¶

설정 방법¶

Restricted visibility levels 설명¶

운영 메모¶

6. 프로젝트 생성 권한¶

경로¶

설정 방법¶

운영 메모¶

7. Git 프로토콜¶

경로¶

설정 방법¶

운영 메모¶

8. 로그인 보안 (2FA)¶

경로¶

설정 방법¶

2FA grace period 설명¶

운영 메모¶

명령어로 2FA 비활성화 (긴급 시)¶

9. 비밀번호 정책¶

경로¶

설정 방법¶

CLI 설정¶

설정 항목 설명¶

적용 범위¶

운영 기준¶

주의 사항¶

10. 계정 운영 원칙¶

root 이메일 수정¶

최고 관리자 계정 생성¶

운영 메모¶

11. Access Token 만료 및 정리 정책¶

경로¶

설정 방법¶

CLI 설정¶

설정 항목 설명¶

운영 기준¶

주의 사항¶

12. SMTP 설정 (선택)¶

운영 메모¶

13. SSH Key 알고리즘 및 길이 제한¶

경로¶

설정 방법¶

CLI 설정¶

운영 메모¶

14. IP 필터링 참고사항¶

외부망 접속이 필요한 경우¶

차단 확인 (Troubleshooting)¶

15. Outbound request 차단 설정¶

경로¶

설정 방법¶

운영 메모¶

16. Runner 등록 정책¶

경로¶

설정 방법¶

변경 사항¶

Runner 등록 방식 (권장)¶

운영 기준¶

보안 포인트¶

Legacy 설정 (비권장)¶

17. Instance Runner 제어¶

`/etc/gitlab/initial_root_password` 주의사항¶