GitHub 앱 설치로 인증

GitHub App 설치 인증 정보

GitHub App이(가) 계정에 설치되면 API 요청에 대한 앱 설치로 인증할 수 있습니다. 이렇게 하면 필요한 리포지토리 액세스 및 권한이 부여된 앱이 해당 설치에서 소유한 리소스에 액세스할 수 있습니다. 앱 설치에 의한 API 요청은 앱에 배정됩니다. GitHub 앱 설치에 대한 자세한 내용은 "GitHub 앱 설치" 를 참조하세요.

예를 들어 앱이 "octo-org"라는 조직이 소유한 프로젝트에서 Status 이슈 필드를 변경하려면 앱의 octo-org 설치로 인증합니다. 이슈의 타임라인에서 앱이 상태를 업데이트했음을 명시할 것입니다.

설치로 API 요청을 하려면 먼저 설치 액세스 토큰을 생성해야 합니다. 그런 다음, 후속 API 요청의 Authorization 헤더에 설치 액세스 토큰을 보냅니다. 설치 액세스 토큰을 생성할 수 있는 GitHub의 Octokit SDK를 사용할 수도 있습니다.

일부 REST API 엔드포인트는 설치 액세스 토큰을 수락하지 않으며 대부분의 REST API 엔드포인트는 앱에 엔드포인트를 사용할 특정 권한이 있어야 합니다. REST API 엔드포인트가 설치 액세스 토큰을 수락하는지 여부 및 필요한 사용 권한을 확인하려면 엔드포인트에 대한 설명서를 참조하세요.

앱 설치는 GraphQL API를 사용할 수도 있습니다. REST API와 마찬가지로 앱에는 GraphQL API의 개체에 액세스할 수 있는 특정한 권한이 있어야 합니다. GraphQL 요청의 경우 앱에 만들려는 GraphQL 쿼리 및 변형에 필요한 권한이 있는지 테스트해야 합니다.

설치 액세스 토큰을 사용하여 HTTP 기반 Git 액세스를 인증할 수도 있습니다. 앱에 "콘텐츠" 리포지토리 권한이 있어야 합니다. 그런 다음 설치 액세스 토큰을 HTTP 암호로 사용합니다. TOKEN을(를) git clone https://x-access-token:TOKEN@github.com/owner/repo.git 설치 액세스 토큰으로 바꿉니다.

설치 액세스 토큰을 사용하여 수행한 요청을 "서버 간" 요청이라고도 합니다.

앱 설치 대신 사용자를 대신하여 앱으로 인증하는 방법에 대한 자세한 내용은 "사용자를 대신하여 GitHub 앱으로 인증"을 참조하세요.

설치 액세스 토큰을 사용하여 앱 설치로 인증

설치 액세스 토큰을 사용하여 설치로 인증하려면 먼저 REST API를 사용하여 설치 액세스 토큰을 생성합니다. 그런 다음 REST API 또는 GraphQL API 요청의 Authorization 헤더에서 해당 설치 액세스 토큰을 사용합니다. 설치 액세스 토큰은 1시간 후에 만료됩니다.

설치 액세스 토큰 생성

앱에 대한 JWT(JSON Web Token)를 생성합니다. 자세한 내용은 "GitHub 앱에 대한 JWT(JSON Web Token) 생성"을 참조하세요.
인증하려는 설치의 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 앱 등록 수정"을(를) 참조하세요.
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를 사용해야 합니다.

설치 액세스 토큰을 사용하여 인증

설치 액세스 토큰을 사용하여 인증하려면 API 요청의 Authorization 헤더에 포함합니다. 액세스 토큰은 GraphQL API와 REST API 모두에서 작동합니다.

앱에는 엔드포인트를 사용하는 데 필요한 권한이 있어야 합니다. 자세한 내용은 "GitHub 앱의 권한 선택"을(를) 참조하세요.

다음 예제에서는 INSTALLATION_ACCESS_TOKEN을(를) 설치 액세스 토큰으로 바꿉니다.

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/meta" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

Octokit.js SDK를 사용하여 앱 설치로 인증

GitHub의 Octokit.js SDK 를 사용하여 앱 설치로 인증할 수 있습니다. SDK를 사용하여 인증하는 것의 한 가지 이점은 JWT(JSON Web Token) 을(를) 직접 생성할 필요가 없다는 것입니다. 또한 SDK는 설치 액세스 토큰을 다시 생성하므로 1시간 만료에 대해 걱정할 필요가 없습니다.

참고: Octokit.js 라이브러리를 사용하려면 octokit을(를) 설치하고 가져와야 합니다. 다음 예제에서는 ES6에 따라 import 문을 사용합니다. 다양한 설치 및 가져오기 방법에 대한 자세한 내용은 Octokit.js 추가 정보 사용 섹션 을 참조하세요.

Octokit.js 를 사용하여 설치 ID로 인증

GitHub App용 ID를 받습니다. GitHub App의 설정 페이지에서 앱의 ID를 찾을 수 있습니다. GitHub App의 설정 페이지로 이동하는 방법에 대한 자세한 내용은 "GitHub 앱 등록 수정"을 참조하세요.
프라이빗 키를 생성합니다. 자세한 내용은 "GitHub 앱에 대한 프라이빗 키 관리"을 참조하세요.
인증하려는 설치의 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 엔드포인트"을(를) 참조하세요.
octokit에서 App을 가져옵니다. App 의 새 인스턴스를 만듭니다. 다음 예제에서는 APP_ID을 앱 ID에 대한 참조로 바꿉니다. 앱의 프라이빗 키에 대한 참조로 대체 PRIVATE_KEY 합니다.
JavaScript
```
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
});
```
```
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
});
```
이 getInstallationOctokit 메서드를 사용하여 인증된 octokit 인스턴스를 만듭니다. 다음 예제에서는 INSTALLATION_ID을(를) 대신 인증하려는 앱 설치의 ID로 바꿉니다.
JavaScript
```
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
```
```
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
```
octokit 메서드를 사용하여 API에 요청합니다.

앱에는 엔드포인트를 사용하는 데 필요한 권한이 있어야 합니다. 자세한 내용은 "GitHub 앱의 권한 선택"을(를) 참조하세요.

예를 들어 GraphQL API를 요청하려면 다음을 수행합니다.
JavaScript
```
await octokit.graphql(`
  query {
    viewer {
      login
    }
  }
  `)
```
```
await octokit.graphql(`
  query {
    viewer {
      login
    }
  }
  `)
```
예를 들어 REST API를 요청하려면 다음을 수행합니다.
JavaScript
```
await octokit.request("GET /meta")
```
```
await octokit.request("GET /meta")
```

Octokit.js 를 사용하여 웹후크 이벤트에 대한 응답으로 인증

또한 Octokit.js SDK는 미리 인증된 octokit 인스턴스를 웹후크 이벤트 처리기에 전달합니다.

GitHub App용 ID를 받습니다. GitHub App의 설정 페이지에서 앱의 ID를 찾을 수 있습니다. GitHub App의 설정 페이지로 이동하는 방법에 대한 자세한 내용은 "GitHub 앱 등록 수정"을 참조하세요.
프라이빗 키를 생성합니다. 자세한 내용은 "GitHub 앱에 대한 프라이빗 키 관리"을 참조하세요.
앱 설정에서 지정한 웹후크 비밀을 가져옵니다. 웹후크 비밀에 대한 자세한 내용은 "GitHub 앱에 웹후크 사용"을(를) 참조하세요.
octokit에서 App을 가져옵니다. App 의 새 인스턴스를 만듭니다. 다음 예제에서는 APP_ID을 앱 ID에 대한 참조로 바꿉니다. 앱의 프라이빗 키에 대한 참조로 대체 PRIVATE_KEY 합니다. WEBHOOK_SECRET을(를) 앱의 웹후크 비밀로 바꿉니다.
JavaScript
```
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
  webhooks: { WEBHOOK_SECRET },
});
```
```
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
  webhooks: { WEBHOOK_SECRET },
});
```

app.webhooks.* 메서드를 사용하여 웹후크 이벤트를 처리합니다. 자세한 내용은 Octokit.js 추가 정보 웹후크 섹션 을 참조하세요. 예를 들어 이슈가 열릴 때 이슈에 대한 주석을 만들려면 다음을 수행합니다.

app.webhooks.on("issues.opened", ({ octokit, payload }) => {
  await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", {
      owner: payload.repository.owner.login,
      repo: payload.repository.name,
      issue_number: payload.issue.number,
      body: `This is a bot post in response to this issue being opened.`,
      headers: {
        "x-github-api-version": "2022-11-28",
      },
    }
  )
});

이 문서의 내용