조직 이니셔티브는 GitLab.com과 GitLab Self-Managed 간의 기능 동등성(feature parity) 달성에 초점을 맞추고 있습니다.

현재 단계 (FY27-Q1 및 FY27-Q2): 기능 동등성#

현재 개발 초점은 조직에 대한 기능 동등성을 달성하는 것입니다. 이는 조직 내 그룹에서 기존 기능이 작동하여, 조직으로 이전하는 사용자가 기능을 잃지 않도록 보장하는 것을 의미합니다.

조직은 아직 새로운 기능을 위한 준비가 되지 않았습니다. 새로운 기능은 계속해서 다음을 대상으로 해야 합니다:

• GitLab.com: 최상위 그룹

• GitLab Self-Managed: 인스턴스 레벨

조직에서 새로운 기능을 개발하거나 기존 기능을 최상위 그룹에서 조직으로 마이그레이션하는 방법에 대한 가이드는 향후 제공될 예정입니다. 비공식적으로 논의하고 싶다면 Slack(#g_organizations)에서 팀에 문의하세요.

조직 구현을 위한 사용 가능 및 계획된 지원#

Organizations 팀은 다음에 대한 지원을 자동으로 포함하는 변경 사항을 구현하고 있습니다:

• 애플리케이션 레벨 조직 격리: Organization Scoping을 처리하는 ActiveRecord 확장 기능이 제공될 예정입니다. 이는 FY27-Q2 초반에 사용 가능하도록 잠정적으로 계획되어 있습니다.

• Sidekiq: organization_id를 Sidekiq worker 파라미터에 전달할 필요가 없습니다. Sidekiq worker는 스케줄링 컨텍스트에서 Current Organization을 상속합니다.

• 이벤트 / 로깅: User, Project, Namespace와 유사하게 Organization이 포함될 예정입니다.

• 라우팅: 조직 기반 URL(/o/<organization> 접두사)의 활성화/비활성화가 가능해질 예정입니다.

• 테스트에서의 조직 사용 가능성

특별한 이유가 없는 한, 팀에서 이를 직접 구현할 필요가 없습니다.

데이터베이스 테이블 설계#

샤딩 가이드라인을 참조하세요.

Current.organization 사용#

Current.organization이 요청 레이어에서 올바르게 설정되어 있는지 확인하세요. 자동으로 설정되지 않는 경우에는 아래 단계를 따르세요.

Current.organization이 설정되면 ActiveRecord 확장 기능(gitlab-database-data_isolation)이 이 컨텍스트를 사용하여 해당 조직으로 쿼리를 조건부로 범위 지정합니다.

Current.organization을 사용할 수 있는 곳#

Current.organization은 다음 컨텍스트에서 사용할 수 있습니다. 일부는 자동으로 설정되고, 나머지는 set_current_organization을 명시적으로 호출해야 합니다.

자동 설정 (플랫폼 전체):

• 컨트롤러 — ApplicationController에는 모든 요청에 대해 실행되는 before_action :set_current_organization이 포함되어 있습니다.

• GraphQL — GraphqlController는 ApplicationController를 상속하므로 동일한 before_action이 자동으로 적용됩니다.

• Sidekiq — job이 큐에 추가될 때 캡처된 조직 컨텍스트에서 설정됩니다.

개발자 설정 필요:

• Grape API 엔드포인트 — Current.organization은 자동으로 설정되지 않습니다. 이것이 필요한 각 API 클래스의 before 블록에서 set_current_organization 헬퍼를 호출하세요:

before do
  authenticate_non_get!
  set_current_organization
end

조직 컨텍스트 전달#

Current.organization이 필요한 애플리케이션 로직이 있다면, 요청 레이어에서 전달해야 합니다:

# In controllers
def create
  @group = Groups::CreateService.new(
    current_user,
    group_params.with_defaults(organization_id: Current.organization.id)
  ).execute
end

조직으로 쿼리 범위 지정#

조직의 격리 상태에 따라 Organization Scoping을 제공하는 ActiveRecord 확장 기능(gitlab-database-data_isolation)이 제공될 예정입니다.

조직 라우팅#

조직 범위 라우트는 /o/:organization_path/ 패턴을 사용합니다(예: /o/my-org/projects). projects_path와 같은 일반적이고 범위 지정되지 않은 Rails URL 헬퍼를 항상 사용하세요. GitLab이 Current.organization을 기반으로 자동으로 라우팅합니다. 이를 통해 조직 범위 라우트와 전역 라우트 간의 전환이 자동으로 이루어집니다.

# Recommended: Use global route helpers
projects_path                    # Automatically becomes /o/my-org/projects if Current.organization is set
project_issues_path(@project)    # Automatically becomes /o/my-org/namespace/project/-/issues

작동 방식#

조직 URL 헬퍼 시스템은 Routing::OrganizationsHelper::MappedHelpers에 구현되어 있습니다. 라우트가 로드될 때 시스템은:

• 모든 라우트를 스캔하여 조직 범위 라우트(/o/:organization_path를 포함하는 라우트)를 찾습니다.

• 전역 라우트 이름과 조직 라우트 이름 간의 매핑을 생성합니다.

• 표준 Rails URL 헬퍼(projects_path, groups_url 등)를 재정의하여 조직을 인식하도록 합니다.

• Current.organization이 존재하고 조직에 범위 지정된 경로가 활성화된 경우, 헬퍼가 자동으로 조직 범위 버전의 라우트를 사용합니다.

• 원래의 root_path와 root_url을 unscoped_root_path와 unscoped_root_url로 보존합니다.

이 접근 방식은 요청 라이프사이클 전반에 걸쳐 조직 컨텍스트를 보존합니다. 예를 들어, GET /o/my-org/projects는 Current.organization을 통해 조직 컨텍스트를 사용할 수 있는 상태로 /projects와 동일한 ProjectsController#index로 라우팅됩니다.

명시적 조직 헬퍼는 Current.organization과 다른 특정 조직에 대한 URL을 생성해야 하거나, Current.organization을 사용할 수 없는 요청 레이어 외부(서비스, worker, Rake 태스크)에서 작업할 때만 사용하세요:

# Explicit organization helpers
organization_projects_path(organization_path: 'my-org')           # /o/my-org/projects
organization_project_issues_path(@project, organization_path: 'my-org')  # /o/my-org/namespace/project/-/issues

아직 조직 범위가 지정되지 않은 라우트#

일부 라우트는 현재 조직 범위에서 사용할 수 없습니다:

• Devise OmniAuth 콜백 - Devise는 동적 세그먼트 하위에서 OmniAuth 콜백 범위 지정을 지원하지 않으므로, 전역 레벨에 유지됩니다.

• API 라우트 - API 엔드포인트는 아직 조직 범위가 지정되지 않았습니다.

조직 격리 테스트#

조직을 테스트하려면 다음 기능 플래그를 활성화하세요:

• ui_for_organizations

• organization_switching

기능을 조직 인식으로 만들 때, 교차 조직 데이터 누출이 발생할 수 있는 영역에 특별히 주의를 기울이세요. 예시:

• 그룹 및 프로젝트 멤버 초대

• 이슈, 머지 리퀘스트, 댓글에서의 사용자 언급

• 사용자 검색 및 자동 완성 결과

• 조직 간 이슈, 머지 리퀘스트, 마일스톤, 라벨 참조

• 현재 조직으로 결과를 범위 지정하는 Finder 클래스

개발 환경에서 수동 테스트를 위한 유용한 규칙은 명확한 이름의 조직을 생성하고 관련된 모든 데이터에 접두사를 붙이는 것입니다. 이를 통해 다른 조직의 데이터가 우발적으로 노출되었는지 시각적으로 쉽게 확인할 수 있습니다.

Secret Tanuki라는 이름의 조직을 생성하고 관련된 모든 데이터에 이 이름을 접두사로 붙이세요:

• 조직: Secret Tanuki

• 사용자: Secret Tanuki User Bob, Secret Tanuki User Alice

• 프로젝트: Secret Tanuki Project X, Secret Tanuki Project Y

• 이슈: Secret Tanuki Issue #42, Secret Tanuki Issue #99

• 그룹: Secret Tanuki Group

• 머지 리퀘스트: Secret Tanuki MR: Add feature

데이터 누출을 테스트할 때 UI 또는 API 응답에서 Secret Tanuki를 검색하세요. 있어서는 안 될 곳에서 발견된다면, 교차 조직 데이터 누출을 발견한 것입니다. 이는 특히 다음과 같은 경우에 유용합니다:

• 검색 및 자동 완성 기능 테스트

• 멤버 초대가 조직 간에 누출되지 않는지 확인

• 언급 및 참조가 올바르게 범위 지정되는지 확인

• 의도치 않은 데이터 노출에 대한 API 응답 검토

자동화 테스트#

자동화 테스트 전략에 대해서는 조직을 사용한 테스트를 참조하세요.

프론트엔드 가이드라인#

REST API 및 GraphQL 요청#

REST API 및 GraphQL 요청에 현재 조직 컨텍스트를 제공하는 데 추가적인 인수가 필요하지 않습니다. 백그라운드에서 현재 조직은 axios_utils.js#L15 및 graphql.js#L183에서 X-GitLab-Organization-ID 헤더를 통해 전달됩니다.

URL#

조직 라우팅을 지원하지 않으므로 프론트엔드에서 URL을 하드코딩하거나 구성하지 마세요. 프론트엔드에서 URL을 생성하는 방법에 대한 가이드라인은 GitLab의 URL을 참조하세요.

현재 조직에 접근#

현재 조직 컨텍스트는 window.gon.current_organization을 통해 프론트엔드에서 사용할 수 있습니다. 백그라운드에서 이는 gon_helper.rb#L69에서 프론트엔드에 노출됩니다.

관련 항목#

• 샤딩 가이드라인

• 조직 사용자 문서

• 조직을 사용한 테스트

• 그룹 및 프로젝트 통합 아키텍처 문서