속도 제한은 웹 애플리케이션의 보안과 내구성을 높이는 데 널리 쓰이는 기법입니다. 자세한 내용은 속도 제한을 참고합니다.

다음 제한은 기본적으로 비활성화되어 있습니다.

• 인증되지 않은 API 요청(IP별).
• 인증되지 않은 웹 요청(IP별).
• 인증된 API 요청(사용자별).
• 인증된 웹 요청(사용자별).
• 인증된 의존성 프록시 요청(사용자별 또는 배포 토큰별).

API 요청에 대한 속도 제한은 프론트엔드가 보내는 요청에는 적용되지 않습니다. 해당 요청은 항상 웹 트래픽으로 집계되기 때문입니다.

사전 요구 사항#

관리자 접근 권한이 있어야 합니다.

인증되지 않은 API 요청 속도 제한 활성화#

인증되지 않은 API 요청 속도 제한을 활성화하려면 다음 단계를 수행합니다.

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.

2. 왼쪽 사이드바에서 Settings > Network를 선택합니다.

3. User and IP rate limits를 펼칩니다.

4. Enable unauthenticated API request rate limit을 선택합니다.

   • 선택 사항. Maximum unauthenticated API requests per rate limit period per IP 값을 변경합니다. 기본값은 3600 입니다.
   • 선택 사항. Unauthenticated rate limit period in seconds 값을 변경합니다. 기본값은 3600 입니다.

인증되지 않은 웹 요청 속도 제한 활성화#

인증되지 않은 요청 속도 제한을 활성화하려면 다음 단계를 수행합니다.

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.

2. 왼쪽 사이드바에서 Settings > Network를 선택합니다.

3. User and IP rate limits를 펼칩니다.

4. Enable unauthenticated web request rate limit을 선택합니다.

   • 선택 사항. Maximum unauthenticated web requests per rate limit period per IP 값을 변경합니다. 기본값은 3600 입니다.
   • 선택 사항. Unauthenticated rate limit period in seconds 값을 변경합니다. 기본값은 3600 입니다.

인증된 API 요청 속도 제한 활성화#

인증된 API 요청 속도 제한을 활성화하려면 다음 단계를 수행합니다.

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.

2. 왼쪽 사이드바에서 Settings > Network를 선택합니다.

3. User and IP rate limits를 펼칩니다.

4. Enable authenticated API request rate limit을 선택합니다.

   • 선택 사항. Maximum authenticated API requests per rate limit period per user 값을 변경합니다. 기본값은 7200 입니다.
   • 선택 사항. Authenticated API rate limit period in seconds 값을 변경합니다. 기본값은 3600 입니다.

인증된 웹 요청 속도 제한 활성화#

인증된 요청 속도 제한을 활성화하려면 다음 단계를 수행합니다.

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.

2. 왼쪽 사이드바에서 Settings > Network를 선택합니다.

3. User and IP rate limits를 펼칩니다.

4. Enable authenticated web request rate limit을 선택합니다.

   • 선택 사항. Maximum authenticated web requests per rate limit period per user 값을 변경합니다. 기본값은 7200 입니다.
   • 선택 사항. Authenticated web rate limit period in seconds 값을 변경합니다. 기본값은 3600 입니다.

인증된 의존성 프록시 요청 속도 제한 활성화#

컨테이너 이미지용 의존성 프록시에 대한 인증된 요청은 기본적으로 인증된 웹 요청 속도 제한에 집계됩니다. 이 경우 컨테이너 이미지 풀이 해당 사용자의 다른 웹 트래픽과 할당량을 공유합니다. 병렬로 실행되는 CI/CD 풀이 이 할당량을 모두 소진하면 429 오류로 실패할 수 있습니다.

의존성 프록시 트래픽에 별도의 할당량을 부여하려면 /v2/<group>/dependency_proxy/containers/ 아래의 컨테이너 이미지 매니페스트 및 blob 엔드포인트 전용 속도 제한을 활성화합니다. 이 제한은 인증된 요청에만 적용됩니다. GitLab은 인증되지 않은 의존성 프록시 요청에 대한 속도 제한은 제공하지 않습니다.

배포 토큰으로 인증하는 요청은 해당 배포 토큰에 집계되며, 각 배포 토큰은 자체 허용량을 가집니다. 클라이언트의 IP 주소에는 집계되지 않습니다.

다음 요청은 이 제한이 아니라 사용자별 또는 배포 토큰별 인증된 웹 요청 속도 제한에 집계됩니다.

• Docker 인증 요청 GET /v2.
• GitLab이 의존성 프록시 캐시에 이미지를 저장하기 위해 보내는 요청.

인증된 의존성 프록시 속도 제한을 활성화하려면 다음 단계를 수행합니다.

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.

2. 왼쪽 사이드바에서 Settings > Network를 선택합니다.

3. Dependency proxy rate limits를 펼칩니다.

4. Enable authenticated dependency proxy request rate limit을 선택합니다.

   • 선택 사항. Max authenticated dependency proxy requests per period per user 값을 변경합니다. 기본값은 1000 입니다.
   • 선택 사항. Authenticated dependency proxy rate limit period in seconds 값을 변경합니다. 기본값은 15 입니다.

이 제한이 비활성화되어 있는 동안에는 의존성 프록시 요청이 계속 인증된 웹 요청 속도 제한에 집계됩니다.

인증된 MCP 서버 요청 속도 제한 활성화#

GitLab MCP 서버에 대한 인증된 요청은 인증된 API 요청 속도 제한에 집계됩니다.

MCP 서버 트래픽에 제한을 추가하려면 POST /api/v4/mcp 엔드포인트에 대한 속도 제한을 활성화합니다. 이 제한은 인증된 API 속도 제한에 더해 적용되며, 둘 중 하나라도 초과하면 요청이 거부됩니다. 도구 호출만이 아니라 이 엔드포인트에 대한 모든 요청을 집계합니다. 이 제한은 인증된 요청에만 적용되며 기본적으로 비활성화되어 있습니다.

인증된 MCP 서버 속도 제한을 활성화하려면 다음 단계를 수행합니다.

1. 오른쪽 위 모서리에서 Admin을 선택합니다.

2. 왼쪽 사이드바에서 Settings > Network를 선택합니다.

3. GitLab MCP server rate limits를 확장합니다.

4. Enable authenticated MCP server request rate limit을 선택합니다.

   • 선택 사항. Max authenticated MCP server requests per period per user 값을 업데이트합니다. 기본값은 600입니다.
   • 선택 사항. Authenticated MCP server rate limit period in seconds 값을 업데이트합니다. 기본값은 60입니다.

사용자 정의 속도 제한 응답 사용#

속도 제한을 초과한 요청은 429 응답 코드와 평문 본문을 반환하며, 기본값은 Retry later 입니다.

사용자 정의 응답을 사용하려면 다음 단계를 수행합니다.

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > Network를 선택합니다.
3. User and IP rate limits를 펼칩니다.
4. Plain-text response to send to clients that hit a rate limit 텍스트 상자에 평문 응답 메시지를 입력합니다.

분당 project/:id/jobs에 대한 최대 인증 요청 수#

타임아웃을 줄이기 위해 project/:id/jobs 엔드포인트에는 인증된 사용자당 600회 호출이라는 기본 속도 제한이 있습니다.

최대 요청 수를 변경하려면 다음 단계를 수행합니다.

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > Network를 선택합니다.
3. User and IP rate limits를 펼칩니다.
4. Maximum authenticated requests to project/:id/jobs per minute 값을 변경합니다.

응답 헤더#

응답 헤더에는 모든 요청에 대한 속도 제한 정보가 포함됩니다. 이 헤더로 사용량을 미리 모니터링하고 요청 패턴을 조정하여 스로틀링을 피할 수 있습니다.

다중 속도 제한 시스템#

속도 제한은 서로 독립적인 두 시스템으로 적용됩니다.

• Rack::Attack 미들웨어 속도 제한: HTTP 계층에서 적용됩니다. 사용자별 인증된 API 요청이나 IP별 인증되지 않은 웹 요청이 여기에 해당합니다. 이 제한은 응답 헤더에 반영됩니다.
• 애플리케이션 속도 제한: 애플리케이션 수준에서 적용됩니다. 사용자별 이슈 생성이나 사용자별 프로젝트 내보내기가 여기에 해당합니다. 이 제한은 응답 헤더에 포함되지 않습니다.

하나의 요청이 두 종류의 속도 제한에 동시에 집계될 수 있습니다. 응답 헤더에는 가장 엄격한 Rack::Attack 속도 제한 상태만 표시됩니다.

예시#

API로 이슈를 생성하는 요청은 다음 제한에 집계됩니다.

• 인증된 API 요청 속도 제한(Rack::Attack). 응답 헤더에 포함됩니다.
• 이슈 생성 속도 제한(애플리케이션 수준). 응답 헤더에 포함되지 않습니다.

이슈 생성 제한을 초과하면 이전 응답 헤더가 인증된 API 요청이 충분히 남아 있다고 표시했더라도 429 응답이 반환됩니다.

모든 요청에 반환되는 헤더#

클라이언트가 속도 제한 상태를 추적할 수 있도록 다음 헤더가 모든 응답에 포함됩니다.

스로틀된 요청에 대한 추가 헤더#

클라이언트가 속도 제한을 초과하면(HTTP 상태 429) 다음 헤더가 추가로 포함됩니다.

HTTP 헤더를 사용하여 속도 제한 우회#

조직의 필요에 따라 속도 제한을 활성화하면서도 일부 요청은 속도 제한기를 우회하도록 할 수 있습니다.

속도 제한기를 우회해야 하는 요청에 사용자 정의 헤더를 표시하면 됩니다. 이 작업은 GitLab 앞단의 로드 밸런서나 리버스 프록시에서 수행해야 합니다. 예를 들면 다음과 같습니다.

1. 우회 헤더 이름을 정합니다. 예를 들어 Gitlab-Bypass-Rate-Limiting 입니다.
2. GitLab 속도 제한을 우회해야 하는 요청에 Gitlab-Bypass-Rate-Limiting: 1을 설정하도록 로드 밸런서를 구성합니다.
3. 로드 밸런서를 다음 중 하나로 구성합니다.
   • Gitlab-Bypass-Rate-Limiting을 삭제합니다.
   • 속도 제한을 적용해야 하는 모든 요청에는 Gitlab-Bypass-Rate-Limiting을 1 이외의 값으로 설정합니다.
4. 환경 변수 GITLAB_THROTTLE_BYPASS_HEADER를 설정합니다.
   • Linux 패키지 설치에서는 gitlab_rails['env']에 'GITLAB_THROTTLE_BYPASS_HEADER' => 'Gitlab-Bypass-Rate-Limiting'을 설정합니다.
   • 자체 컴파일 설치에서는 /etc/default/gitlab에 export GITLAB_THROTTLE_BYPASS_HEADER=Gitlab-Bypass-Rate-Limiting을 설정합니다.

로드 밸런서가 들어오는 모든 트래픽에서 우회 헤더를 삭제하거나 덮어쓰는 것이 중요합니다. 그렇지 않으면 사용자가 그 헤더를 설정해 GitLab 속도 제한기를 우회하지 않으리라고 신뢰해야 합니다.

우회는 헤더가 1로 설정된 경우에만 동작합니다.

우회 헤더 때문에 속도 제한기를 우회한 요청은 production_json.log에 "throttle_safelist":"throttle_bypass_header"로 표시됩니다.

우회 기능을 비활성화하려면 환경 변수 GITLAB_THROTTLE_BYPASS_HEADER를 설정하지 않거나 비워 둡니다.

특정 사용자가 인증된 요청 속도 제한을 우회하도록 허용#

앞에서 설명한 우회 헤더와 비슷하게, 특정 사용자 집합이 속도 제한기를 우회하도록 허용할 수 있습니다. 이는 인증된 요청에만 적용됩니다. 인증되지 않은 요청에서는 GitLab이 사용자가 누구인지 알 수 없기 때문입니다.

허용 목록은 GITLAB_THROTTLE_USER_ALLOWLIST 환경 변수에 쉼표로 구분한 사용자 ID 목록으로 구성합니다. 사용자 1, 53, 217이 인증된 요청 속도 제한기를 우회하도록 하려면 허용 목록 구성은 1,53,217 이 됩니다.

• Linux 패키지 설치에서는 gitlab_rails['env']에 'GITLAB_THROTTLE_USER_ALLOWLIST' => '1,53,217'을 설정합니다.
• 자체 컴파일 설치에서는 /etc/default/gitlab에 export GITLAB_THROTTLE_USER_ALLOWLIST=1,53,217을 설정합니다.

사용자 허용 목록 때문에 속도 제한기를 우회한 요청은 production_json.log에 "throttle_safelist":"throttle_user_allowlist"로 표시됩니다.

애플리케이션 시작 시 허용 목록이 auth.log에 기록됩니다.

적용하기 전에 스로틀 설정 시험 사용#

히스토리

• GitLab 19.5에서 LabKit 속도 제한기의 속도 제한 상태를 요청별 구조화 로그에 기록하는 기능이 도입되었습니다.

GITLAB_THROTTLE_DRY_RUN 환경 변수를 쉼표로 구분한 스로틀 이름 목록으로 설정하면 스로틀 설정을 시험해 볼 수 있습니다.

사용할 수 있는 이름은 다음과 같습니다.

• throttle_unauthenticated
  • GitLab 14.3에서 지원 중단. 대신 throttle_unauthenticated_api 또는 throttle_unauthenticated_web을 사용합니다. throttle_unauthenticated는 여전히 지원되며 두 가지를 모두 선택합니다.
• throttle_unauthenticated_api
• throttle_unauthenticated_web
• throttle_authenticated_api
• throttle_authenticated_web
• throttle_unauthenticated_protected_paths
• throttle_authenticated_protected_paths_api
• throttle_authenticated_protected_paths_web
• throttle_unauthenticated_packages_api
• throttle_authenticated_packages_api
• throttle_authenticated_git_lfs
• throttle_unauthenticated_files_api
• throttle_authenticated_files_api
• throttle_unauthenticated_deprecated_api
• throttle_authenticated_deprecated_api
• throttle_unauthenticated_git_http
• throttle_authenticated_git_http
• throttle_authenticated_mcp

예를 들어 GITLAB_THROTTLE_DRY_RUN='throttle_authenticated_web,throttle_authenticated_api'를 설정하면 보호되지 않은 경로에 대한 모든 인증된 요청의 스로틀을 시험해 볼 수 있습니다.

모든 스로틀에 시험 실행 모드를 적용하려면 변수를 *로 설정합니다.

시험 실행 모드에서 GitLab은 스로틀의 제한에 도달할 요청을 차단하지 않습니다. 이러한 요청은 평소와 같이 계속 처리됩니다. GitLab이 이러한 요청을 기록하는 위치는 요청을 평가하는 속도 제한기에 따라 다릅니다.

• 레거시 Rack::Attack 속도 제한기: 요청이 제한에 도달할 때 GitLab은 auth.log와 auth_json.log에 메시지를 기록합니다. 로그 메시지에는 track으로 설정된 env 필드가 포함됩니다. matched 필드에는 도달한 스로틀의 이름이 들어 있습니다.
• LabKit 속도 제한기: 이 이벤트에 대해 GitLab은 별도의 auth.log 또는 auth_json.log 메시지를 남기지 않습니다. 대신 GitLab은 production_json.log와 api_json.log를 포함한 요청별 구조화 로그의 rate_limit_state 필드에 속도 제한 상태를 추가합니다. 각 항목의 형식은 <limiter>:<rule>:<result>입니다. 시험 실행 모드에서 요청이 스로틀의 제한에 도달할 경우 결과는 log입니다 (예: 200 상태 코드를 반환하는 요청의 경우 ["rack_request:unauthenticated_api:log"]). 시험 실행 모드가 이 속도 제한기에서 동작하는지 확인하려면 auth.log의 env 필드가 아니라 rate_limit_state 필드를 확인합니다.

설정에서 속도 제한을 활성화하기 전에 환경 변수를 먼저 설정하는 것이 중요합니다. Admin 영역의 설정은 즉시 적용되지만, 환경 변수 설정은 모든 Puma 프로세스를 재시작해야 반영됩니다.

문제 해결#

실수로 관리자가 차단된 후 스로틀 비활성화#

여러 사용자가 동일한 프록시나 네트워크 게이트웨이로 GitLab에 접속하는 경우, 속도 제한이 너무 낮으면 관리자까지 함께 차단될 수 있습니다. GitLab이 스로틀링을 유발한 요청과 동일한 IP를 관리자도 사용한다고 보기 때문입니다.

관리자는 Rails 콘솔을 사용하여 GITLAB_THROTTLE_DRY_RUN 변수에 나열된 것과 동일한 제한을 비활성화할 수 있습니다. 예를 들면 다음과 같습니다.

Gitlab::CurrentSettings.update!(throttle_authenticated_web_enabled: false)

이 예시에서 throttle_authenticated_web 매개변수에는 _enabled 이름 접미사가 붙습니다.

제한에 숫자 값을 설정하려면 _enabled 이름 접미사를 _period_in_seconds 및 _requests_per_period 접미사로 바꿉니다.