OctoKit

Github API를 편하게 쓰도록 만든 라이브러리 세트

GitHub REST API, GraphQL API 호출을 - 인증 - rate-limit 처리 - pagination - 오류 처리 - webhook 검증 등을 수행해줌

사용 예시

REST API

import { Octokit } from "octokit";

const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });

const { data } = await octokit.rest.repos.get({
  owner: "octocat",
  repo: "Hello-World",
});

console.log(data);

GraphQL API

import { graphql } from "@octokit/graphql";

const { repository } = await graphql(
  `
    query ($owner: String!, $repo: String!) {
      repository(owner: $owner, name: $repo) {
        stargazerCount
      }
    }
  `,
  {
    owner: "octocat",
    repo: "Hello-World",
    headers: {
      authorization: `token ${process.env.GITHUB_TOKEN}`,
    },
  }
);

console.log(repository.stargazerCount);

전체 구조

Core (핵심 HTTP/인증 기능)
REST API (GitHub REST wrapper)
GraphQL API
Webhooks (서명 검증/리스너)
Plugins (확장 기능)

Octokit Core 기능

@octokit/core

모든 Octokit 패키지의 기반.

핵심 기능 인증 - Personal Access Token - GitHub App 인증 (App ID + Private Key) - OAuth App 인증 - Web OAuth Flow 지원 - JWT 발급 자동 처리

요청(Request) 기능 - GitHub API 스펙 자동 적용 - 파라미터 검증 - 자동 User-Agent 설정 - Base URL 커스텀(GitHub Enterprise)

오류 처리(Error Handling) - API rate limit 에러 - Abuse detection - Validation error 자동 파싱 - Retry 가능

Pagination (자동 페이지네이션) - octokit.paginate() API 제공 - 전체 데이터 자동 수집

Hook 시스템 - before/after hooks로 요청을 가로채서 커스텀 가능.

REST API 기능

@octokit/rest

GitHub의 600+ REST API 엔드포인트를 method로 제공.

주요 기능 인증된 사용자 - 내 정보 가져오기 - 이메일 목록 - 사용자 Organizations 조회

Repository 관리 - 레포 만들기 - 삭제/아카이브/포크 - branch, tree, blobs 관리 - Collaborator 추가/삭제 - Webhook 생성/삭제

Issues - 생성/조회/수정/닫기 - 라벨 관리 - Assignees 관리 - Comment 추가/삭제

Pull Requests - 생성 - Merge - Review 등록/승인/요청변경 - 코멘트, 커밋, 파일 변경 내역 읽기

Releases - 릴리즈 생성/수정/삭제 - Release Assets 업로드 - 태그 관리

Git 데이터 API - 커밋/트리/블롭 관리 - Git 객체 생성 - 참조(ref) 생성/삭제 - SHA 체크

Actions - workflow 실행 트리거 - 실행 로그 조회 - artifacts 조회/다운로드/삭제 - workflow dispatch 호출

Checks API - CI 상태 체크 생성 - 상태를 GitHub UI에 표시

Permissions - Token 조회 - Github App permissions 체크

Stats - 기여도 통계 - 트래픽, 인기 파일 조회

GitHub Packages - 패키지 조회 - 버전 삭제 - 패키지 다운로드 정보

GraphQL API 기능

@octokit/graphql

GitHub의 GraphQL API를 편하게 호출하는 클라이언트.

가능한 기능 - GraphQL 쿼리 실행 - 변수 바인딩 - Header 커스텀(auth) - GitHub의 전체 스키마(레포/유저/PR/이슈 모두) 접근

GraphQL의 장점: - 필요한 데이터만 가져오기 - 복잡한 nested 관계를 한번에 조회 - REST에서 여러 요청이 필요한 작업을 한 번에 끝냄

Webhooks 기능

@octokit/webhooks

GitHub에서 오는 이벤트를 받아 처리하는 기능.

지원하는 기능 - Webhook signature 검증(HMAC SHA-256) - 이벤트 라우팅 (예: issues.opened) - 모든 GitHub 이벤트 타입 지원 (100+) - Express/Fastify/Koa 등 Node 프레임워크 연결 - 배포 방식(FaaS) 대응

예:

webhooks.on("issues.opened", async ({ payload }) => {
  console.log("이슈 생성됨:", payload.issue.title);
});

Plugins 시스템

Octokit은 플러그인을 조합해서 기능을 확장하도록 설계됨.

주요 플러그인들:

@octokit/plugin-retry

GitHub API rate limit → 자동 재시도
네트워크 오류 자동 재시도

@octokit/plugin-rest-endpoint-methods - REST API 엔드포인트를 자동 메소드화 - octokit.rest.* 제공하게 하는 핵심

@octokit/plugin-paginate-rest - 페이지네이션 자동 처리 - 모든 list API에서 .paginate() 제공

@octokit/auth- (여러 종류) - 앱 인증 - OAuth 인증 - SSO 인증 등

@octokit/plugin-throttling - GitHub가 abuse detection 걸면 요청 속도 제한 조절 - GitHub Actions 봇 개발 시 필수

@octokit/plugin-request-log - API 요청/응답 로깅

기타 기능 - GitHub Enterprise 호환 - GraphQL rate-limit 검사 - Linking, Hypermedia 지원

특수 라이브러리들

Octokit 생태계에 있는 중요 패키지들:

패키지 기능 octokit Core + REST + paginate + retry 번들 @octokit/auth-app GitHub App 인증 전체 자동화 @octokit/oauth-methods OAuth device flow 등 @octokit/webhooks-methods 웹훅 생성/삭제 등 probot Octokit 기반 GitHub App 프레임워크

Octokit으로 가능한 것들 전체 요약

GitHub 자동화 - Issue/PR 자동 생성 - PR merge bot 만들기 - release 자동 생성 - 잔디 자동 커밋 봇

GitHub Actions 외부 스크립팅 - 빌드 완료 후 release 생성 - CI 결과 보고 Slack 알리기

GitHub App 제작 - Webhook + Octokit 조합 - 리뷰 자동 할당 - 스팸 PR 차단

Git 데이터 직접 조작 - repo 파일 읽기/쓰기 - 커밋 직접 생성 - ref 브랜치 조작

GraphQL로 고급 데이터 조회 - 팀 기여도 통계 - 대규모 레포 분석