GitHub Personal Access Token을 활용한 API 권한 인증과 설정 방법

1. 개요

GitHub API를 통해 리포지토리를 읽거나 이슈를 생성하거나 액션을 트리거하려면 반드시 인증이 필요합니다. 이때 가장 일반적으로 사용되는 인증 방식이 바로 Personal Access Token (PAT) 입니다.

이 글에서는 다음 내용을 다룹니다:

GitHub Personal Access Token이란 무엇인가?
토큰을 생성하고 설정하는 방법
토큰을 사용해 API 요청을 인증하는 코드 예시
권한 범위를 설정할 때 주의할 점

2. Personal Access Token(PAT)이란?

PAT는 사용자의 GitHub 계정 권한을 대신하여 API 요청을 보낼 수 있는 비밀번호 같은 문자열입니다.

OAuth 앱 또는 GitHub Actions 외에, 개인 또는 백엔드 서비스에서 GitHub와 연동할 때 가장 많이 사용되는 인증 수단입니다.

3. PAT 생성 방법

GitHub 로그인 > 오른쪽 상단 프로필 > Settings
좌측 메뉴 > Developer Settings > Personal access tokens > Tokens (classic) 또는 Fine-grained tokens
Generate new token 클릭
다음 항목을 설정:
- Note: 토큰 이름
- Expiration: 만료 기간 설정 (보안상 짧게 추천)
- Scopes: 토큰 권한 범위 (예: repo, workflow, read:org 등)
토큰을 복사해둠 (한 번만 제공됨)

생성된 토큰은 GitHub API 요청 시 Authorization: Bearer <TOKEN> 형태로 사용됩니다.

4. 예시: 토큰을 이용한 리포지토리 정보 요청

4.1 요청 코드 (Node.js + Axios)

import axios from 'axios';

const GITHUB_TOKEN = process.env.GITHUB_TOKEN!; // 환경변수에서 불러오기
const REPO = 'my-org/my-repo';

async function fetchRepoInfo() {
  const res = await axios.get(`https://api.github.com/repos/${REPO}`, {
    headers: {
      Authorization: `Bearer ${GITHUB_TOKEN}`,
      Accept: 'application/vnd.github+json',
    },
  });

  console.log(res.data);
}

fetchRepoInfo();

🔍 동작 설명

Authorization 헤더에 Bearer 방식으로 토큰을 포함시킵니다.
Accept 헤더는 GitHub의 최신 API 형식을 요청하는 것입니다.
repos/{owner}/{repo} API는 해당 리포지토리의 메타 정보를 반환합니다.

5. 권한 범위 설정 주의사항

주요 Scope 설명:

Scope 설명

repo	공개/비공개 리포지토리 접근 (읽기/쓰기 모두 포함)
read:org	조직 멤버 정보 읽기 권한
workflow	GitHub Actions 워크플로우 실행/관리 권한
admin:repo_hook	Webhook 설정 및 관리 권한

최소 권한의 원칙(Principle of Least Privilege)을 지키는 것이 중요합니다. 불필요한 권한은 제거해야 보안 사고를 줄일 수 있습니다.

6. 실전 적용 팁

토큰은 환경변수로 관리하고 절대 코드에 하드코딩하지 않습니다.
토큰 노출 시 즉시 취소하고 새로 생성해야 합니다.
GitHub Apps나 OIDC 인증이 가능한 경우, PAT 대신 권장 방식으로 점차 이전하는 것이 좋습니다.

7. 정리

GitHub API를 사용할 때는 Personal Access Token을 통해 인증할 수 있습니다.
토큰은 GitHub 사용자 권한을 대표하므로 반드시 안전하게 관리해야 합니다.
위 코드는 구조를 설명하기 위한 예제이며, 실제 환경에서는 보안 설정 및 에러 처리를 강화하여 사용하시길 권장합니다.

[GitHub] Personal Access Token을 활용한 API 권한 인증과 설정 방법