Import/Export 개발 문서
Import/Export 기능에 대한 일반 개발 지침 및 팁.
본 문서는 YouTube에서 제공 중인 Import/Export 201 프레젠테이션을 기반으로 합니다.
Import/Export 개발에 대한 보다 자세한 내용은 YouTube에서 Deep dive on Import / Export Development를 시청할 수 있습니다.
보안
Import/Export 기능은 지속적으로 업데이트됩니다(내보낼 새로운 것을 추가함). 그러나 코드는 오랜 시간 동안 리팩토링되지 않았습니다. 동적 성격이 보안 문제의 수를 늘리지 않는지 확인하기 위해 코드 감사를 수행해야 합니다.
GitLab 팀원들은 이 기밀 이슈에서 더 많은 정보를 확인할 수 있습니다: https://gitlab.com/gitlab-org/gitlab/-/issues/20720
.
코드 내 보안
일부 클래스들은 Import/Export에 대한 보안 계층을 제공합니다.
AttributeCleaner
는 금지된 키를 제거합니다:
# AttributeCleaner
# 모든 `_ids` 및 다른 금지된 키를 제거함
class AttributeCleaner
ALLOWED_REFERENCES = RelationFactory::PROJECT_REFERENCES + RelationFactory::USER_REFERENCES + ['group_id']
def clean
@relation_hash.reject do |key, _value|
prohibited_key?(key) || !@relation_class.attribute_method?(key) || excluded_key?(key)
end.except('id')
end
...
AttributeConfigurationSpec
은 새 열의 확인 및 추가를 확인합니다:
# AttributeConfigurationSpec
<<-MSG
프로젝트 Import/Export를 사용하여 내보낼 #{relation_class}에 새로운 속성이 추가되어 있는 것 같습니다.
이 속성을 내보낼 수 있으면 `SAFE_MODEL_ATTRIBUTES`에 추가해 주세요.
이 속성을 IMPORT_EXPORT_CONFIG에서 해당 모델의 +excluded_attributes+ 섹션에 추가하여 목록에서 제외해 주세요.
SAFE_MODEL_ATTRIBUTES: #{File.expand_path(safe_attributes_file)}
IMPORT_EXPORT_CONFIG: #{Gitlab::ImportExport.config_file}
MSG
ModelConfigurationSpec
은 새 모델의 확인 및 추가를 확인합니다:
# ModelConfigurationSpec
<<-MSG
#{parent_model_name}과(와) 관련된 새로운 모델 <#{new_models.join(',')}>이(가) Import/Export 기능으로 내보내집니다.
만약 이 모델이 내보내기에 포함되어야 한다면 `#{Gitlab::ImportExport.config_file}`에 추가해주세요.
또한 `#{File.expand_path(ce_models_yml)}`에도 추가해주세요.
이렇게 하면 오류를 처리했음을 알리고 나중에 표시되지 않도록 합니다.
MSG
ExportFileSpec
은 암호화되거나 민감한 열을 감지합니다:
# ExportFileSpec
<<-MSG
발견된 새로운 민감한 단어 <#{key_found}>, 이것은 #{parent.inspect}의 일부입니다.
이 정보가 내보내는 게 적합하지 않다고 생각하면, IMPORT_EXPORT_CONFIG에서 이 모델 또는 속성을 제외하세요.
그렇지 않으면, CURRENT_SPEC의 +safe_list+에 예외를 추가하세요. 그리고 키로 #{sensitive_word}를, 값으로 대응되는 해시나 모델을 사용하세요.
또한 이 속성이 생성된 고유한 토큰이라면, RelationFactory::TOKEN_RESET_MODELS에 추가해서
(동일한 인스턴스로 가져올 때 중복 열 문제를 방지하기 위해) 리셋해야 하는지 확인하세요.
IMPORT_EXPORT_CONFIG: #{Gitlab::ImportExport.config_file}
CURRENT_SPEC: #{__FILE__}
MSG
버전 관리
Import/Export는 단일 GitLab 릴리즈 동안 빈번한 변경사항을 가지고 있어서 엄격한 SemVer를 사용하지 않습니다. 그러나 호환성이 깨지는 경우에는 업데이트가 필요합니다.
# ImportExport
module Gitlab
module ImportExport
extend self
# 매번 버전 업데이트마다 import_export.md의 이력을 최신 상태로 유지해야 합니다.
VERSION = '0.2.4'
호환성
프로젝트를 가져오고 내보낼 때 호환성을 확인하세요.
버전을 업데이트해야 하는 경우
모델/열의 이름을 바꾸거나 어떤 형식을 수행하는 경우, JSON 구조나 아카이브 파일의 파일 구조에서 수정을 해야 합니다.
다음의 경우에는 버전을 업데이트할 필요가 없습니다:
- 새로운 열이나 모델을 추가하는 경우
- 열이나 모델을 삭제하는 경우 (DB 제약 조건이 없는 한)
- 새로운 것(예: 새로운 유형의 업로드)을 내보내는 경우
버전을 업데이트할 때마다 통합 스펙이 실패하고 다음 명령으로 수정할 수 있습니다:
bundle exec rake gitlab:import_export:bump_version
코드 간단히 살펴보기
Import/Export 구성 (import_export.yml
)
주요 구성인 import_export.yml
은 내보내거나 가져올 수 있는 모델 관계를 정의합니다.
프로젝트 Import/Export에 포함될 모델 관계:
project_tree:
- labels:
- :priorities
- milestones:
- events:
- :push_event_payload
- issues:
- events:
# ...
지정된 모델에 대해 포함할 속성만을 포함하도록 합니다:
included_attributes:
user:
- :id
- :public_email
# ...
지정된 모델에 대해 포함하지 않을 속성을 포함하지 않도록 합니다:
excluded_attributes:
project:
- :name
- :path
- ...
내보내기에 의해 호출될 추가 메서드:
# 메서드
methods:
labels:
- :type
label:
- :type
모델 관계의 내보내기 순서를 사용자 정의합니다:
# 지정된 관계에 대한 사용자 정의 내보내기 재정렬 지정
# 예를 들어 이슈에 대해 상대 위치로 사용자 정의 내보내기 재정렬을 사용하여,
# 가져온 곳에서 상대적 위치 값을 재설정할 수 있지만, 여전히 내보낸 프로젝트에 있던 순서대로 이슈를 유지할 수 있도록 합니다.
# 기본적으로 관계의 순서는 PK로 정렬됩니다.
# column - 재정렬할 열을 지정합니다. 기본값은 관계의 PK입니다.
# direction - 정렬 방향을 지정합니다 :asc 또는 :desc, 기본값은 :asc입니다.
# nulls_position - null 값이 위치하는 위치를 지정합니다. 사용자 정의 정렬 열은 null 값이 포함될 수 있기 때문에
# null 값이 위치하는 곳을 지정해야 합니다. :nulls_last 또는 :nulls_first일 수 있으며 기본값은 :nulls_last입니다.
export_reorders:
project:
issues:
column: :relative_position
direction: :asc
nulls_position: :nulls_last
조건별 익스포트
프로젝트 외부에서 연결된 리소스인 경우, 프로젝트나 그룹을 내보내는 사용자가 이러한 연결을 액세스할 수 있는지를 확인해야 할 수 있습니다. include_if_exportable
은 리소스에 대한 연결의 배열을 허용합니다. 내보내는 중에 리소스의 exportable_association?
메서드가 연결의 이름과 사용자를 사용하여 연결된 리소스를 내보낼 수 있는지를 검증합니다.
예시:
include_if_exportable:
project:
issues:
- epic_issue
이 정의:
- 이슈의
exportable_association?(:epic_issue, current_user: current_user)
메서드를 호출합니다. - 메서드가 true를 반환하면, 이슈의
epic_issue
연결을 이슈에 포함합니다.
가져오기
가져오기 작업 상태는 none
에서 scheduled
로, started
로 이동한 다음, 다른 상태로 이동합니다: finished/failed
상태가 started
인 동안 Importer
코드는 가져오기에 필요한 각 단계를 처리합니다.
# ImportExport::Importer
module Gitlab
module ImportExport
class Importer
def execute
if import_file && check_version! && restorers.all?(&:restore) && overwrite_project
project
else
raise Projects::ImportService::Error.new(@shared.errors.join(', '))
end
rescue => e
raise Projects::ImportService::Error.new(e.message)
ensure
remove_import_file
end
def restorers
[repo_restorer, wiki_restorer, project_tree, avatar_restorer,
uploads_restorer, lfs_restorer, statistics_restorer]
end
내보내기 서비스는 Importer
와 유사하며, 데이터를 저장하는 대신 데이터를 복원합니다.
내보내기
# ImportExport::ExportService
module Projects
module ImportExport
class ExportService < BaseService
def save_all!
if save_services
Gitlab::ImportExport::Saver.save(project: project, shared: @shared)
notify_success
else
cleanup_and_notify_error!
end
end
def save_services
[version_saver, avatar_saver, project_tree_saver, uploads_saver, repo_saver,
wiki_repo_saver, lfs_saver].all?(&:save)
end
테스트 픽스처
가져오기/내보내기 스펙에 사용되는 픽스처는 spec/fixtures/lib/gitlab/import_export
에 있습니다. 프로젝트와 그룹 픽스처가 모두 있습니다.
각 픽스처에는 두 가지 버전이 있습니다.
- 모든 객체가 포함된 사람이 읽을 수 있는 단일 JSON 파일.
project.json
또는group.json
으로 불리기도 합니다. -
ndjson
형식의 파일 트리를 포함하는tree
라는 이름의 폴더. 스트릭트하게 필요하지 않은 이상, 이 폴더의 파일을 수동으로 편집하지 마십시오.
사람이 읽을 수 있는 JSON 파일에서 NDJSON 트리를 생성하는 도구는 gitlab-org/memory-team/team-tools
프로젝트에 있습니다.
프로젝트
legacy-project-json-to-ndjson.sh
를 사용하여 NDJSON 트리를 생성하세요.
NDJSON 트리는 다음과 같이 보입니다:
tree
├── project
│ ├── auto_devops.ndjson
│ ├── boards.ndjson
│ ├── ci_cd_settings.ndjson
│ ├── ci_pipelines.ndjson
│ ├── container_expiration_policy.ndjson
│ ├── custom_attributes.ndjson
│ ├── error_tracking_setting.ndjson
│ ├── external_pull_requests.ndjson
│ ├── issues.ndjson
│ ├── labels.ndjson
│ ├── merge_requests.ndjson
│ ├── milestones.ndjson
│ ├── pipeline_schedules.ndjson
│ ├── project_badges.ndjson
│ ├── project_feature.ndjson
│ ├── project_members.ndjson
│ ├── protected_branches.ndjson
│ ├── protected_tags.ndjson
│ ├── releases.ndjson
│ ├── services.ndjson
│ ├── snippets.ndjson
│ └── triggers.ndjson
└── project.json
그룹
legacy-group-json-to-ndjson.rb
를 사용하여 NDJSON 트리를 생성하세요.
NDJSON 트리는 다음과 같습니다:
tree
└── groups
├── 4351
│ ├── badges.ndjson
│ ├── boards.ndjson
│ ├── epics.ndjson
│ ├── labels.ndjson
│ ├── members.ndjson
│ └── milestones.ndjson
├── 4352
│ ├── badges.ndjson
│ ├── boards.ndjson
│ ├── epics.ndjson
│ ├── labels.ndjson
│ ├── members.ndjson
│ └── milestones.ndjson
├── _all.ndjson
├── 4351.json
└── 4352.json
경고:
이러한 픽스처를 업데이트할 때는 테스트가 두 파일 형식에 모두 적용되므로 json
파일과 tree
폴더 모두를 업데이트하는지 확인하세요.