설명 템플릿

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

이슈 및 Merge Request에 사용할 템플릿을 정의할 수 있습니다.

프로젝트, 그룹 또는 인스턴스에서 이러한 템플릿을 정의할 수 있습니다. 프로젝트는 상위 수준에서 정의된 템플릿을 상속합니다.

다음과 같은 템플릿을 사용하고 싶을 수 있습니다:

  • 워크플로우의 다른 단계에 대해, 예를 들어, 기능 제안, 기능 개선 또는 버그 보고서.
  • 특정 프로젝트의 모든 이슈나 Merge Request에 대해 레이아웃이 일관되게 유지되도록.
  • Service Desk 이메일 템플릿으로 사용할 수 있습니다.

설명 템플릿을 사용하려면 다음이 충족되어야 합니다:

  • .md 확장자로 저장되어야 합니다.
  • 프로젝트의 리포지터리인 .gitlab/issue_templates 또는 .gitlab/merge_request_templates 디렉터리에 저장되어야 합니다.
  • 기본 브랜치에 있어야 합니다.

이슈 템플릿 생성

리포지터리의 .gitlab/issue_templates/ 디렉터리에 새로운 마크다운(.md) 파일을 만드세요.

이슈 설명 템플릿을 만들려면:

  1. 왼쪽 사이드바에서 검색 또는 이동하여 프로젝트를 찾습니다.
  2. 코드 > 리포지터리를 선택합니다.
  3. 기본 브랜치 옆에서 를 선택합니다.
  4. 새 파일을 선택합니다.
  5. 기본 브랜치 옆의 파일 이름 텍스트 상자에 .gitlab/issue_templates/mytemplate.md를 입력합니다. 여기서 mytemplate은 이슈 템플릿의 이름입니다.
  6. 기본 브랜치에 커밋합니다.

이것이 올바르게 작동하는지 확인하려면 새 이슈를 생성하여 템플릿 선택 드롭다운 디렉터리에서 설명 템플릿을 찾을 수 있는지 확인합니다.

Merge Request 템플릿 생성

이슈 템플릿과 유사하게, 리포지터리의 .gitlab/merge_request_templates/ 디렉터리에 새로운 마크다운(.md) 파일을 만드세요. 이슈 템플릿과 달리, Merge Request에는 추가적인 상속 규칙이 있습니다. 이는 커밋 메시지와 브랜치 이름의 내용에 따라 달라집니다.

프로젝트에 대한 Merge Request 설명 템플릿을 만들려면:

  1. 왼쪽 사이드바에서 검색 또는 이동하여 프로젝트를 찾습니다.
  2. 코드 > 리포지터리를 선택합니다.
  3. 기본 브랜치 옆에서 를 선택합니다.
  4. 새 파일을 선택합니다.
  5. 기본 브랜치 옆의 파일 이름 텍스트 상자에 .gitlab/merge_request_templates/mytemplate.md를 입력합니다. 여기서 mytemplate은 Merge Request 템플릿의 이름입니다.
  6. 기본 브랜치에 커밋합니다.

이것이 올바르게 작동하는지 확인하려면 새 Merge Request을 생성하여 템플릿 선택 드롭다운 디렉터리에서 설명 템플릿을 찾을 수 있는지 확인합니다.

템플릿 사용

이슈나 Merge Request을 생성하거나 편집할 때 템플릿 선택 드롭다운 디렉터리에 표시됩니다.

템플릿을 적용하려면:

  1. 이슈나 Merge Request을 생성하거나 편집합니다.
  2. 템플릿 선택 드롭다운 디렉터리을 선택합니다.
  3. 설명 텍스트 상자가 비어 있지 않은 경우, 확인을 위해 템플릿 적용을 선택합니다.
  4. 변경 사항 저장을 선택합니다.

설명 템플릿을 선택하면 해당 내용이 설명 텍스트 상자에 복사됩니다.

템플릿을 선택한 후 설명에 대한 변경을 취소하려면 템플릿 선택 드롭다운 디렉터리을 확장하고 템플릿 재설정을 선택합니다.

이슈에서 설명 템플릿 선택

note
지정된 템플릿을 사용하여 이슈를 생성하는 단축 링크를 만들 수 있습니다. 예시: https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal. 자세한 내용은 사전 작성된 값이 있는 URL을 사용하여 이슈 생성을 읽어보세요.

Merge Request 템플릿에서 지원되는 변수

note
이 기능은 기본 템플릿 설정에서만 사용할 수 있습니다.

Merge Request을 처음으로 저장할 때, GitLab은 Merge Request 템플릿에서 이러한 변수를 해당 값으로 대체합니다:

변수 설명 결과 예시
%{all_commits} Merge Request의 모든 커밋 메시지. 최근 100개의 커밋에 대해 제한됩니다. 100 KiB를 초과하는 커밋 본문은 건너뜁니다. Merge 커밋 메시지도 제외됩니다. * 기능 도입

이 커밋은 기능을 구현합니다
변경내역: 추가됨

* 버그 수정

* 문서 개선

이 커밋은 더 좋은 문서를 도입했습니다.
%{co_authored_by} Merge Request에서 최근 100개의 커밋의 작성자 이름과 이메일을 Co-authored-by Git 커밋 트레일러 형식으로 제공합니다. Co-authored-by: Zane Doe <zdoe@example.com>
Co-authored-by: Blake Smith <bsmith@example.com>
%{first_commit} Merge Request 차이의 첫 번째 커밋의 전체 메시지입니다. README.md 업데이트
%{first_multiline_commit} Merge Request에서 첫 번째 Merge 커밋이며 메시지 본문이 여러 줄인 전체 메시지입니다. 만약 모든 커밋이 여러 줄이 아니면 Merge Request 제목이 됩니다. README.md 업데이트

Readme 파일에 프로젝트 설명을 개선했습니다.
%{source_branch} Merge되는 브랜치의 이름입니다. my-feature-branch
%{target_branch} 변경이 적용되는 브랜치의 이름입니다. main

인스턴스 수준 설명 템플릿 설정

Tier: Premium, Ultimate Offering: Self-managed, GitLab Dedicated

인스턴스 템플릿 리포지터리를 사용하여 이슈와 Merge Request에 대한 인스턴스 수준 설명 템플릿을 설정할 수 있습니다. 또한 파일 템플릿에도 인스턴스 템플릿 리포지터리를 사용할 수 있습니다.

또한, 해당 인스턴스에서 새 프로젝트를 생성할 때 사용할 수 있는 프로젝트 템플릿에 관심이 있을 수 있습니다.

그룹 수준 설명 템플릿 설정

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

그룹 수준 설명 템플릿을 사용하면 그룹 내의 프로젝트를 선택하여 템플릿을 저장할 수 있습니다. 그런 다음 해당 템플릿을 그룹의 다른 프로젝트에서 액세스할 수 있습니다. 결과적으로 모든 그룹 프로젝트의 이슈 및 Merge Request에서 동일한 템플릿을 사용할 수 있습니다.

필수 사항:

  • 그룹에 대한 소유자 역할이 있어야 합니다.
  • 프로젝트는 그룹의 직계 하위여야 합니다.

생성한 템플릿을 재사용하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
  2. 설정 > 일반을 선택합니다.
  3. 템플릿을 확장합니다.
  4. 드롭다운 디렉터리에서 템플릿 프로젝트를 그룹 수준의 템플릿 리포지터리로 선택합니다.
  5. 변경 사항 저장을 선택합니다.

그룹 템플릿 설정

또한, 그룹 내 다양한 파일 유형에 대한 템플릿에 관심이 있을 수 있습니다.

이슈 및 Merge Request을 위한 기본 템플릿 설정

프로젝트에서 새로운 이슈 및 Merge Request을 위한 기본 설명 템플릿을 선택할 수 있습니다. 결과적으로 새로운 Merge Request 또는 이슈가 생성될 때마다 템플릿에 입력한 텍스트로 미리 채워집니다.

필수 사항:

  • 프로젝트의 왼쪽 사이드바에서 설정 > 일반을 선택하고 가시성, 프로젝트 기능, 권한을 확장합니다. 이슈 또는 Merge Request이 접근 권한이 있는 모든 사용자 또는 프로젝트 멤버만으로 설정되어 있는지 확인합니다.

Merge Request을 위한 기본 설명 템플릿을 설정하려면 다음 중 하나를 수행하세요:

  • GitLab 14.8 이상의 버전에서 .gitlab/merge_request_templates/에 Default.md(대소문자 구분 없음)로 이름 지은 Merge Request 템플릿을 생성하고 저장합니다. 이렇게 하면 프로젝트 설정에서 이미 기본 템플릿이 설정되어 있는 경우에는 해당 설정을 덮어쓰지 않습니다.

  • GitLab Premium 및 Ultimate 사용자: 프로젝트 설정에서 기본 템플릿을 설정합니다.

    1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
    2. 설정 > Merge Request을 선택합니다.
    3. Merge Request을 위한 기본 설명 템플릿 섹션에서 텍스트 영역을 채웁니다.
    4. 변경 사항 저장을 선택합니다.

이슈를 위한 기본 설명 템플릿을 설정하려면 다음 중 하나를 수행하세요:

  • GitLab 14.8 이상의 버전에서 .gitlab/issue_templates/에 Default.md(대소문자 구분 없음)로 이름 지은 이슈 템플릿을 생성하고 저장합니다. 이렇게 하면 프로젝트 설정에서 이미 기본 템플릿이 설정되어 있는 경우에는 해당 설정을 덮어쓰지 않습니다.

  • GitLab Premium 및 Ultimate 사용자: 프로젝트 설정에서 기본 템플릿을 설정합니다.

    1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
    2. 설정 > 일반을 선택합니다.
    3. 이슈를 위한 기본 설명 템플릿을 확장합니다.
    4. 텍스트 영역을 채웁니다.
    5. 변경 사항 저장을 선택합니다.

GitLab Merge Request 및 이슈는 마크다운을 지원하므로 제목, 디렉터리 등을 포맷팅할 수 있습니다.

또한, 프로젝트 REST API에서 issues_template 및 merge_requests_template 속성을 제공하여 기본 이슈 및 Merge Request 템플릿을 최신 상태로 유지할 수 있습니다.

기본 설명 템플릿의 우선 순위

각종 위치에서 이슈 설명 템플릿을 설정하면 프로젝트에서 다음과 같은 우선 순위가 있습니다. 아래쪽에 있는 것들은 위쪽에 있는 것들을 덮어씁니다:

  1. 프로젝트 설정에서 설정한 템플릿.
  2. 상위 그룹의 Default.md(대소문자 구분 없음).
  3. 프로젝트 리포지터리에서의 Default.md(대소문자 구분 없음).

Merge Request은 커밋 메시지 및 브랜치 이름의 내용에 따라 추가 상속 규칙이 있습니다.

설명 템플릿 예시

GitLab 프로젝트의 .gitlab 폴더에서 이슈 및 Merge Request에 대한 설명 템플릿을 참조할 수 있습니다.

caution
빠른 조치를 사용하여 이슈 또는 Merge Request을 제출하는 사용자가 수행할 수 있는 동작을 빠르게 추가할 수 있습니다. 빠른 조치는 관련 작업을 수행할 수 있는 권한을 가진 경우에만 실행됩니다.

다음은 버그 보고 템플릿의 예시입니다: 

## 요약

(간결하게 발견된 버그를 요약)

## 재현 방법

(문제를 재현하는 방법 - 매우 중요합니다)

## 예제 프로젝트

(가능한 경우, GitLab.com에서 여기에 문제를 나타내는 예제 프로젝트를 생성하고 여기에서 해당 버그보고서에 링크를 추가합니다.
더 낮은 버전의 GitLab을 사용 중인 경우, 해당 버그가 더 최신 버전에서 수정되었는지도 확인합니다)

## 현재 버그 동작은 무엇입니까?

(실제로 발생하는 것)

## 올바른 예상 동작은 무엇입니까?

(올바른 동작 대신에 보여야 하는 것)

## 관련 로그 및/또는 스크린샷

(관련 로그를 붙여넣습니다)

## 가능한 수정 항목

(문제의 책임이 있는 코드 라인에 링크를 추가할 수 있는 경우)

/label ~bug ~reproduced ~needs-investigation
/cc @project-manager
/assign @qa-tester