GitHub 앱에 대한 설치 액세스 토큰 생성

GitHub App에 대한 설치 액세스 토큰을 생성하는 방법을 알아봅니다.

이 문서의 내용

설치 액세스 토큰 정보

앱 설치로 인증하려면 설치 액세스 토큰을 생성해야 합니다. 앱 설치로 인증하는 방법에 대한 자세한 내용은 GitHub 앱 설치로 인증을 참조하세요.

Note

설치 액세스 토큰을 생성하는 대신 GitHub의 Octokit SDK를 사용하여 앱으로 인증할 수 있습니다. SDK는 설치 액세스 토큰 생성을 처리하고 만료되면 토큰을 다시 생성합니다. 앱 설치로 인증하는 방법에 대한 자세한 내용은 GitHub 앱 설치로 인증을 참조하세요.

설치 액세스 토큰을 안전하게 유지해야 합니다. 자세한 내용은 GitHub App을 만드는 모범 사례을(를) 참조하세요.

설치 액세스 토큰 생성

  1. 앱에 대한 JWT(JSON Web Token)를 생성합니다. 자세한 내용은 "GitHub 앱에 대한 JWT(JSON Web Token) 생성"을 참조하세요.

  2. 인증하려는 설치의 ID를 가져옵니다.

    웹후크 이벤트에 응답하는 경우 웹후크 페이로드에 설치 ID가 포함됩니다.

    REST API를 사용하여 앱 설치에 대한 ID를 찾을 수도 있습니다. 예를 들어, GET /users/{username}/installation, GET /repos/{owner}/{repo}/installation, GET /orgs/{org}/installation, GET /app/installations 엔드포인트를 사용하여 설치 ID를 가져올 수 있습니다. 자세한 내용은 "GitHub Apps에 대한 REST API 엔드포인트" 항목을 참조하세요.

    앱의 설정 페이지에서도 앱 ID를 찾을 수 있습니다. 앱 ID는 클라이언트 ID와 다릅니다. GitHub App의 설정 페이지로 이동하는 방법에 대한 자세한 내용은 "GitHub 앱 등록 수정"을(를) 참조하세요.

  3. REST API POST 요청을 /app/installations/INSTALLATION_ID/access_tokens에 보냅니다. 요청의 Authorization 헤더에 JSON Web Token을 포함합니다. INSTALLATION_ID를 인증하려는 설치의 ID로 바꿉니다.

    예를 들어 이 curl 요청을 보냅니다. INSTALLATION_ID를 설치 ID로 바꾸고 JWT를 JSON 웹 토큰으로 바꿉니다.

    curl --request POST \
--url "http(s)://HOSTNAME/api/v3/app/installations/INSTALLATION_ID/access_tokens" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer JWT" \
--header "X-GitHub-Api-Version: 2022-11-28"

    필요에 따라 repositories 또는 repository_ids 본문 매개 변수를 사용하여 설치 액세스 토큰이 액세스할 수 있는 개별 리포지토리를 지정할 수 있습니다. repositories 또는 repository_ids를 사용하여 특정 리포지토리에 대한 액세스 권한을 부여하지 않는 경우 설치 액세스 토큰은 설치에 액세스 권한이 부여된 모든 리포지토리에 액세스할 수 있습니다. 설치 액세스 토큰에는 액세스 권한이 설치에 부여되지 않은 리포지토리에 대한 액세스 권한이 부여될 수 없습니다. 최대 500개의 리포지토리를 나열할 수 있습니다.

    필요에 따라 permissions 본문 매개 변수를 사용하여 설치 액세스 토큰에 있어야 하는 권한을 지정합니다. permissions을 지정하지 않는 경우 설치 액세스 토큰에는 앱에 부여된 모든 권한이 포함됩니다. 설치 액세스 토큰은 앱에 부여되지 않은 권한을 부여할 수 없습니다.

    permissions 매개 변수를 사용하여 토큰의 액세스를 줄이는 경우 요청의 권한 수와 토큰에서 액세스할 수 있는 리포지토리 수로 인해 토큰의 복잡성이 증가합니다. 복잡성이 너무 크면 지원될 수 있는 최대 리포지토리 수를 나타내는 오류 메시지가 표시됩니다. 이 경우 permissions 매개 변수를 사용하여 더 적은 권한을 요청하거나, repositories 또는 repository_ids 매개 변수를 사용하여 더 적은 리포지토리를 요청하거나, 앱을 조직의 all 리포지토리에 설치해야 합니다.

    응답에는 설치 액세스 토큰, 토큰 만료 날짜, 토큰의 사용 권한 및 토큰이 액세스할 수 있는 리포지토리가 포함됩니다. 설치 액세스 토큰은 1시간 후에 만료됩니다.

    엔드포인트에 대한 자세한 내용은 “GitHub Apps에 대한 REST API 엔드포인트”을 참조하세요.

    Note

    대부분의 경우 Authorization: Bearer 또는 Authorization: token을 사용하여 전달할 수 있습니다. 그러나 JWT(JSON 웹 토큰)를 전달하는 경우 Authorization: Bearer를 사용해야 합니다.