GitHub Issue Template이 표시되지 않는 문제 해결 (front-matter 설정)

🧑‍💻 GitHub Issue Template이 표시되지 않는 문제 해결 (front-matter 설정)

프로젝트를 진행하면서 팀원들과 협업을 위해 GitHub Issue Template을 만들었다.
하지만 템플릿을 생성했음에도 불구하고 이슈 생성 화면에서 템플릿이 표시되지 않는 문제가 발생했다.

 

이번 글에서는 해당 문제의 원인과 해결 과정을 정리해보려고 한다.

---

📌 문제 상황

GitHub 협업을 위해 Issue Template을 생성했다.

 

.github/ISSUE_TEMPLATE/custom.md 파일을 생성하고 템플릿 내용을 작성했지만
GitHub에서 Issue 생성 화면에 템플릿이 표시되지 않는 문제가 발생했다.

---

🔍 원인 분석

문제의 원인은 Issue Template 파일 상단에 front-matter 설정이 없었기 때문이었다.

 

GitHub Issue Template은 단순히 .md 파일을 생성한다고 자동으로 인식되지 않는다.
파일 상단에 아래와 같은 **메타 정보(front-matter)**가 반드시 필요하다.

---
name: "🛠 작업 요청 템플릿"
about: "새로운 작업을 정의할 때 사용하는 기본 템플릿입니다."
title: "[TASK] "
labels: "enhancement"
assignees: ""
---

 

이 설정이 없으면 GitHub은 해당 파일을 일반 Markdown 파일로만 인식하게 된다.

 

즉, 템플릿으로 사용되기 위해서는 front-matter 설정이 필수다.

---

🛠 해결 과정

문제를 해결하기 위해 custom.md 파일 상단에
front-matter 설정을 추가했다.

---
name: "🛠 작업 요청 템플릿"
about: "새로운 작업을 정의할 때 사용하는 기본 템플릿입니다."
title: "[TASK] "
labels: "enhancement"
assignees: ""
---

 

이 설정을 추가한 후 다시 GitHub에서 Issue 생성 화면을 확인하자

정상적으로 템플릿이 표시되는 것을 확인할 수 있었다.

---

📊 정리

GitHub Issue Template이 동작하기 위해서는 다음 조건이 필요하다.

• .github/ISSUE_TEMPLATE/ 경로에 파일이 존재해야 한다
• .md 형식의 파일이어야 한다
• front-matter 설정이 반드시 포함되어야 한다
• name, about, title 등의 메타 정보가 있어야 템플릿으로 인식된다

---

💡 회고 및 교훈

1️⃣ 도구의 규칙을 정확히 이해하는 것이 중요

• GitHub Issue Template은 단순히 .md 파일을 생성한다고 자동으로 인식되지 않는다.
• name, about, title 등의 front-matter 메타 정보가 있어야 템플릿으로 인식된다는 점을 확인할 수 있었다.

 

2️⃣ 공식 문서를 확인하는 습관의 필요성

 

문제 발생 당시에는 팀원분의 도움으로 해결할 수 있었지만
이후 GitHub Docs를 확인하면서 Issue Template이

• .github/ISSUE_TEMPLATE/ 경로
• front-matter 설정

을 기준으로 동작한다는 것을 알게 되었다.

앞으로는 문제 발생 시 공식 문서를 먼저 확인하는 습관을 가져야겠다고 느꼈다.

 

 

3️⃣ 협업 환경에서는 템플릿 관리가 중요

• Issue Template을 설정하면 팀원들이 일관된 형식으로 이슈를 작성할 수 있어 협업 효율이 높아진다.
• 앞으로 프로젝트에서도 협업을 위해 Issue Template, PR Template 등 협업 규칙을 적극적으로 활용해볼 예정이다.