기능 플래그를 사용하면 애플리케이션의 새 기능을 작은 단위로 나누어 프로덕션에 배포할 수 있습니다. 사용자 하위 집합을 대상으로 기능을 켜고 끌 수 있어 지속적 전달(Continuous Delivery)을 달성하는 데 도움이 됩니다. 기능 플래그는 위험을 줄이고 통제된 테스트를 수행하며 기능 제공을 고객 출시와 분리할 수 있게 해줍니다.

GitLab의 전체 기능 플래그 목록도 확인할 수 있습니다.

실제로 동작하는 기능 플래그 예시는 기능 플래그로 위험 제거하기를 참고합니다.

클릭으로 진행하는 데모는 기능 플래그를 참고합니다.

기능 플래그 사용#

GitLab은 기능 플래그를 위해 Unleash 호환 API를 제공합니다.

GitLab에서 플래그를 활성화하거나 비활성화하면 애플리케이션이 어떤 기능을 활성화하거나 비활성화할지 결정할 수 있습니다.

GitLab에서 기능 플래그를 생성하고, 애플리케이션에서 API를 사용해 기능 플래그 목록과 상태를 가져올 수 있습니다. 애플리케이션이 GitLab과 통신하도록 구성되어야 하므로, 호환되는 클라이언트 라이브러리를 사용해 애플리케이션에 기능 플래그를 통합하는 작업은 개발자에게 달려 있습니다.

기능 플래그 생성#

기능 플래그를 생성하고 활성화하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Feature flags를 선택합니다.
3. New feature flag를 선택합니다.
4. 문자로 시작하고 소문자, 숫자, 밑줄(_), 대시(-)만 포함하며 대시(-)나 밑줄(_)로 끝나지 않는 이름을 입력합니다.
5. 선택 사항. 설명을 입력합니다(최대 255자).
6. 플래그가 적용되는 방식을 정의하기 위해 기능 플래그 Strategies를 추가합니다. 각 전략에는 Type(기본값은 All users)과 Environments(기본값은 모든 환경)를 포함합니다.
7. Create feature flag를 선택합니다.

이러한 설정을 변경하려면 목록에서 원하는 기능 플래그 옆의 Edit (✏️) 을 선택합니다.

기능 플래그를 관리할 수 있는 사용자 제한#

히스토리

• GitLab 19.4에서 feature_flag_management_permissions라는 이름의 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.

기본적으로 Developer 권한 이상을 가진 프로젝트 멤버는 누구나 기능 플래그를 생성, 업데이트, 전환, 삭제할 수 있습니다. 변경 통제 또는 컴플라이언스 요구 사항을 충족하기 위해 이 기준을 높일 수 있습니다.

사전 요구 사항:

• 프로젝트에 대해 Maintainer 권한 이상이 있어야 합니다.
• 최소 권한을 owner 또는 no_one_allowed에서 다른 값으로 변경하려면 프로젝트에 대해 Owner 권한이 있어야 합니다.

최소 권한을 설정하려면:

1. 왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. Settings > CI/CD를 선택합니다.
3. Feature flags를 확장합니다.
4. 권한을 선택합니다.
5. Save changes를 선택합니다.

또는 다음 기능 플래그 설정 업데이트 REST 엔드포인트로 최소 권한을 설정할 수 있습니다:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/feature_flags_settings?minimum_role=maintainer"

또는 프로젝트 업데이트 엔드포인트의 feature_flags_minimum_role 속성으로 설정하여 한 번의 요청으로 여러 프로젝트 설정을 구성할 수도 있습니다.

이 설정에는 다음 값 중 하나를 사용할 수 있습니다:

기준보다 낮은 권한을 가진 멤버는 Developer 권한 이상이 있으면 기능 플래그와 그 상태를 볼 수는 있지만, 생성, 업데이트, 전환, 삭제는 할 수 없습니다. 또한 사용자 목록이 플래그가 적용되는 사용자를 변경하므로 사용자 목록을 생성, 편집, 삭제할 수도 없습니다.

최대 기능 플래그 수#

GitLab Self-Managed에서 프로젝트당 최대 기능 플래그 수는 200개입니다. GitLab.com에서는 최대 수가 티어에 따라 결정됩니다:

기능 플래그 전략#

전략을 여러 번 정의하지 않고도 여러 환경에 걸쳐 기능 플래그 전략을 적용할 수 있습니다.

GitLab 기능 플래그는 Unleash를 기반으로 합니다. Unleash에는 세밀한 기능 플래그 제어를 위한 전략이 있습니다. GitLab 기능 플래그는 여러 전략을 가질 수 있으며, 지원되는 전략은 다음과 같습니다:

• 모든 사용자
• 사용자 비율
• 사용자 ID
• 사용자 목록

전략은 기능 플래그를 생성할 때 추가하거나, 생성 후 Deploy > Feature flags 로 이동해 기존 기능 플래그를 편집하면서 Edit (✏️)을 선택해 추가할 수 있습니다.

모든 사용자#

모든 사용자에 대해 기능을 활성화합니다. 표준(default) Unleash 활성화 전략을 사용합니다.

비율 롤아웃#

동작의 일관성을 구성할 수 있는 상태로 페이지 뷰의 일정 비율에 대해 기능을 활성화합니다. 이 일관성은 스티키니스(stickiness)라고도 합니다. 점진적 롤아웃(flexibleRollout) Unleash 활성화 전략을 사용합니다.

다음을 기준으로 일관성을 구성할 수 있습니다:

• User IDs: 세션 ID를 무시하고 각 사용자 ID가 일관된 동작을 갖습니다.
• Session IDs: 사용자 ID를 무시하고 각 세션 ID가 일관된 동작을 갖습니다.
• Random: 일관된 동작이 보장되지 않습니다. 선택한 비율의 페이지 뷰에 대해 무작위로 기능이 활성화됩니다. 사용자 ID와 세션 ID는 무시됩니다.
• Available ID: 사용자의 상태를 기준으로 일관된 동작을 시도합니다:
  • 사용자가 로그인한 경우, 사용자 ID를 기준으로 동작을 일관되게 합니다.
  • 사용자가 익명인 경우, 세션 ID를 기준으로 동작을 일관되게 합니다.
  • 사용자 ID나 세션 ID가 없는 경우, 선택한 비율의 페이지 뷰에 대해 무작위로 기능이 활성화됩니다.

예를 들어 Available ID를 기준으로 값을 15%로 설정하면 페이지 뷰의 15%에 대해 기능이 활성화됩니다. 인증된 사용자의 경우 이는 사용자 ID를 기준으로 합니다. 세션 ID가 있는 익명 사용자는 사용자 ID가 없으므로 대신 세션 ID를 기준으로 합니다. 그리고 세션 ID도 제공되지 않으면 무작위 방식으로 대체됩니다.

롤아웃 비율은 0%에서 100% 사이로 설정할 수 있습니다.

사용자 ID를 기준으로 일관성을 선택하면 사용자 비율 롤아웃과 동일하게 동작합니다.

사용자 비율#

인증된 사용자의 일정 비율에 대해 기능을 활성화합니다. Unleash 활성화 전략 gradualRolloutUserId를 사용합니다.

예를 들어 값을 15%로 설정하면 인증된 사용자의 15%에 대해 기능이 활성화됩니다.

롤아웃 비율은 0%에서 100% 사이로 설정할 수 있습니다.

스티키니스(동일한 사용자에 대한 일관된 애플리케이션 동작)는 인증된 사용자에게는 보장되지만 익명 사용자에게는 보장되지 않습니다.

User IDs를 기준으로 일관성을 설정한 비율 롤아웃도 동일하게 동작합니다. 비율 롤아웃이 사용자 비율보다 더 유연하므로 비율 롤아웃을 사용해야 합니다.

사용자 ID#

대상 사용자 목록에 대해 기능을 활성화합니다. Unleash UserIDs(userWithId) 활성화 전략으로 구현됩니다.

사용자 ID는 쉼표로 구분된 값 목록으로 입력합니다(예: user@example.com, user2@example.com 또는 username1,username2,username3 등). 사용자 ID는 애플리케이션 사용자를 식별하는 값이며, GitLab 사용자일 필요는 없습니다.

사용자 목록#

기능 플래그 UI에서 생성했거나 기능 플래그 사용자 목록 API로 생성한 사용자 목록에 대해 기능을 활성화합니다. 사용자 ID와 마찬가지로 Unleash UsersIDs(userWithId) 활성화 전략을 사용합니다.

특정 사용자에 대해서만 기능을 비활성화할 수는 없지만, 사용자 목록에 대해 기능을 활성화하면 비슷한 결과를 얻을 수 있습니다.

예를 들면:

• Full-user-list = User1A, User1B, User2A, User2B, User3A, User3B, ...
• Full-user-list-excluding-B-users = User1A, User2A, User3A, ...

사용자 목록 생성#

사용자 목록을 생성하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Feature flags를 선택합니다.
3. View user lists를 선택합니다
4. New user list를 선택합니다.
5. 목록의 이름을 입력합니다.
6. Create를 선택합니다.

목록 옆의 Edit (✏️)을 선택하면 목록의 사용자 ID를 볼 수 있습니다. 목록을 보는 동안 Edit (✏️)을 선택하면 이름을 바꿀 수 있습니다.

사용자 목록에 사용자 추가#

사용자 목록에 사용자를 추가하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Feature flags를 선택합니다.
3. 사용자를 추가할 목록 옆의 Edit (✏️)을 선택합니다.
4. Add Users를 선택합니다.
5. 사용자 ID를 쉼표로 구분된 값 목록으로 입력합니다. 예를 들어 user@example.com, user2@example.com 또는 username1,username2,username3 등입니다.
6. Add를 선택합니다.

사용자 목록에서 사용자 제거#

사용자 목록에서 사용자를 제거하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Feature flags를 선택합니다.
3. 변경할 목록 옆의 Edit (✏️)을 선택합니다.
4. 제거할 ID 옆의 Remove ([remove])을 선택합니다.

코드 참조 검색#

정리 작업 중 코드에서 기능 플래그를 제거하려면, 프로젝트 내에서 해당 플래그에 대한 참조를 찾습니다.

기능 플래그의 코드 참조를 검색하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Feature flags를 선택합니다.
3. 제거할 기능 플래그를 편집합니다.
4. More actions (⋮)을 선택합니다.
5. Search code references를 선택합니다.

특정 환경에서 기능 플래그 비활성화#

특정 환경에서 기능 플래그를 비활성화하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Feature flags를 선택합니다.
3. 비활성화할 기능 플래그에서 Edit (✏️)을 선택합니다.
4. 플래그를 비활성화하려면:
   • 플래그가 적용되는 각 전략에서 Environments 아래의 환경을 삭제합니다.
5. Save changes를 선택합니다.

모든 환경에서 기능 플래그 비활성화#

모든 환경에서 기능 플래그를 비활성화하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Feature flags를 선택합니다.
3. 비활성화할 기능 플래그에서 Status 토글을 Disabled로 밉니다.

기능 플래그는 Disabled 탭에 표시됩니다.

애플리케이션에 기능 플래그 통합#

애플리케이션에서 기능 플래그를 사용하려면 GitLab에서 액세스 자격 증명을 가져옵니다. 그런 다음 클라이언트 라이브러리로 애플리케이션을 준비합니다.

액세스 자격 증명 가져오기#

애플리케이션이 GitLab과 통신하는 데 필요한 액세스 자격 증명을 가져오려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Feature flags를 선택합니다.
3. Configure를 선택하면 다음을 확인할 수 있습니다:

   • API URL: 클라이언트(애플리케이션)가 기능 플래그 목록을 가져오기 위해 연결하는 URL입니다.

   • Instance ID: 기능 플래그 조회를 인증하는 고유 토큰입니다.

   • Application name: 애플리케이션 자체의 이름이 아니라 애플리케이션이 실행되는 환경의 이름입니다.

     예를 들어 애플리케이션이 프로덕션 서버에서 실행되는 경우 Application name은 production 등이 될 수 있습니다. 이 값은 환경 스펙 평가에 사용됩니다.

이 필드들의 의미는 시간이 지나면서 바뀔 수 있습니다. 예를 들어 Instance ID는 Environment에 할당된 단일 토큰이거나 여러 토큰일 수 있습니다. 또한 Application name은 실행 환경 대신 애플리케이션 버전을 나타낼 수도 있습니다.

클라이언트 라이브러리 선택#

GitLab은 Unleash 클라이언트와 호환되는 단일 백엔드를 구현합니다.

Unleash 클라이언트를 사용하면 개발자는 애플리케이션 코드에서 플래그의 기본값을 정의할 수 있습니다. 각 기능 플래그 평가는 제공된 구성 파일에 플래그가 없을 때의 원하는 결과를 표현할 수 있습니다.

Unleash는 현재 다양한 언어와 프레임워크를 위한 여러 SDK를 제공합니다.

기능 플래그 API 정보#

API 관련 내용은 다음을 참고합니다:

• 기능 플래그 API
• 기능 플래그 사용자 목록 API

Go 애플리케이션 예시#

Go 애플리케이션에 기능 플래그를 통합하는 방법의 예시입니다:

package main

import (
    "io"
    "log"
    "net/http"

    "github.com/Unleash/unleash-client-go/v3"
)

type metricsInterface struct {
}

func init() {
    unleash.Initialize(
        unleash.WithUrl("https://gitlab.com/api/v4/feature_flags/unleash/42"),
        unleash.WithInstanceId("29QmjsW6KngPR5JNPMWx"),
        unleash.WithAppName("production"), // Set to the running environment of your application
        unleash.WithListener(&metricsInterface{}),
    )
}

func helloServer(w http.ResponseWriter, req *http.Request) {
    if unleash.IsEnabled("my_feature_name") {
        io.WriteString(w, "Feature enabled\n")
    } else {
        io.WriteString(w, "hello, world!\n")
    }
}

func main() {
    http.HandleFunc("/", helloServer)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

Ruby 애플리케이션 예시#

Ruby 애플리케이션에 기능 플래그를 통합하는 방법의 예시입니다.

Unleash 클라이언트에는 Percent rollout (logged in users) 롤아웃 전략이나 Target Users 목록과 함께 사용할 사용자 ID가 제공됩니다.

#!/usr/bin/env ruby

require 'unleash'
require 'unleash/context'

unleash = Unleash::Client.new({
  url: 'http://gitlab.com/api/v4/feature_flags/unleash/42',
  app_name: 'production', # Set to the running environment of your application
  instance_id: '29QmjsW6KngPR5JNPMWx'
})

unleash_context = Unleash::Context.new
# Replace "123" with the ID of an authenticated user.
# The context's user ID must be a string:
# https://unleash.github.io/docs/unleash_context
unleash_context.user_id = "123"

if unleash.is_enabled?("my_feature_name", unleash_context)
  puts "Feature enabled"
else
  puts "hello, world!"
end

Unleash Proxy 예시(폐기됨)#

Unleash Proxy 버전 0.2부터 프록시가 기능 플래그와 호환됩니다.

GitLab.com의 프로덕션에서는 Unleash Proxy를 사용해야 합니다. 자세한 내용은 성능 참고 사항을 참고합니다.

프로젝트의 기능 플래그에 연결하는 Docker 컨테이너를 실행하려면 다음 명령을 실행합니다:

docker run \
  -e UNLEASH_PROXY_SECRETS=<secret> \
  -e UNLEASH_URL=<project feature flags URL> \
  -e UNLEASH_INSTANCE_ID=<project feature flags instance ID> \
  -e UNLEASH_APP_NAME=<project environment> \
  -e UNLEASH_API_TOKEN=<tokenNotUsed> \
  -p 3000:3000 \
  unleashorg/unleash-proxy

이 프록시 서버는 서버와 클라이언트 사이에 위치합니다. 클라이언트 그룹을 대신해 서버에 요청을 보내므로 아웃바운드 요청 수를 크게 줄일 수 있습니다. 그래도 429 응답을 받는다면 Unleash Proxy의 UNLEASH_FETCH_INTERVAL 값을 늘립니다.

Unleash Proxy를 사용할 때는 각 프록시 인스턴스가 UNLEASH_APP_NAME에 지정된 환경에 대해서만 플래그를 요청할 수 있다는 제약이 있습니다. 프록시는 클라이언트를 대신해 이 값을 GitLab에 전달하므로, 클라이언트는 이를 재정의할 수 없습니다.

기능 플래그 관련 이슈#

관련 이슈를 기능 플래그에 링크할 수 있습니다. 기능 플래그의 Linked issues 섹션에서 + 버튼을 선택하고 이슈 참조 번호나 이슈의 전체 URL을 입력합니다. 그러면 해당 이슈가 연결된 기능 플래그에 나타나고, 반대로도 나타납니다.

이 기능은 연결된 이슈 기능과 유사합니다.

성능 요인#

GitLab 기능 플래그는 모든 애플리케이션에서 사용할 수 있습니다. 대규모 애플리케이션에는 고급 구성이 필요할 수 있습니다. 이 섹션에서는 이 기능을 사용하기 전에 조직에서 확인해야 할 사항을 파악하는 데 도움이 되도록 성능 요인을 설명합니다. 자세한 내용은 기능 플래그 사용을 참고합니다.

애플리케이션 노드에서 지원되는 최대 클라이언트 수#

GitLab은 속도 제한에 도달할 때까지 가능한 한 많은 클라이언트 요청을 수락합니다. 기능 플래그 API는 Unauthenticated traffic으로 간주되며 소스 IP 주소별로 제한됩니다. GitLab.com에 대해서는 GitLab.com 관련 제한을 참고합니다.

속도 제한은 소스 IP별로 적용되므로, 공유 송신 주소 뒤에 있는 모든 클라이언트는 그 주소에서 나오는 다른 모든 GitLab.com 트래픽과 함께 하나의 할당량을 사용합니다.

폴링 속도는 SDK에서 구성할 수 있습니다. 모든 클라이언트가 동일한 IP에서 요청한다고 가정하면:

• 분당 1회 요청 시 약 500개의 클라이언트를 지원합니다(8 RPS).
• 15초당 1회 요청 시 약 125개의 클라이언트를 지원합니다.

사용 가능한 처리량을 늘리려면 클라이언트를 여러 송신 주소에 분산합니다. 제한이 소스 IP별로 적용되므로 애플리케이션을 변경할 필요가 없습니다.

아웃바운드 요청량을 줄여야 하는 애플리케이션에서는 Unleash Proxy가 클라이언트와 GitLab 사이에 위치합니다. 클라이언트 그룹을 대신해 요청을 보내므로 많은 클라이언트 측 평가가 소수의 아웃바운드 호출로 합쳐집니다. 프록시를 실행하는데도 429 응답을 받는다면 프록시의 UNLEASH_FETCH_INTERVAL 값을 늘립니다.

Unleash Proxy는 업스트림에서 폐기되었으며 2026년 11월 26일에 계획된 지원 종료(EOL)에 도달합니다. 그 이후에는 보안 릴리스를 포함해 더 이상의 릴리스가 계획되어 있지 않습니다. GitLab 기능 플래그 API에서는 계속 작동하며, 그렇게 작동하는 것으로 알려진 유일한 구성 요소로 남아 있습니다.

네트워크 오류로부터 복구#

일반적으로 Unleash 클라이언트에는 서버가 오류 코드를 반환할 때를 위한 폴백 메커니즘이 있습니다. 예를 들어 unleash-ruby-client는 로컬 백업에서 플래그 데이터를 읽어 애플리케이션이 현재 상태를 유지하며 계속 실행될 수 있게 합니다.

자세한 내용은 SDK 프로젝트의 문서를 참고합니다.

GitLab Self-Managed#

기능 측면에서는 차이가 없습니다. GitLab.com과 GitLab Self-Managed 모두 동일하게 동작합니다.

확장성 측면에서는 GitLab 인스턴스의 사양에 따라 달라집니다. GitLab.com은 많은 동시 요청을 처리하기 위해 고도로 확장된 아키텍처를 사용합니다.

다만 참조 아키텍처 기준으로 용량이 부족한 GitLab Self-Managed 인스턴스는 비슷한 성능을 제공하지 못하며, 기능 플래그 트래픽으로 과부하가 걸릴 수도 있습니다. GitLab 사용자 수에 더해 배포한 애플리케이션의 사용자 수도 함께 고려합니다.