깃블로그 댓글 Giscus 오류 해결: Unable to create discussion

💬 Giscus 댓글 기능과 마주한 연동 오류

깃블로그(GitHub Pages)에 댓글 기능을 추가하기 위해 가장 많이 사용하는 도구 중 하나가 바로 Giscus입니다. Giscus는 GitHub Discussions를 기반으로 작동하여 정적 블로그에서도 데이터베이스 없이 깔끔하게 댓글을 관리할 수 있는 강력한 오픈소스 도구입니다.

하지만 설정을 마친 후 블로그 화면에 다음과 같은 오류가 표시되며 당황하는 경우가 많습니다.

❌ giscus is not installed on this repository
❌ Unable to create discussion

본 포스트에서는 이 오류가 발생하는 세 가지 핵심 원인과 함께 이를 한 번에 해결할 수 있는 단계별 조치 가이드를 정리해 보았습니다.

---

🔍 오류가 발생하는 3가지 핵심 원인

1. GitHub 저장소의 Discussions 기능 미활성화

Giscus는 댓글을 GitHub 저장소의 Discussions에 게시글 형태로 저장합니다. 따라서 연동하고자 하는 저장소의 Discussions 기능이 비활성화되어 있으면 Giscus가 댓글 데이터를 생성하거나 조회할 수 없습니다.

2. 저장소 고유 ID (data-repo-id)의 불일치

개발 중인 코드나 블로그 템플릿에 다른 사람의 설정이나 예시 코드가 그대로 남아 있는 경우, 실제 배포된 저장소의 ID와 코드 상의 data-repo-id가 달라 정상적으로 연동되지 않습니다.

3. 토론 카테고리 ID (data-category-id)의 불일치

저장소 ID가 달라지면 해당 저장소 내에 존재하는 토론 카테고리의 고유 ID(data-category-id) 역시 바뀝니다. 맞지 않는 카테고리 ID를 코드로 전달하면 "Unable to create discussion"이라는 오류창이 발생합니다.

---

🛠️ 해결 프로세스: 단계별 조치 가이드

단계 1: GitHub 저장소에서 Discussions 활성화하기

1. 댓글을 연동할 GitHub 저장소(예: seodaeya/seodaeya.github.io) 페이지로 이동합니다.
2. 상단 메뉴에서 Settings (설정) 탭을 클릭합니다.
3. General 화면에서 스크롤을 내려 Features 섹션을 찾습니다.
4. Discussions 항목의 체크박스를 찾아 체크(활성화)해 줍니다.

단계 2: giscus GitHub App 권한 관리

1. giscus GitHub App 설정 페이지로 이동합니다.
2. Configure 버튼을 클릭하여 본인의 계정을 선택합니다.
3. Repository access 설정에서 Only select repositories를 선택하고, 연동할 블로그 저장소를 추가한 뒤 Save를 누릅니다.

단계 3: 정확한 Repo ID 및 Category ID 발급받기

1. giscus.app 사이트에 접속합니다.
2. 저장소 섹션에 본인의 저장소 경로(예: seodaeya/seodaeya.github.io)를 입력합니다.
3. 입력 후 저장소가 올바르게 설치되었다는 메시지가 뜨면, 하단의 토론 카테고리에서 사용하고자 하는 카테고리(예: General)를 선택합니다.
4. 아래 giscus 추가 섹션에 생성된 스크립트 코드에서 data-repo-id와 data-category-id를 각각 복사합니다.

단계 4: 코드 수정 및 재배포

1. 블로그 소스 코드의 Giscus 설정 파일(예: components/Comments.js)을 엽니다.
2. 방금 복사한 올바른 ID 값들을 복사하여 붙여넣고 저장합니다.
3. 코드 변경 사항을 커밋하고 푸시하여 재배포합니다.
4. 배포 완료 후 브라우저 캐시를 지운 뒤(Cmd + Shift + R 또는 Ctrl + F5) 확인합니다.

---

💡 요약 및 마무리

Giscus 연동 시 발생하는 오류는 대부분 저장소 설정의 Discussions 활성화 누락과 코드 상의 고유 키 값 오기입으로 인해 발생합니다. 위의 가이드에 따라 하나씩 확인해 보신다면 누구나 쉽게 깃블로그에 댓글 기능을 정상 탑재하실 수 있습니다.

블로그 방문자들과 활발하게 소통해 보세요!