GitHub REST API 자동화가 운영에서 멈추지 않게 만드는 법

1. 개인 토큰보다 자동화 주체를 먼저 선택

개인 작업인지 조직 서비스인지에 따라 GitHub App, OAuth, fine-grained token과 Actions의 GITHUB_TOKEN 중 적절한 주체가 달라집니다. 운영 자동화는 사람 계정의 넓은 권한에 장기간 의존하지 않도록 설계하세요.

• 사람 계정 토큰 대신 GitHub App 등 서비스 주체 검토
• 토큰 만료일과 교체 담당자 지정

2. 저장소와 작업 단위로 최소 권한 부여

코드 읽기, 이슈 쓰기, 워크플로 실행처럼 필요한 권한을 구분하고 대상 저장소를 제한하세요. 읽기 작업 때문에 관리자 권한을 주지 말고 권한 확대가 필요한 변경은 별도 검토합니다.

• 대상 저장소를 필요한 곳으로만 제한
• 권한 목록을 문서로 남기고 분기마다 재검토

3. 버전·미디어 타입·사용자 에이전트 확인

공식 문서가 요구하는 API 버전과 Accept 헤더를 명시하고 요청을 식별할 User-Agent를 설정하세요. 예제가 오래됐을 때 기본 버전 변화에 휘둘리지 않게 테스트에서 응답 필드를 확인합니다.

• Accept 헤더와 API 버전 헤더 명시
• 요청 식별용 User-Agent 설정

4. 전체 목록과 변경분 수집을 구분

목록 응답의 링크 또는 페이지 정보를 따라 끝까지 수집하고 고유 ID로 중복을 제거하세요. 매번 전체 데이터를 읽기보다 수정 시각, ETag와 조건부 요청을 사용할 수 있는지 확인합니다.

• Link 헤더의 다음 페이지를 끝까지 따라가기
• ETag·조건부 요청으로 불필요한 호출 줄이기

5. 제한 응답은 헤더 기준으로 기다립니다

GitHub는 기본 제한과 별도의 보조 제한을 적용합니다. 남은 요청 수와 재설정 시각, Retry-After를 읽고 동시 호출 수를 제한하며 오류가 계속되면 자동화를 멈추고 운영자에게 알립니다.

• 남은 요청 수와 재설정 시각을 로그에 기록
• 동시 요청 수를 제한하는 큐 사용

6. 쓰기는 미리보기·검증·실행으로 나눕니다

이슈 생성, 파일 변경과 병합 전에 대상 저장소, 브랜치, 현재 SHA와 변경 내용을 확인하세요. 요청 ID를 기록하고 같은 작업이 재실행될 때 중복 이슈나 댓글이 생기지 않도록 조회 후 쓰기 규칙을 둡니다.

• 쓰기 전 대상 저장소·브랜치·현재 SHA 확인
• 같은 요청 ID로 이미 만든 이슈·댓글이 있는지 먼저 조회

7. 비밀이 있는 워크플로에서 외부 코드를 실행하지 않기

GitHub 공식 보안 문서는 신뢰하지 않는 코드와 비밀이 같은 워크플로에서 만날 때의 위험을 설명합니다. 이벤트 종류, 토큰 권한과 체크아웃 대상을 검토하고 타사 액션은 고정된 버전과 신뢰 범위로 관리하세요.

• 외부 기여 이벤트에서 비밀이 필요한 단계 분리
• 타사 액션은 커밋 SHA로 고정

자주 하는 실수

GitHub 자동화에서 가장 흔한 문제는 편의를 위해 개인 토큰에 넓은 권한을 주고 오랫동안 교체하지 않는 것입니다. 그 밖에 재실행 시 중복 이슈가 쌓이거나, 보조 제한에 걸려 자동화가 조용히 멈추는 경우도 많습니다.

• 관리자 권한 개인 토큰을 여러 자동화가 공유하기
• 재실행할 때마다 같은 이슈·댓글이 새로 생기기
• 제한 응답을 무시해 계정이 일시 차단되기
• 신뢰하지 않는 코드와 비밀을 같은 워크플로에서 실행하기

적용 예시: 주간 이슈 정리 봇

가상의 예로, 매주 월요일 오래된 이슈에 라벨을 붙이는 봇을 만든다고 해 보겠습니다. 대상 저장소 하나에 이슈 쓰기 권한만 가진 App을 설치하고, 목록 API로 열린 이슈를 끝까지 수집합니다. 라벨을 붙이기 전에 이미 같은 라벨이 있는지 확인해 중복 작업을 막고, 처리한 이슈 번호와 요청 ID를 기록합니다. 제한 헤더의 남은 요청 수가 적으면 다음 실행으로 넘기고, 오류가 반복되면 봇을 멈추고 관리자에게 알립니다.

다시 확인할 때

내용 업데이트: 2026-09-30

• GitHub App 권한을 변경하는 경우
• 새 저장소 또는 조직으로 범위를 넓히는 경우
• 쓰기 엔드포인트를 추가하는 경우

공식 자료에서 다시 확인