TL;DR: Service Account는 Google Cloud Console에서 생성하는 프로젝트 단위 가상 계정으로, 키 파일 기반 인증을 통해 CI/CD 환경에서 가장 안정적인 자동화를 제공하며, OAuth Client는 사용자 계정의 위임된 권한을 사용하지만 refresh token 관리가 필요해 장기 운영이 더 복잡하다.
Google API를 자동화 스크립트나 CI/CD 파이프라인에서 사용할 때, 인증 방식 선택은 시스템의 안정성과 운영 복잡도를 결정한다. 주요 옵션은 Service Account와 OAuth Client(Refresh Token 기반) 두 가지이며, 각각 다른 접근 모델과 트레이드오프를 가진다.
Service Account는 Google Cloud 프로젝트에 속한 가상 계정이다. Google Cloud Console의 IAM & Admin > Service Accounts 메뉴에서 생성하며, JSON 형식의 비공개 키를 발급받는다. 이 키 파일을 통해 API에 직접 인증할 수 있어, 사용자 개입 없이 자동으로 동작한다. Service Account 자체는 처음에는 아무 리소스에도 접근 권한이 없으므로, 구체적인 리소스에 명시적으로 공유(Share)해야 한다. 예를 들어 개인 Google Drive 폴더를 동기화하려면, 해당 폴더를 Service Account의 이메일 주소(예: my-sync@project-id.iam.gserviceaccount.com)와 Viewer 권한으로 공유하면 된다. Domain-wide delegation은 일반적인 개인 자동화에는 필요하지 않다.
OAuth Client는 사용자의 Google 계정을 대신하여 API를 호출하는 방식이다. Client ID와 Client Secret으로 초기 인증 흐름을 수행한 후, 장기 사용을 위해 발급받은 Refresh Token을 저장해야 한다. 이 Refresh Token으로 Access Token을 주기적으로 갱신하며 API를 호출한다. 이 방식은 사용자 계정의 정확한 권한을 그대로 사용할 수 있다는 장점이 있지만, Refresh Token의 수명(테스트 중에는 7일)과 재동의(Re-consent) 요구 가능성으로 인해 장기 자동화에서는 더 취약할 수 있다.
두 방식의 선택 기준은 사용 사례와 운영 환경에 달려 있다. GitHub Actions 같은 CI/CD 환경에서는 Service Account 키를 Secret으로 저장해 사용하는 것이 일반적으로 더 낫다. 사용자 계정과 분리되어 있으며, 토큰 갱신 문제가 없어 운영이 단순하다. 반면, 기존에 rclone 등의 도구로 이미 발급받은 OAuth Client 자격증명(Client ID, Secret, Refresh Token)이 있고 이를 재사용하려는 경우, OAuth Client 방식을 빠르게 시작할 수 있다. 그러나 장기적인 안정성을 고려한다면 Service Account로 전환하는 것이 권장된다.
인증을 설정한 후에는 API 호출에 필요한 권한 범위(Scope)를 최소한으로 제한해야 한다. Google Drive 파일을 읽기만 하는 동기화 작업의 경우 https://www.googleapis.com/auth/drive.readonly 범위면 충분하다. 이 범위는 파일 메타데이터와 콘텐츠 읽기를 모두 허용한다.
관련 항목
- GitHub Actions Secrets
- Google Drive API
- OAuth 2.0
Open questions
- 동기화 대상에 assets 폴더와 같은 이진 파일을 포함시킬지 여부
- GitHub Actions schedule 이 정각(UTC 00:00)에 집중되는 부하를 피하기 위해 실행 시간을 몇 분 정도 지연시킬지 여부