이 문서는 기여자가 GitLab에 애플리케이션 설정을 추가하기 위한 개발 가이드를 제공합니다.

애플리케이션 설정은 application_settings 테이블에 저장됩니다. 각 설정은 자체 칼럼을 가지며 행은 하나만 있어야 합니다.

GitLab Duo 관련 애플리케이션 설정은 다른 테이블에 저장됩니다.

새 애플리케이션 설정 추가#

우선, 애플리케이션 설정을 추가해야 하는지 여부를 결정해야 합니다. 새 설정을 추가할 때는 구성 원칙을 고려하세요.

application_settings 테이블이 지나치게 넓어지는 것을 방지하기 위해 관련 애플리케이션 설정을 단일 JSONB 칼럼에 저장하는 것을 권장합니다. 또한, 기존 칼럼에 새 설정을 추가하는 경우에는 데이터베이스 검토가 필요 없으므로 시간을 절약할 수 있습니다.

새 설정을 추가하려면 다음을 수행해야 합니다:

• 새 설정을 저장하는 데 사용할 수 있는 기존 JSONB 칼럼이 있는지 확인합니다.

• 기존 JSON 칼럼이 있는 경우:

ApplicationSetting 모델의 rate_limits와 같이 JSONB 칼럼에 새 설정을 추가합니다.

• rate_limits 검증기와 같이 해당 칼럼의 JSON 스키마 검증기를 업데이트합니다.

• 사용할 수 있는 기존 JSON 칼럼이 없는 경우:

참고를 위해 이 머지 리퀘스트를 참조하여 application_settings 테이블에 새 JSON 칼럼을 추가합니다.

• 칼럼이 항상 해시를 저장하도록 보장하는 제약 조건을 추가합니다. 참고를 위해 이 머지 리퀘스트를 참조하세요.

• 기존의 관련 칼럼을 새로 생성된 JSONB 칼럼으로 이동하기 위한 후속 이슈를 생성합니다. 데이터베이스 칼럼을 JSONB 칼럼으로 마이그레이션하는 프로세스를 따르세요.

• 표시 가능한 속성 목록에 새 설정을 추가합니다.

• 설정에 기본값이 있는 경우, ApplicationSettingImplementation#defaults에 새 설정을 추가합니다.

• 설정에 기본값이 있는 경우, 기본값에 대한 테스트를 추가합니다.

• ApplicationSetting 모델에 새 필드에 대한 유효성 검사를 추가합니다.

• 유효성 검사 및 기본값에 대한 모델 테스트를 추가합니다.

• 적절한 뷰 파일을 찾거나 새로 만들어 새 설정에 폼 필드를 추가합니다.

• API 문서를 업데이트합니다. 애플리케이션 설정은 REST API에서 자동으로 사용 가능하게 됩니다.

• scripts/cells/application-settings-analysis.rb 스크립트를 실행하여 config/application_setting_columns/*.yml에 정의 YAML 파일을 생성하고, db/structure.sql 및 API 문서를 기반으로 cells/application_settings_analysis 문서 파일을 업데이트합니다. 정의 파일이 생성된 후에는 clusterwide 키를 true 또는 false로 설정해야 합니다. clusterwide: true로 설정하면 속성 값이 리더 셀에서 다른 셀로 복사됩니다. 이는 Cells 아키텍처 맥락에서 적용됩니다. 대부분의 경우 clusterwide: false가 권장됩니다.

데이터베이스 마이그레이션 예시#

class AddNewSetting < Gitlab::Database::Migration[2.1]
  disable_ddl_transaction!

  def up
    with_lock_retries do
      add_column :application_settings, :new_setting, :text, if_not_exists: true
    end

    add_text_limit :application_settings, :new_setting, 255
  end

  def down
    with_lock_retries do
      remove_column :application_settings, :new_setting, if_exists: true
    end
  end
end

모델 유효성 검사 예시#

validates :new_setting,
          length: { maximum: 255, message: N_('is too long (maximum is %{count} characters)') },
          allow_blank: true

데이터베이스 칼럼을 JSONB 칼럼으로 마이그레이션#

칼럼을 JSONB로 마이그레이션하려면 JSONB 접근자 아래에 새 설정을 추가합니다.

JSONB 설정 추가#

• 새 애플리케이션 설정 추가 프로세스를 따릅니다.

• 일관성을 유지하기 위해 기존 칼럼과 동일한 이름을 사용합니다.

• 전환 기간 동안 Rails는 기존 데이터베이스 칼럼과 새 JSONB 칼럼 아래의 필드 양쪽에 동일한 정보를 씁니다. 이는 데이터 일관성을 보장하고 다운타임을 방지합니다.

필수 정리 단계#

원본 칼럼을 제거하려면 칼럼 삭제 프로세스를 반드시 따라야 합니다. 이는 다음을 포함하는 필수 다중 마일스톤 프로세스입니다:

• 칼럼 무시(ignore) 처리.

• 칼럼 삭제.

• 무시 규칙 제거.

모델에서 무시하기 전에 원본 칼럼을 삭제하면 제로 다운타임 마이그레이션에 문제가 발생할 수 있습니다.

기본값#

jsonb_accessor 기본값을 가진 JSONB 칼럼으로 설정을 마이그레이션할 때는 JSONB 접근자가 defaults 메서드보다 우선하므로 ApplicationSettingImplementation.defaults에서 해당 설정을 제거합니다.

GitLab Duo 관련 설정 추가#

application_settings 테이블에는 여러 인스턴스 전체 GitLab Duo 설정이 있습니다. 여기에는 duo_features_enabled(boolean), duo_workflow(jsonb), duo_chat(jsonb)이 포함됩니다.

어느 시점에서, 새 인스턴스 전체 설정을 다른 테이블에 추가하는 것이 더 간단하다는 것을 깨달았습니다. 앞으로 새 GitLab Duo 관련 인스턴스 전체 설정은 ai_settings 테이블에 추가해야 합니다.

그룹 또는 프로젝트 수준의 GitLab Duo 설정에는 namespace_ai_settings 테이블도 있습니다.

캐스케이딩 설정 프레임워크는 인스턴스 전체 설정이 application_settings 테이블에 있고, 그룹 및 프로젝트 설정이 각각 namespace_settings 및 project_settings에 있다고 가정합니다. GitLab Duo를 위한 캐스케이딩 설정 추가를 고려 중이라면, ai_settings 대신 application_settings를 사용하는 것이 좋은 이유가 될 수 있습니다.