Skip to main content

GitHub 앱의 권한 선택

GitHub 앱의 권한은 앱이 GitHub의 API로 수행할 수 있는 작업과 앱이 받을 수 있는 웹후크를 결정합니다.

GitHub App 권한 정보

GitHub Apps에는 기본적으로 사용 권한이 없습니다. GitHub App을 등록할 때 앱에 대한 권한을 선택할 수 있습니다. 선택한 권한은 앱이 GitHub의 API로 수행할 수 있는 작업과 앱이 구독할 수 있는 웹후크를 결정합니다. 앱에 필요한 최소 권한을 선택해야 합니다.

GitHub Apps에는 기본적으로 권한이 없지만 사용자를 대신하여 작업할 때 공용 리소스를 읽을 수 있는 암시적 권한이 있습니다. 사용자가 앱을 대신하여 작동하도록 권한을 부여하면 GitHub App에서 결과 사용자 액세스 토큰을 사용하여 REST API 및 GraphQL API에 대한 요청을 만들어 공용 리소스를 읽을 수 있습니다. 사용자를 대신하여 작동하는 방법에 대한 자세한 내용은 "사용자를 대신하여 GitHub 앱으로 인증"을(를) 참조하세요.

앱 권한은 리포지토리, 조직 또는 계정 권한으로 분류됩니다. 리포지토리 권한을 사용하면 앱이 설치된 계정에서 소유한 리포지토리와 관련된 리소스에 액세스할 수 있습니다. 조직 권한을 사용하면 앱이 조직 계정에 설치된 경우 앱이 설치된 조직과 관련된 리소스에 액세스할 수 있습니다. 계정 권한을 사용하면 사용자가 앱에 권한을 부여한 경우 앱이 사용자와 관련된 리소스에 액세스할 수 있습니다. 앱의 사용자 권한 부여에 대한 자세한 내용은 "사용자를 대신하여 GitHub 앱으로 인증"을(를) 참조하세요.

사용자가 자신의 계정 또는 조직에 앱을 설치할 때 앱이 요청한 리포지토리 및 조직 권한을 보고 부여합니다. 또한 앱이 개별 사용자에 대해 요청할 수 있는 계정 권한 목록도 표시됩니다. 사용자가 앱을 대신하여 작동하도록 권한을 부여하면 앱이 요청한 계정 권한을 보고 부여합니다.

사용자 액세스 토큰을 사용한 API 요청의 성공 횟수는 사용자의 권한과 앱의 권한에 따라 달라집니다. 예를 들어 앱에 리포지토리의 콘텐츠를 쓸 수 있는 권한이 부여되었지만 사용자가 콘텐츠를 읽기만 할 수 있는 경우, 사용자 액세스 토큰은 콘텐츠만 읽을 수 있습니다. 설치 액세스 토큰을 사용한 API 요청의 성공 횟수는 앱의 권한에 따라 달라집니다.

언제든지 앱에 대한 권한을 수정할 수 있습니다. 사용 권한을 수정하면 앱이 설치된 각 계정의 소유자에게 새 사용 권한을 승인하라는 메시지가 표시됩니다. 계정 소유자가 새 사용 권한을 승인하지 않으면 해당 설치에서 이전 사용 권한을 계속 사용합니다.

일부 웹후크 및 API 액세스에는 "관리자" 권한이 필요합니다. 앱에 "관리자" 권한이 필요한 경우 앱 홈페이지에서 이 요구 사항을 설명하는 것이 좋습니다. 이렇게 하면 사용자가 앱에 높은 수준의 권한이 필요한 이유를 이해하는 데 도움이 됩니다.

GitHub App 등록 시에 권한을 지정하는 방법에 대한 자세한 내용은 "GitHub 앱 등록"을(를) 참조하세요. 권한 수정에 대한 자세한 내용은 "GitHub 앱 등록 수정"을(를) 참조하세요.

웹후크 액세스 권한 선택

웹후크 설명서는 각 웹후크를 GitHub Apps에 사용할 수 있는지 여부를 나타냅니다. 구독하려는 각 웹후크에 대해 웹후크 설명서를 참조하여 GitHub App이(가) 해당 웹후크를 구독하는 데 필요한 권한을 확인합니다. 자세한 내용은 "웹후크 이벤트 및 페이로드"을(를) 참조하세요.

예를 들어 앱이 team 이벤트를 구독하도록 하려면 앱에 "멤버" 조직 권한이 있어야 합니다.

GitHub App 등록 페이지에서 앱의 권한을 변경하면 사용 가능한 웹후크 이벤트가 변경됩니다. GitHub App이(가) 이벤트를 구독할 수 있는 충분한 권한을 선택하지 않은 경우 이벤트는 앱 등록 페이지에 옵션으로 표시되지 않습니다.

REST API 액세스에 대한 권한 선택

각 엔드포인트에 대한 REST API 참조 문서는 엔드포인트가 GitHub Apps에서 작동하는지 여부 및 앱이 엔드포인트를 사용하기 위해 필요한 권한을 명시합니다. 일부 엔드포인트에는 여러 권한이 필요할 수 있으며 일부 엔드포인트에는 여러 권한 중 하나가 필요할 수 있습니다. GitHub App에서 각 권한으로 액세스할 수 있는 REST API 엔드포인트에 대한 자세한 내용은 “GitHub 앱에 필요한 권한”을 참조하세요.

예를 들어 GET /orgs/{org}/dependabot/secrets 엔드포인트를 사용하려면 앱에 "조직 종속성 비밀" 권한에 대한 읽기 수준 이상의 권한이 있어야 합니다.

앱이 권한이 부족한 REST API 요청을 만드는 경우 API는 403 응답을 반환합니다.

올바른 사용 권한을 선택하는 데 도움이 되도록 REST API 응답에서 X-Accepted-GitHub-Permissions 헤더를 받게 됩니다. 헤더는 엔드포인트에 액세스하는 데 필요한 권한을 알려줍니다. 자세한 내용은 "REST API 문제 해결"을(를) 참조하세요.

GraphQL API 액세스 권한 선택

GraphQL 요청의 경우 앱을 테스트하여 만들려는 GraphQL 쿼리 및 변형에 필요한 권한이 있는지 확인해야 합니다.

앱이 권한이 부족한 GraphQL API 쿼리 또는 변형을 만드는 경우 API는 401 응답을 반환합니다.

Git 액세스 권한 선택

앱이 설치 또는 사용자 액세스 토큰을 사용하여 HTTP 기반 Git 액세스를 인증하도록 하려면 "콘텐츠" 리포지토리 권한을 요청해야 합니다. 앱이 .github/workflows 디렉터리에서 Actions 파일을 액세스하거나 편집해야 하는 경우 "워크플로" 리포지토리 권한을 요청합니다.

그러면 액세스 토큰을 HTTP 암호로 사용할 수 있습니다. TOKEN을 이 액세스 토큰으로 바꿉니다.

git clone https://x-access-token:TOKEN@github.com/owner/repo.git