Skip to content
푸땡로그
Go back

GitHub Discussions 자동 생성 시스템으로 Giscus 댓글 완성하기

이전 글에서 Astro 블로그에 Giscus 댓글 시스템을 구현했습니다. 이번 글에서는 빌드할 때 포스트별 Discussion을 미리 만드는 GitHub Discussions 자동 생성 시스템을 구현합니다. 🚀


🤔 왜 Discussion 자동 생성이 필요한가?

Giscus의 한계점

Giscus는 댓글을 표시하기 위해 해당 포스트와 매칭되는 GitHub Discussion이 존재해야 합니다.
Discussion이 없으면 Giscus가 404 에러를 냅니다.
그래서 빌드할 때 Discussion을 자동으로 만들어 404 에러를 막습니다.

자동 생성으로 얻는 것

  1. 404 에러 방지: Discussion이 없는 포스트에서 댓글 영역을 열어도 에러가 나지 않음
  2. 사용자 경험 개선: 모든 포스트에서 일관된 댓글 시스템 제공
  3. 관리 효율성: 수동으로 Discussion을 생성할 필요 없음
  4. 확장성: 새 포스트 작성 시 자동으로 댓글 시스템 준비

🏗️ 시스템 아키텍처

전체 구조

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을 생성해야 합니다.

토큰 생성 과정

  1. GitHub.com → Settings → Developer settings → Personal access tokens → Fine-grained tokens
  2. Generate new token 클릭
  3. Token name: blog-discussions-auto-generation
  4. Expiration: 1년 권장
  5. Repository access: Giscus가 사용하는 저장소만 선택
  6. Permissions: Discussions Read and write (필수)
  7. Generate token 클릭 후 토큰 복사

보안 주의사항

⚠️ 중요: 토큰을 절대 공개 저장소에 커밋하지 마세요!

  • .env 파일을 .gitignore에 추가
  • 배포 환경에서는 환경 변수로 설정
  • 토큰 노출 시 즉시 재발급

토큰 권한 확인

Bash
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을 환경 변수로 설정합니다:

Bash
# .env 파일에 추가 (절대 공개 저장소에 커밋하지 마세요!)
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

환경 변수 설명:

저장소 및 카테고리 ID 설정

실제 구현에서는 상수 파일에 둔 값을 사용합니다:

TypeScript
// 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 생성 스크립트를 바탕으로 합니다.

기본 유틸리티 함수

TypeScript
// 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 검색 및 생성 함수

TypeScript
// 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;
  }
}

고급 처리 함수들

TypeScript
// 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;
}

주요 특징


🤖 빌드 시 자동 실행 시스템

앞에서 만든 유틸리티로 빌드할 때 Discussion을 자동 생성하는 스크립트를 만듭니다.

1단계: package.json 스크립트 추가

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"
  }
}

스크립트 설명:

npm은 postbuild라는 이름만 build 뒤에 자동으로 실행합니다. 그래서 build 스크립트 끝에 npm run post-build:discussions를 직접 붙였습니다. 스크립트를 실행하려면 npm install -D tsx와 npm install dotenv gray-matter로 의존성을 먼저 설치합니다.

2단계: Discussion 생성 스크립트

TypeScript
// 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단계: 실행 및 테스트

자동 실행 (빌드 후)

Bash
npm run build
# 빌드 완료 후 자동으로 Discussion 생성 스크립트 실행

수동 실행

Bash
npm run discussions:manual
# 언제든지 수동으로 Discussion 생성 가능

실행 결과 확인

Bash
# GitHub 저장소의 Discussions 탭에서 생성된 Discussion 확인
# 또는 콘솔 로그를 통해 처리 결과 확인

📚 참고 자료


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 스크립트 연결과 패키지 설치 안내도 추가했습니다.


Share this post on:

Previous Post
Astro 블로그에 Giscus 댓글 시스템 구현하기
Next Post
Claude Code Agent Teams: 여러 에이전트에게 작업을 나눠 맡기고 조율하는 방법