Google API를 자동화 스크립트나 CI/CD 파이프라인에서 사용할 때 적절한 인증 방식을 선택하는 기준은 접근 대상 리소스의 소유권과 운영 환경의 제약에 있습니다. 간단히 말해, ‘접근 대상’이 개인 리소스인지 조직 리소스인지, 그리고 ‘운영 환경’이 CI인지 로컬인지에 따라 결정됩니다. 서비스 계정은 CI 자동화에, OAuth 클라이언트는 개인 계정 리소스 직접 접근에 적합합니다.
서비스 계정은 Google Cloud 프로젝트 내 생성된 가상 계정으로, 사람 계정과 독립된 자체 신원입니다. 이 방식은 GitHub Actions, Jenkins 같은 CI 환경에서 Google 리소스(예: 특정 Drive 폴더)에 안정적으로 접근해야 할 때 적합합니다. JSON 키 파일을 사용해 API 호출에 서명하며, 리프레시 토큰이나 브라우저 승인 흐름이 필요 없습니다. 단, 서비스 계정 자체의 Drive는 비어 있으므로, 접근하려는 폴더나 파일을 사람 계정이 명시적으로 서비스 계정 이메일에 ‘공유’해야 합니다. 장점은 CI/CD와 궁합이 좋고 장기 자동화에서 토큰 만료 관리가 필요 없다는 것이며, 단점은 공유 설정이 추가로 필요하고 공유되지 않은 개인 Drive 영역에는 접근할 수 없다는 점입니다.
OAuth 2.0 클라이언트는 특정 Google 사용자 계정을 대신하여 API를 호출하는 권한을 위임받습니다. 스크립트가 특정 개인 사용자의 전체 Drive 리소스(예: ‘내 Drive’ 루트)에 접근해야 할 때, 또는 로컬 개발 환경에서 일회성 인증이 가능할 때 적합합니다. 클라이언트 ID와 시크릿, 그리고 초기 승인을 통해 얻은 리프레시 토큰을 사용하며, 리프레시 토큰이 있어야 Access Token을 장기간 갱신할 수 있습니다. 승인 시 부여된 스코프 내에서 해당 사용자의 리소스에 직접 접근하므로 별도의 공유 설정이 필요 없습니다. 사용자 계정의 권한을 그대로 활용할 수 있어 접근 범위 설정이 직관적이라는 장점이 있지만, 리프레시 토큰 관리가 필요하며 OAuth 동의 화면 상태(예: ‘테스트 중’ 모드)에 따라 토큰이 7일 후 만료될 수 있어 장기 CI 운영에는 불안정할 수 있습니다.
워크로드 아이덴티티 연동은 외부 자격 증명(예: GitHub Actions의 OIDC 토큰)을 Google Cloud 자격 증명으로 변환합니다. 서비스 계정 키 파일을 CI 환경에 저장하지 않고 최고 수준의 보안을 확보해야 할 때 적합합니다. GitHub Actions 워크플로우가 자체 JWT를 생성하면 Google Cloud가 이를 신뢰하고 임시 서비스 계정 자격 증명을 발급합니다. 장점은 장기적인 키 파일 관리 부담과 유출 위험을 제거하는 것이며, 단점은 Google Cloud와 CI 공급자 양쪽 설정이 복잡하고 ‘세팅 쉬운 방법’의 범위를 벗어난다는 점입니다.
방식 선택은 몇 가지 질문을 따라 결정할 수 있습니다. 첫째, 대상 리소스가 특정 개인 사용자의 ‘내 Drive’ 전체라면 OAuth 클라이언트를 선택합니다. 둘째, 대상이 특정 폴더이며 CI 환경에서 안정적으로 실행되어야 한다면 서비스 계정을 사용하고 폴더를 공유해야 합니다. 셋째, 이미 rclone 등의 도구로 OAuth 리프레시 토큰을 보유 중이라면 해당 토큰을 재사용하는 OAuth 클라이언트 방식으로 빠르게 시작할 수 있습니다. 단, 토큰의 스코프(drive.readonly 등)와 유효성을 확인해야 합니다. 넷째, 보안 요구사항이 매우 높고 설정 복잡도를 감수할 수 있다면 워크로드 아이덴티티 연동을 고려합니다.
GitHub Actions에서 개인 문서 동기화를 구현하는 맥락에서는 대상 폴더를 명확히 지정할 수 있으므로 운영 복잡도와 안정성 면에서 서비스 계정이 권장됩니다. OAuth 리프레시 토큰을 이미 보유하고 있다면 이를 재사용하는 것도 유효한 출발점이 될 수 있습니다.
관련 항목으로는 GitHub Actions cron 작업, Google Drive API changes.list, OAuth 2.0 리프레시 토큰이 있습니다. 확인이 필요한 사항으로는 사용자가 보유한 rclone 구성에 리프레시 토큰이 실제로 포함되어 있는지, 그리고 해당 토큰의 스코프가 drive.readonly 이상인지 확인이 필요합니다.