설명 템플릿
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
설명 템플릿은 GitLab에서 이슈와 머지 리퀘스트를 만드는 방식을 표준화하고 자동화합니다. 다음에 대한 설명으로 사용할 템플릿을 정의할 수 있습니다: 프로젝트는 그룹과 인스턴스에서 템플릿을 상속합니다. 저장소의 .gitlab/issue_templates/ 디렉토리 내에 새 Markdown(.md) 파일로 설명 템플릿을 만듭니다.
히스토리
- Work item support introduced in GitLab 17.10.
- Support for epics introduced in GitLab 17.10 with a flag named
work_item_epics. Enabled by default. Introduced in beta. - Support for epics generally available in GitLab 18.1. Feature flag
work_item_epicsremoved.
설명 템플릿은 GitLab에서 이슈와 머지 리퀘스트를 만드는 방식을 표준화하고 자동화합니다.
설명 템플릿의 기능:
- 프로젝트 전반에 걸쳐 이슈와 머지 리퀘스트에 대해 일관된 레이아웃을 만듭니다.
- 다양한 워크플로우 단계와 목적에 맞는 특수 템플릿을 제공합니다.
- 프로젝트, 그룹, 전체 인스턴스에 대한 사용자 정의 템플릿을 지원합니다.
- 변수와 빠른 작업으로 필드를 자동으로 채웁니다.
- 버그, 기능, 기타 작업 항목의 적절한 추적을 보장합니다.
- 서비스 데스크 이메일 응답의 형식을 지정합니다.
다음에 대한 설명으로 사용할 템플릿을 정의할 수 있습니다:
프로젝트는 그룹과 인스턴스에서 템플릿을 상속합니다.
템플릿은:
.md확장자로 저장되어야 합니다.- 저장소의
.gitlab/issue_templates또는.gitlab/merge_request_templates디렉토리에 저장되어야 합니다. - 기본 브랜치에 있어야 합니다.
설명 템플릿 만들기#
저장소의 .gitlab/issue_templates/ 디렉토리 내에 새 Markdown(.md) 파일로 설명 템플릿을 만듭니다.
작업 항목 설명 템플릿을 만들려면:
- 상단 메뉴에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
- 왼쪽 사이드바에서 코드 > 저장소를 선택합니다.
- 기본 브랜치 옆에서 +를 선택합니다.
- 새 파일을 선택합니다.
- 기본 브랜치 옆의 파일 이름 텍스트 상자에
.gitlab/issue_templates/mytemplate.md를 입력합니다. 여기서mytemplate은 템플릿의 이름입니다. - 기본 브랜치에 커밋합니다.
올바르게 작동했는지 확인하려면:
- 새 이슈를 만들거나 새 에픽을 만듭니다.
- 템플릿 선택 드롭다운 목록에서 설명 템플릿을 찾을 수 있는지 확인합니다.
머지 리퀘스트 템플릿 만들기#
이슈 템플릿과 마찬가지로 저장소의 .gitlab/merge_request_templates/ 디렉토리 내에 새 Markdown(.md) 파일을 만듭니다. 이슈 템플릿과 달리 머지 리퀘스트에는 커밋 메시지 및 브랜치 이름의 내용에 따라 달라지는 추가 상속 규칙이 있습니다. 자세한 내용은 머지 리퀘스트 만들기를 참조하세요.
프로젝트에 대한 머지 리퀘스트 설명 템플릿을 만들려면:
- 상단 메뉴에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
- 왼쪽 사이드바에서 코드 > 저장소를 선택합니다.
- 기본 브랜치 옆에서 +를 선택합니다.
- 새 파일을 선택합니다.
- 기본 브랜치 옆의 파일 이름 텍스트 상자에
.gitlab/merge_request_templates/mytemplate.md를 입력합니다. 여기서mytemplate은 머지 리퀘스트 템플릿의 이름입니다. - 기본 브랜치에 커밋합니다.
올바르게 작동했는지 확인하려면 새 머지 리퀘스트를 만들고 템플릿 선택 드롭다운 목록에서 설명 템플릿을 찾을 수 있는지 확인합니다.
템플릿 사용#
이슈나 머지 리퀘스트를 만들거나 편집할 때 템플릿 선택 드롭다운 목록에 표시됩니다.
템플릿을 적용하려면:
- 이슈, 작업 항목 또는 머지 리퀘스트를 만들거나 편집합니다.
- 템플릿 선택 드롭다운 목록을 선택합니다.
- 설명 텍스트 상자가 비어 있지 않은 경우 확인을 위해 템플릿 적용을 선택합니다.
- 변경 사항 저장을 선택합니다.
설명 템플릿을 선택하면 해당 내용이 설명 텍스트 상자에 복사됩니다.
템플릿을 선택한 후 설명에 대한 변경 사항을 취소하려면 템플릿 선택 드롭다운 목록을 펼치고 템플릿 재설정을 선택합니다.
지정된 템플릿을 사용하여 이슈를 만드는 단축 링크를 만들 수 있습니다. 예: https://gitlab.com/gitlab-org/gitlab/-/issues/new?description_template=Feature%20proposal. 미리 채워진 값으로 URL을 사용하여 이슈 만들기에 대해 자세히 알아보세요.
머지 리퀘스트 템플릿에서 지원되는 변수#
히스토리
- Introduced in GitLab 15.7.
이 기능은 기본 템플릿에서만 사용할 수 있습니다.
머지 리퀘스트를 처음 저장할 때 GitLab은 머지 리퀘스트 템플릿에서 이 변수들을 해당 값으로 교체합니다:
| 변수 | 설명 | 출력 예시 |
|---|---|---|
%{all_commits} |
머지 리퀘스트의 모든 커밋 메시지. 최근 100개 커밋으로 제한. 100 KiB를 초과하는 커밋 본문 및 머지 커밋 메시지는 건너뜁니다. | * Feature introduced This commit implements feature Changelog:added * Bug fixed * Documentation improved This commit introduced better docs. |
%{co_authored_by} |
Co-authored-by Git 커밋 트레일러 형식의 커밋 작성자 이름 및 이메일. 머지 리퀘스트의 최근 100개 커밋 작성자로 제한. |
Co-authored-by: Zane Doe <zdoe@example.com> Co-authored-by: Blake Smith <bsmith@example.com> |
%{first_commit} |
머지 리퀘스트 차이의 첫 번째 커밋의 전체 메시지. | Update README.md |
%{first_multiline_commit} |
머지 커밋이 아니고 메시지 본문에 두 줄 이상 있는 첫 번째 커밋의 전체 메시지. 모든 커밋이 여러 줄이 아닌 경우 머지 리퀘스트 제목. | Update README.md Improved project description in readme file. |
%{first_multiline_commit_description} |
머지 커밋이 아니고 메시지 본문에 두 줄 이상 있는 첫 번째 커밋의 설명(첫 번째 줄/제목 제외). | Improved project description in readme file. |
%{source_branch} |
머지되는 브랜치의 이름. | my-feature-branch |
%{target_branch} |
변경 사항이 적용되는 브랜치의 이름. | main |
인스턴스 수준 설명 템플릿 설정#
인스턴스 템플릿 저장소를 사용하여 이슈 및 머지 리퀘스트에 대해 인스턴스 수준의 설명 템플릿을 설정할 수 있습니다. 파일 템플릿에도 인스턴스 템플릿 저장소를 사용할 수 있습니다.
인스턴스에서 새 프로젝트를 만들 때 사용할 수 있는 프로젝트 템플릿에도 관심이 있을 수 있습니다.
그룹 수준 설명 템플릿 설정#
그룹 수준 설명 템플릿을 사용하면 그룹 내의 프로젝트를 선택하여 템플릿을 저장할 수 있습니다. 그런 다음 그룹의 다른 프로젝트에서 이러한 템플릿에 액세스할 수 있습니다. 결과적으로 그룹의 모든 프로젝트에서 이슈와 머지 리퀘스트에 동일한 템플릿을 사용할 수 있습니다.
사전 요구 사항:
- 그룹의 소유자 역할이 있어야 합니다.
- 프로젝트는 그룹의 직접 자식이어야 합니다.
만든 템플릿을 재사용하려면:
- 상단 메뉴에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
- 왼쪽 사이드바에서 설정 > 일반을 선택합니다.
- 템플릿을 펼칩니다.
- 드롭다운 목록에서 그룹 수준의 템플릿 저장소로 사용할 템플릿 프로젝트를 선택합니다.
- 변경 사항 저장을 선택합니다.
그룹의 다양한 파일 형식 템플릿에도 관심이 있을 수 있습니다.
머지 리퀘스트 및 이슈의 기본 템플릿 설정#
프로젝트에서 새 이슈 및 머지 리퀘스트에 대한 기본 설명 템플릿을 선택할 수 있습니다. 결과적으로 새 머지 리퀘스트나 이슈가 만들어질 때마다 템플릿에 입력한 텍스트로 미리 채워집니다.
사전 요구 사항:
- 프로젝트의 왼쪽 사이드바에서 설정 > 일반을 선택하고 공개 여부, 프로젝트 기능, 권한을 펼칩니다. 이슈 또는 머지 리퀘스트가 액세스 권한이 있는 모든 사람 또는 프로젝트 구성원만으로 설정되어 있는지 확인합니다.
머지 리퀘스트의 기본 설명 템플릿을 설정하려면 다음 중 하나를 수행합니다:
-
Default.md(대소문자 구분 없음)라는 머지 리퀘스트 템플릿을 만들고.gitlab/merge_request_templates/에 저장합니다.Default.md템플릿은 프로젝트 설정에서 설정한 기본 템플릿보다 우선하지 않습니다. 자세한 내용은 기본 설명 템플릿의 우선순위를 참조하세요. -
GitLab Premium 및 Ultimate 사용자: 프로젝트 설정에서 기본 템플릿을 설정합니다:
- 상단 메뉴에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
- 설정 > 머지 리퀘스트를 선택합니다.
- 머지 리퀘스트의 기본 설명 템플릿 섹션에서 텍스트 영역을 채웁니다.
- 변경 사항 저장을 선택합니다.
작업 항목의 기본 설명을 설정하려면 다음 중 하나를 수행합니다:
-
Default.md(대소문자 구분 없음)라는 설명 템플릿을 만들고.gitlab/issue_templates/에 저장합니다.Default.md템플릿은 프로젝트 설정에서 설정한 기본 설명보다 우선하지 않습니다. 자세한 내용은 기본 설명 템플릿의 우선순위를 참조하세요. -
GitLab Premium 및 Ultimate 사용자: 프로젝트 설정에서 기본 템플릿을 설정합니다:
- 상단 메뉴에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
- 설정 > 일반을 선택합니다.
- 작업 항목의 기본 설명을 펼칩니다.
- 텍스트 영역을 채웁니다.
- 변경 사항 저장을 선택합니다.
GitLab 머지 리퀘스트와 이슈는 Markdown을 지원하므로 제목, 목록 등의 형식을 지정하는 데 사용할 수 있습니다.
프로젝트 REST API에서 issues_template 및 merge_requests_template 속성을 제공하여 기본 이슈 및 머지 리퀘스트 템플릿을 최신 상태로 유지할 수도 있습니다.
기본 설명 템플릿의 우선순위#
다양한 곳에서 이슈 설명 템플릿을 설정할 때, 프로젝트에서 다음 우선순위를 가집니다. 위에 있는 것이 아래 있는 것보다 우선합니다:
- 프로젝트 설정에서 설정한 템플릿.
- 상위 그룹의
Default.md(대소문자 구분 없음). - 프로젝트 저장소의
Default.md(대소문자 구분 없음).
머지 리퀘스트에는 커밋 메시지 및 브랜치 이름의 내용에 따라 달라지는 추가 상속 규칙이 있습니다.
설명 템플릿 예시#
GitLab 프로젝트의 .gitlab 폴더에서 이슈와 머지 리퀘스트에 대한 설명 템플릿을 사용합니다. 이를 일부 예시로 참조할 수 있습니다.
설명 템플릿에서 빠른 작업을 사용하여 레이블, 담당자, 마일스톤을 빠르게 추가할 수 있습니다. 빠른 작업은 이슈 또는 머지 리퀘스트를 제출하는 사용자에게 관련 작업을 수행할 권한이 있는 경우에만 실행됩니다.
다음은 버그 보고서 템플릿의 예시입니다:
## Summary
<!-- HTML comments are not displayed -->
(Summarize the bug encountered concisely)
## Steps to reproduce
(How one can reproduce the issue - this is very important)
## Example Project
(If possible, create an example project here on GitLab.com that exhibits the problematic
behavior, and link to it here in the bug report.
If you are using an older version of GitLab, this will also determine whether the bug has been fixed
in a more recent version)
## What is the current bug behavior?
(What actually happens)
## What is the expected correct behavior?
(What you should see instead)
## Relevant logs and/or screenshots
(Paste any relevant logs - use code blocks (```) to format console output, logs, and code, as
it's very hard to read otherwise.)
## Possible fixes
(If you can, link to the line of code that might be responsible for the problem)
/label ~bug ~reproduced ~needs-investigation
/cc @project-manager
/assign @qa-tester