OAuth 앱을 GitHub 앱으로 마이그레이션

OAuth app를 GitHub App(으)로 마이그레이션할 때의 이점과 OAuth app를 마이그레이션하는 방법을 알아보세요.

이 기사에서

OAuth apps에서 GitHub Apps(으)로 마이그레이션할 때의 이점

GitHub Apps은 GitHub와 통합하는 권장 방법입니다. GitHub Apps은 다음을 포함하여 많은 이점을 제공합니다.OAuth apps

  • 세분화된 사용 권한, 리포지토리 액세스에 대한 선택 및 단기 실행 토큰과 같은 향상된 보안 기능
  • 사용자와 독립적으로 또는 사용자를 대신하여 작업할 수 있는 기능
  • 확장 가능한 속도 제한
  • 기본 제공 웹후크

자세한 내용은 GitHub 앱 만들기 정보을(를) 참조하세요.

OAuth app를 GitHub App로 변환

다음 단계에서는 OAuth app에서 GitHub App(으)로 마이그레이션하는 방법에 대한 개요를 제공합니다. 특정 단계는 앱에 따라 달라집니다.

1. OAuth app을(를) 검토하세요

OAuth app의 코드를 다시 숙지하세요. OAuth app이(가) 수행하는 API 요청은 GitHub App에 대해 어떤 권한을 선택할지 결정하는 데 도움이 됩니다.

또한 OAuth apps에서 사용할 수 없는 몇 가지 REST API 엔드포인트가 있습니다. GitHub 앱 설치 액세스 토큰에 사용할 수 있는 엔드포인트을 검토하여 사용 중인 모든 REST 엔드포인트를 GitHub Apps에서 사용할 수 있는지 확인합니다.

2. GitHub App 등록

새 GitHub App를 등록합니다. 자세한 내용은 GitHub 앱 등록을(를) 참조하세요.

OAuth app에 비해 GitHub App 설정을 더 많이 제어할 수 있습니다. 몇 가지 주요 추가 사항은 다음과 같습니다.

  • 항상 사용자를 대신해 동작하는 OAuth app와 달리, GitHub App가 자체적으로 또는 사용자를 대신해 작업을 수행하도록 할 수 있습니다. 새 GitHub App 사용자가 사용자를 대신하여 작업을 수행하지 않도록 하려면 "사용자 식별 및 권한 부여" 설정을 건너뛸 수 있습니다. 자세한 내용은 GitHub 앱을 사용한 인증 정보을(를) 참조하세요.

  • 웹후크를 사용해 특정 이벤트가 발생하면 GitHub App에 알릴 수 있습니다. 각 리포지토리 또는 조직마다 OAuth apps의 API를 통해 구성해야 하는 웹후크와 달리, GitHub Apps에는 웹후크 기능이 기본으로 내장되어 있습니다. GitHub App를 등록할 때 수신하려는 웹후크 이벤트를 선택할 수 있습니다. 또한 현재 OAuth app에서 이벤트가 발생했는지 확인하기 위해 폴링을 사용하고 있다면, GitHub App가 속도 제한을 준수할 수 있도록 대신 웹훅을 구독하는 것을 고려해 보세요. 자세한 내용은 GitHub 앱에서 웹후크 사용을(를) 참조하세요.

  • OAuth app를 사용하면 사용자가 앱을 승인할 때 범위를 요청합니다. 를 사용하여 GitHub App앱 설정에서 사용 권한을 지정합니다. 이러한 권한은 범위보다 세분화되어 있으며 앱에 필요한 권한만 선택할 수 있도록 합니다. 또한 이러한 권한은 REST API 엔드포인트 및 웹후크 이벤트에 매핑되므로 특정 REST API 엔드포인트에 액세스하거나 특정 웹후크를 구독하기 위해 필요한 권한을 GitHub App 쉽게 결정할 수 있습니다. GraphQL 요청에 대한 사용 권한은 현재 문서화되어 있지 않습니다. 자세한 내용은 GitHub 앱에 대한 권한 선택을(를) 참조하세요.

3. 앱의 코드 수정

GitHub App을(를) 등록한 후에는 이전 OAuth app의 코드를 새 GitHub App에서 작동하도록 조정합니다.

인증 업데이트

앱 코드가 사용자의 GitHub App에 대한 API 인증을 처리할 수 있도록 업데이트해야 합니다. GitHub App는 세 가지 방법으로 인증할 수 있습니다.

  • 앱 자체의 자격으로 GitHub App 등록에 대한 세부 정보를 가져오거나 수정하거나 설치 액세스 토큰을 생성하기 위해. 자세한 내용은 GitHub 앱으로 인증을(를) 참조하세요.
  • 앱 설치로서, 스스로를 대신하여 작업을 수행하기 위해서입니다. 자세한 내용은 GitHub 앱 설치로 인증을(를) 참조하세요.
  • 사용자를 대신하여 사용자에게 작업을 할당합니다. 자세한 내용은 사용자를 대신하여 GitHub 앱으로 인증을(를) 참조하세요.

'의 공식 Octokit.js 라이브러리를 사용하는 GitHub경우 기본 제공 App 개체를 사용하여 인증할 수 있습니다. 예는 REST API 및 JavaScript를 사용하여 스크립팅 및 웹후크 이벤트에 응답하는 GitHub 앱 빌드을(를) 참조하세요.

비율 한도 검토

속도 제한의 차이점을 검토합니다 OAuth appsGitHub Apps. GitHub Apps 리포지토리 수와 조직의 사용자 수에 따라 증가할 수 있는 속도 제한에 슬라이딩 규칙을 사용합니다. 자세한 내용은 GitHub 앱에 대한 속도 제한을(를) 참조하세요.

가능하다면, 폴링 대신 조건부 요청을 사용하고 웹훅을 구독하여 속도 제한 내에서 작업을 유지하는 것을 고려하세요. 조건부 요청에 대한 자세한 내용은 REST API 사용에 대한 모범 사례을(를) 참조하세요. 웹후크를 사용하는 방법에 대한 자세한 내용은 GitHub App 및 GitHub 앱에서 웹후크 사용을 참조하세요.

코드 테스트

새 GitHub App 코드를 테스트하여 코드가 예상대로 작동하는지 확인합니다.

4. 새 GitHub App 알리기

다른 계정에서 새 GitHub App계정을 사용할 수 있도록 하려면 앱이 공개되어 있는지 확인합니다.자세한 내용은 을 참조 하세요.

5. 사용자에게 마이그레이션 지시

새 GitHub App 항목이 준비되면 이전 OAuth app 사용자에게 새 GitHub App사용자로 마이그레이션하도록 지시합니다. 사용자를 자동으로 마이그레이션하는 방법은 없습니다. 각 사용자는 귀하의 GitHub App를 각자 직접 설치 및/또는 승인해야 합니다.

앱 소유자는 사용자가 새 GitHub App 항목을 설치/승인하고 이전 OAuth app버전에 대한 권한 부여를 취소하도록 권장하는 작업 호출을 포함해야 합니다. 설명서 또는 사용자 인터페이스 요소도 업데이트해야 합니다.

사용자에게 귀하의 GitHub App 설치를 권장합니다.

GitHub App가 자체적으로 API 요청을 보내거나 조직 또는 리포지토리 리소스에 액세스하게 하려면 사용자가 귀하의 GitHub App를 설치해야 합니다. 사용자가 계정 또는 조직에 설치 GitHub App 할 때 앱이 액세스할 수 있는 리포지토리를 선택하고 앱에 요청한 조직 및 리포지토리 권한을 부여합니다.

사용자가 GitHub App를 설치할 수 있도록 돕기 위해 사용자가 클릭해 GitHub App를 설치할 수 있는 링크를 앱의 웹페이지에 추가할 수 있습니다. 설치 URL의 형식은 http(s)://HOSTNAME/github-apps/YOUR_APP_NAME/installations/new와 같습니다. GitHub App의 설정 페이지에 있는 "공개 링크" 필드에서 찾을 수 있는 GitHub App의 슬러그화된 이름으로 YOUR_APP_NAME을 바꾸세요.

OAuth app가 액세스할 수 있었던 리포지토리를 미리 선택하려면 설치 URL에 /permissions 및 쿼리 매개 변수를 추가하면 됩니다. 이렇게 하면 사용자가 귀하의 GitHub App에 귀하의 OAuth app이 이미 액세스할 수 있는 리포지토리에 대한 액세스 권한을 부여할 수 있습니다. 쿼리 매개 변수는 다음과 같습니다.

  • suggested_target_id: 를 설치하는 GitHub App사용자 또는 조직의 ID입니다. 이 매개 변수는 필수입니다.
  • repository_ids[]: 설치를 위해 선택할 리포지토리 ID입니다. 생략되는 경우 모든 리포지토리를 선택합니다. 미리 선택할 수 있는 최대 리포지토리 수는 100개입니다. 사용자의 OAuth app가 액세스할 수 있는 리포지토리 목록을 가져오려면 인증된 사용자의 리포지토리 나열 및 조직 리포지토리 나열 엔드포인트를 사용하세요.

예: http(s)://HOSTNAME/github-apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID.

GitHub Apps 설치에 대한 자세한 내용은 타사로부터 GitHub 앱 설치하기 및 고유한 GitHub 앱 설치을 참조하세요.

사용자에게 앱 사용을 승인하라는 프롬프트 표시

사용자를 대신하여 API 요청을 하려면 GitHub App 사용자가 앱에 권한을 부여해야 합니다. 사용자가 앱에 권한을 부여하면 앱이 대신 사용할 수 있는 권한을 부여하고 앱에서 요청한 계정 권한을 부여합니다. 앱이 조직 계정에 설치된 경우 해당 조직 내의 각 사용자는 앱이 대신 작동하도록 앱에 권한을 부여해야 합니다.

사용자에게 앱에 권한을 부여하라는 프롬프트를 표시하려면 웹 애플리케이션 흐름 또는 디바이스 흐름을 통해 사용자를 안내합니다. 자세한 내용은 GitHub 앱에 대한 사용자 액세스 토큰 생성을(를) 참조하세요.

권한 부여에 대한 자세한 내용은 GitHub Apps을 참조하세요.

사용자에게 OAuth app 액세스 권한을 취소하도록 권장

또한 사용자가 이전 OAuth app액세스 권한을 취소하도록 권장해야 합니다. 이렇게 하면 OAuth app에서 완전히 벗어날 수 있으며, 사용자 데이터의 보안을 유지하는 데 도움이 됩니다. 자세한 내용은 권한 있는 OAuth 앱 검토을(를) 참조하세요.

인터페이스 또는 설명서 업데이트

앱과 관련된 모든 사용자 인터페이스나 설명서가 OAuth app에서 GitHub App로의 변경 사항을 반영하도록 업데이트해야 합니다.

6. 이전 OAuth app의 웹후크 제거

사용자가 귀하의 GitHub App를 설치하고 리포지토리에 대한 액세스 권한을 부여하면 이전 OAuth app의 웹후크를 제거해야 합니다. 새 GitHub App 사용자와 이전 OAuth app 사용자가 동일한 이벤트에 대한 웹후크에 응답하는 경우 사용자는 중복 동작을 관찰할 수 있습니다.

리포지토리 웹후크를 제거하려면 installation_repositories 작업으로 added 웹후크를 수신 대기 할 수 있습니다. 사용자의 GitHub App가 해당 이벤트를 수신하면, REST API를 사용하여 사용자의 OAuth app에 대해 해당 리포지토리들에서 웹후크를 삭제할 수 있습니다. 자세한 내용은 웹후크 이벤트 및 페이로드 및 리포지토리 웹후크에 대한 REST API 엔드포인트을(를) 참조하세요.

마찬가지로 조직 웹후크를 제거하려면 installation 작업으로 created 웹후크를 수신 대기 할 수 있습니다. 회원님의 GitHub App이(가) 조직에 대한 해당 이벤트를 수신하면 REST API를 사용하여 해당 조직의 웹훅과 회원님의 OAuth app에 해당하는 리포지토리에서 웹훅을 삭제할 수 있습니다. 자세한 내용은 웹후크 이벤트 및 페이로드, 조직 웹후크에 대한 REST API 엔드포인트, 리포지토리 웹후크에 대한 REST API 엔드포인트을(를) 참조하세요.

7. 이전 OAuth app을(를) 삭제하세요

사용자가 새 GitHub App사용자로 마이그레이션되면 이전 OAuth app을 삭제해야 합니다. 이렇게 하면 OAuth app의 자격 증명이 남용되는 것을 방지하는 데 도움이 됩니다. 이 작업을 수행하면 OAuth app의 남아 있는 모든 권한도 취소됩니다. 자세한 내용은 OAuth 앱 삭제을(를) 참조하세요. 귀하의 OAuth app이(가) GitHub Marketplace에 등록되어 있는 경우, 먼저 마켓플레이스에서 앱을 제거하려면 GitHub 지원에 문의해야 할 수 있습니다.