이전 글에서 Astro 블로그에 Giscus 댓글 시스템을 구현했습니다. 이번 글에서는 빌드할 때 포스트별 Discussion을 미리 만드는 GitHub Discussions 자동 생성 시스템을 구현합니다. 🚀
🤔 왜 Discussion 자동 생성이 필요한가?
Giscus의 한계점
Giscus는 댓글을 표시하기 위해 해당 포스트와 매칭되는 GitHub Discussion이 존재해야 합니다.
Discussion이 없으면 Giscus가 404 에러를 냅니다.
그래서 빌드할 때 Discussion을 자동으로 만들어 404 에러를 막습니다.
자동 생성으로 얻는 것
- 404 에러 방지: Discussion이 없는 포스트에서 댓글 영역을 열어도 에러가 나지 않음
- 사용자 경험 개선: 모든 포스트에서 일관된 댓글 시스템 제공
- 관리 효율성: 수동으로 Discussion을 생성할 필요 없음
- 확장성: 새 포스트 작성 시 자동으로 댓글 시스템 준비
🏗️ 시스템 아키텍처
전체 구조
flowchart TD
A[사용자<br/>댓글 작성 / 조회] --> B[Astro 블로그<br/>Giscus 위젯]
B --> C[GitHub Discussions<br/>댓글 저장 / 관리]
D[Astro Build] -->|빌드 시 자동 생성| C
구성 요소
flowchart TD
A[npm run build 완료] --> B[포스트 분석<br/>모든 포스트 정보 수집]
B --> C{Discussion<br/>존재 여부 확인}
C -->|있음| D[스킵]
C -->|없음| E[GraphQL API로<br/>Discussion 생성]
E --> F{성공?}
F -->|성공| G[다음 포스트 처리]
F -->|실패| H[에러 로깅 후<br/>다음 포스트 처리]
D --> G
H --> G
🚀 GitHub GraphQL API 연동
0단계: Personal Access Token 생성
GitHub GraphQL API를 사용하기 전에 Personal Access Token을 생성해야 합니다.
토큰 생성 과정
- GitHub.com → Settings → Developer settings → Personal access tokens → Fine-grained tokens
- Generate new token 클릭
- Token name:
blog-discussions-auto-generation - Expiration: 1년 권장
- Repository access: Giscus가 사용하는 저장소만 선택
- Permissions: Discussions
Read and write(필수) - Generate token 클릭 후 토큰 복사
보안 주의사항
⚠️ 중요: 토큰을 절대 공개 저장소에 커밋하지 마세요!
.env파일을.gitignore에 추가- 배포 환경에서는 환경 변수로 설정
- 토큰 노출 시 즉시 재발급
토큰 권한 확인
curl -H "Authorization: Bearer YOUR_TOKEN" \
-H "Accept: application/vnd.github.v4+json" \
https://api.github.com/graphql \
-d '{"query":"query { viewer { login } }"}'1단계: 환경 변수 설정
Personal Access Token을 환경 변수로 설정합니다:
# .env 파일에 추가 (절대 공개 저장소에 커밋하지 마세요!)
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx환경 변수 설명:
GITHUB_TOKEN: 방금 생성한 Personal Access TokenGISCUS_REPO: Giscus가 사용하는 저장소 (예:username/blog-repo)GISCUS_REPO_ID: 저장소의 고유 ID (R_kgDO...형식 문자열)GISCUS_CATEGORY_ID: Discussion 카테고리 ID (DIC_kwDO...형식 문자열)
저장소 및 카테고리 ID 설정
실제 구현에서는 상수 파일에 둔 값을 사용합니다:
// src/constants.ts
export const GISCUS_CONFIG = {
REPOSITORY: {
ID: "R_kgDOGxxxxxxxx", // 저장소 ID (숫자가 아닌 문자열)
NAME: "username/blog-comments", // 저장소 이름
},
CATEGORY: {
ID: "DIC_kwDOGxxxxxxxx", // 카테고리 ID (숫자가 아닌 문자열)
NAME: "Announcements", // 카테고리 이름
},
API: {
GRAPHQL_URL: "https://api.github.com/graphql",
},
};2단계: Discussion 생성 유틸리티
아래 유틸리티는 이 블로그에서 쓰는 GraphQL 클라이언트와 Discussion 생성 스크립트를 바탕으로 합니다.
기본 유틸리티 함수
// src/utils/githubGraphQL.ts
import "dotenv/config";
import { GISCUS_CONFIG } from "../constants.js";
// GitHub GraphQL API 타입 정의
interface Discussion {
id: string;
title: string;
number: number;
}
interface SearchResult {
discussionCount: number;
nodes: Discussion[];
}
interface CreateDiscussionInput {
repositoryId: string;
categoryId: string;
title: string;
body: string;
}
// GraphQL 클라이언트 초기화
function getGraphQLClient() {
const token = process.env.GITHUB_TOKEN;
if (!token) {
throw new Error("GITHUB_TOKEN environment variable is not set");
}
return {
async query<T>(
query: string,
variables?: Record<string, unknown>
): Promise<T> {
const response = await fetch(GISCUS_CONFIG.API.GRAPHQL_URL, {
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
query,
variables,
}),
});
if (!response.ok) {
const errorText = await response.text();
throw new Error(
`GitHub API error: ${response.status} ${response.statusText}\n${errorText}`
);
}
const result = await response.json();
if (result.errors) {
throw new Error(`GraphQL errors: ${JSON.stringify(result.errors)}`);
}
return result.data;
},
};
}Discussion 검색 및 생성 함수
// src/utils/githubGraphQL.ts
// Discussion 검색 함수
export async function searchDiscussion(
pathname: string
): Promise<Discussion | null> {
const client = getGraphQLClient();
// pathname을 기반으로 discussion 검색
const searchQuery = `repo:${GISCUS_CONFIG.REPOSITORY.NAME} "${pathname}" in:title`;
const query = `
query SearchDiscussions($query: String!) {
search(query: $query, type: DISCUSSION, first: 1) {
discussionCount
nodes {
... on Discussion {
id
title
number
}
}
}
}
`;
try {
const result = await client.query<{ search: SearchResult }>(query, {
query: searchQuery,
});
if (result.search.discussionCount > 0 && result.search.nodes.length > 0) {
return result.search.nodes[0];
}
return null;
} catch (error) {
console.error(`[GitHub GraphQL] Error searching for discussion:`, error);
throw error;
}
}
// Discussion 생성 함수
export async function createDiscussion(pathname: string): Promise<Discussion> {
const client = getGraphQLClient();
const mutation = `
mutation CreateDiscussion($input: CreateDiscussionInput!) {
createDiscussion(input: $input) {
discussion {
id
title
number
}
}
}
`;
const input: CreateDiscussionInput = {
repositoryId: GISCUS_CONFIG.REPOSITORY.ID,
categoryId: GISCUS_CONFIG.CATEGORY.ID,
title: pathname,
body: `Discussion for blog post: ${pathname}\n\nThis discussion was automatically created for the blog post at path: ${pathname}`,
};
try {
const result = await client.query<{
createDiscussion: { discussion: Discussion };
}>(mutation, {
input,
});
return result.createDiscussion.discussion;
} catch (error) {
console.error(`[GitHub GraphQL] Error creating discussion:`, error);
throw error;
}
}고급 처리 함수들
// src/utils/githubGraphQL.ts
// Discussion 존재 여부 확인 및 생성 함수
export async function ensureDiscussionExists(
pathname: string
): Promise<Discussion> {
try {
// 먼저 기존 discussion이 있는지 확인
const existingDiscussion = await searchDiscussion(pathname);
if (existingDiscussion) {
console.log(
`[GitHub GraphQL] Discussion already exists for ${pathname}, skipping creation`
);
return existingDiscussion;
}
// discussion이 없으면 새로 생성
console.log(
`[GitHub GraphQL] Discussion not found for ${pathname}, creating new one`
);
return await createDiscussion(pathname);
} catch (error) {
console.error(
`[GitHub GraphQL] Error ensuring discussion exists for ${pathname}:`,
error
);
throw error;
}
}
// 배치 처리를 위한 함수
export async function ensureDiscussionsExist(
pathnames: string[]
): Promise<Discussion[]> {
const results: Discussion[] = [];
const errors: Array<{ pathname: string; error: Error }> = [];
console.log(
`[GitHub GraphQL] Processing ${pathnames.length} pathnames for discussion creation`
);
// 순차 처리 (rate limiting 고려)
for (const pathname of pathnames) {
try {
const discussion = await ensureDiscussionExists(pathname);
results.push(discussion);
// API rate limiting을 위한 짧은 지연
await new Promise(resolve => setTimeout(resolve, 100));
} catch (error) {
console.error(
`[GitHub GraphQL] Error ensuring discussion for ${pathname}:`,
error
);
errors.push({ pathname, error: error as Error });
}
}
if (errors.length > 0) {
console.error(
`[GitHub GraphQL] ${errors.length} errors occurred during batch processing:`
);
errors.forEach(({ pathname, error }) => {
console.error(` - ${pathname}: ${error.message}`);
});
}
console.log(
`[GitHub GraphQL] Batch processing completed. Success: ${results.length}, Errors: ${errors.length}`
);
return results;
}주요 특징
- 타입 안전성: TypeScript 인터페이스로 GraphQL 응답 타입 정의
- 에러 처리: 상세한 에러 메시지와 로깅
- Rate Limiting: API 제한을 고려한 지연 처리
- 배치 처리: 여러 Discussion을 한 번에 처리
- 중복 방지: 기존 Discussion 확인 후 생성
🤖 빌드 시 자동 실행 시스템
앞에서 만든 유틸리티로 빌드할 때 Discussion을 자동 생성하는 스크립트를 만듭니다.
1단계: package.json 스크립트 추가
{
"scripts": {
"build": "astro check && astro build && pagefind --site dist && cp -r dist/pagefind public/ && npm run post-build:discussions",
"post-build:discussions": "tsx scripts/create-discussions.ts",
"discussions:manual": "tsx scripts/create-discussions.ts"
}
}스크립트 설명:
post-build:discussions:build스크립트 마지막 단계에서 실행discussions:manual: 수동으로 Discussion 생성 실행
npm은 postbuild라는 이름만 build 뒤에 자동으로 실행합니다. 그래서 build 스크립트 끝에 npm run post-build:discussions를 직접 붙였습니다. 스크립트를 실행하려면 npm install -D tsx와 npm install dotenv gray-matter로 의존성을 먼저 설치합니다.
2단계: Discussion 생성 스크립트
// scripts/create-discussions.ts
import { promises as fs } from "fs";
import path from "path";
import matter from "gray-matter";
import {
ensureDiscussionExists,
ensureDiscussionsExist,
} from "../src/utils/githubGraphQL";
// 공개 포스트의 slug 읽기 (_draft 폴더와 draft: true 제외)
async function getPublicPosts() {
const blogDir = path.resolve("src/data/blog");
const files = await fs.readdir(blogDir, { recursive: true });
const posts: { slug: string }[] = [];
for (const file of files) {
if (!file.endsWith(".md") || file.includes("_draft")) continue;
const raw = await fs.readFile(path.join(blogDir, file), "utf-8");
const { data } = matter(raw);
if (data.draft) continue;
posts.push({ slug: data.slug ?? path.basename(file, ".md") });
}
return posts;
}
async function createMissingDiscussions() {
try {
console.log("🔍 포스트별 Discussion 확인 중...");
const posts = await getPublicPosts();
// pathname 배열 생성 (포스트 slug 기반)
const pathnames = posts.map(post => `/posts/${post.slug}`);
console.log(
`📝 총 ${posts.length}개 포스트에 대한 Discussion 확인/생성 시작`
);
// 배치 처리로 모든 Discussion 생성
const results = await ensureDiscussionsExist(pathnames);
console.log(`\n📊 Discussion 생성 완료:`);
console.log(` - 성공: ${results.length}개`);
console.log(` - 총 포스트: ${posts.length}개`);
if (results.length === posts.length) {
console.log(
"✅ 모든 포스트에 대한 Discussion이 성공적으로 준비되었습니다!"
);
} else {
console.log(
`⚠️ ${posts.length - results.length}개 포스트에 대한 Discussion 생성에 실패했습니다.`
);
}
} catch (error) {
console.error("❌ Discussion 생성 중 오류 발생:", error);
process.exit(1);
}
}
// 스크립트 실행
createMissingDiscussions();3단계: 실행 및 테스트
자동 실행 (빌드 후)
npm run build
# 빌드 완료 후 자동으로 Discussion 생성 스크립트 실행수동 실행
npm run discussions:manual
# 언제든지 수동으로 Discussion 생성 가능실행 결과 확인
# GitHub 저장소의 Discussions 탭에서 생성된 Discussion 확인
# 또는 콘솔 로그를 통해 처리 결과 확인📚 참고 자료
- GitHub GraphQL API for Discussions ↗
- GitHub Personal Access Tokens ↗
- GitHub Fine-grained Personal Access Tokens ↗
2026년 9월 26일 수정:
GISCUS_REPO_ID와GISCUS_CATEGORY_ID를 “숫자”라고 적은 설명을, 코드와 같이R_kgDO...·DIC_kwDO...형식의 문자열로 바로잡았습니다. 문장도 짧게 다듬었습니다.
2026년 10월 24일 정정: Discussion 생성 스크립트 예제를 실제
scripts/create-discussions.ts처럼 포스트 파일을 직접 읽어/posts/<slug>경로를 만들도록 바로잡았습니다. 기존 예제는 기본 내보내기인getSortedPosts를 이름 있는 내보내기로 가져오고 Astro 밖에서 없는post.slug를 읽어, 실행하면 바로 오류가 났습니다. npm은post-build:discussions를build뒤에 자동으로 실행하지 않으므로build스크립트 연결과 패키지 설치 안내도 추가했습니다.