매니페스트에서 GitHub 앱 등록

GitHub 앱 매니페스트 정보

누군가 매니페스트에서 GitHub 앱을 등록하는 경우 URL을 따르고 앱 이름을 지정하면 됩니다. 매니페스트에는 앱을 자동으로 등록하는 데 필요한 권한, 이벤트 및 웹후크 URL이 포함됩니다. 매니페스트 흐름은 GitHub 앱 등록을 만들고 앱의 웹후크 비밀, 프라이빗 키(PEM 파일), 클라이언트 암호, GitHub 앱 ID를 생성합니다. 매니페스트에서 GitHub App 등록을 만드는 사람은 GitHub App 등록을 소유하게 되며 등록 설정을 편집하거나, 삭제하거나, GitHub의 다른 사람에게 전송하도록 선택할 수 있습니다.

Probot을 사용하여 GitHub 앱 매니페스트를 시작하거나 예제 구현을 볼 수 있습니다. 자세한 내용은 "Probot을 사용하여 GitHub 앱 매니페스트 흐름 구현"을 참조하세요.

다음은 GitHub 앱 매니페스트를 사용하여 미리 구성된 앱을 등록할 수 있는 몇 가지 시나리오입니다.

GitHub 앱을 개발할 때 새 팀 멤버가 빠르게 최신 정보를 갖출 수 있도록 돕습니다.
다른 사용자가 앱을 구성할 필요 없이 GitHub API를 사용하여 GitHub 앱을 확장하도록 허용합니다.
GitHub 커뮤니티와 공유할 GitHub 앱 참조 디자인을 만듭니다.
동일한 구성을 사용하여 개발 및 프로덕션 환경에 GitHub 앱을 배포해야 합니다.
GitHub 앱 구성의 수정 버전을 추적합니다.

GitHub 앱 매니페스트 흐름 구현

GitHub 앱 매니페스트 흐름은 OAuth 흐름과 유사한 핸드셰이크 프로세스를 사용합니다. 흐름은 매니페스트를 사용하여 GitHub 앱을 등록하고 앱의 프라이빗 키, 웹후크 비밀, ID를 검색하는 데 사용되는 임시 code를 받습니다.

참고: 1시간 내에 GitHub 앱 매니페스트 흐름의 세 단계를 모두 완료해야 합니다.

다음 단계에 따라 GitHub 앱 매니페스트 흐름을 구현합니다.

새 GitHub 앱을 등록하도록 사용자를 GitHub로 리디렉션합니다.
GitHub는 사용자를 사이트로 다시 리디렉션합니다.
임시 코드를 교환하여 앱 구성을 검색합니다.

1. 새 GitHub 앱을 등록하도록 사용자를 GitHub로 리디렉션

새 GitHub 앱을 등록하도록 사용자를 리디렉션하려면 POST 요청을 https://github.com/settings/apps/new(개인 계정) 또는 https://github.com/organizations/ORGANIZATION/settings/apps/new(조직 계정)로 보내는 클릭 가능한 링크를 제공하고 ORGANIZATION을 앱을 등록할 조직 계정의 이름으로 바꿉니다.

GitHub 앱 매니페스트 매개 변수를 JSON으로 인코딩된 문자열로 manifest 매개 변수에 포함해야 합니다. 추가 보안을 위해 state 매개 변수를 포함할 수도 있습니다.

앱을 등록하는 사용자는 manifest 매개 변수에 포함한 앱의 이름을 편집할 수 있는 입력 필드가 있는 GitHub 페이지로 리디렉션됩니다. name을 manifest에 포함하지 않는 경우 이 필드에서 앱의 고유한 이름을 설정할 수 있습니다.

GitHub 앱 매니페스트 매개 변수

속성	형식	설명
`name`	`string`	GitHub App의 이름입니다.
`url`	`string`	필수입니다. GitHub App의 홈페이지입니다.
`hook_attributes`	`object`	GitHub App 웹후크의 구성입니다.
`redirect_url`	`string`	사용자가 매니페스트에서 GitHub App 등록을 시작한 후 리디렉션할 전체 URL입니다.
`callback_urls`	`array of strings`	다른 사람이 설치 권한을 부여한 후 리디렉션할 전체 URL입니다. 최대 10개의 콜백 URL을 제공할 수 있습니다.
`setup_url`	`string`	추가 설정이 필요한 경우 사용자가 GitHub App을(를) 설치한 후 사용자를 리디렉션할 전체 URL입니다.
`description`	`string`	GitHub App에 대한 설명입니다.
`public`	`boolean`	GitHub App을 누구나 사용할 수 있는 경우 `true`로 설정하고 앱 소유자만 액세스할 수 있는 경우 `false`로 설정합니다.
`default_events`	`array`	GitHub App이(가) 구독하는 이벤트 목록입니다.
`default_permissions`	`object`	GitHub 앱에 필요한 권한 세트입니다. 개체 형식은 키에 권한 이름(예 `issues`)을 사용하고 값에 액세스 형식(예: `write`)을 사용합니다. 자세한 내용은 "GitHub 앱의 권한 선택"을(를) 참조하세요.
`request_oauth_on_install`	`boolean`	GitHub App이(가) 설치된 후 사용자에게 GitHub App에 권한을 부여하도록 요청하도록 `true`(으)로 설정합니다.
`setup_on_update`	`boolean`	사용자가 GitHub App 설치를 업데이트한 후 사용자를 `setup_url`(으)로 리디렉션하려면 `true`으(로) 설정합니다.

hook_attributes 개체에는 다음 키가 있습니다.

속성	형식	설명
`url`	`string`	필수입니다. 웹후크 `POST` 요청을 수신할 서버의 URL입니다.
`active`	`boolean`	이 후크가 트리거될 때 이벤트 세부 정보를 전달하며 기본값은 true입니다.

매개 변수

이름	형식	설명
`state`	`string`	추측할 수 없는 임의 문자열입니다. 교차 사이트 요청 위조 공격에서 보호하는 데 사용됩니다.

예제

이 예제에서는 개인 계정에 대한 POST 요청을 트리거하는 단추가 있는 웹 페이지의 양식을 사용합니다.

<form action="https://github.com/settings/apps/new?state=abc123" method="post">
 Register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
 <input type="submit" value="Submit">
</form>

<script>
 input = document.getElementById("manifest")
 input.value = JSON.stringify({
   "name": "Octoapp",
   "url": "https://www.example.com",
   "hook_attributes": {
     "url": "https://example.com/github/events",
   },
   "redirect_url": "https://example.com/redirect",
   "callback_urls": [
     "https://example.com/callback"
   ],
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

이 예제에서는 조직 계정에 대한 POST 요청을 트리거하는 단추가 있는 웹 페이지의 양식을 사용합니다. ORGANIZATION을(를) 앱을 등록하려는 조직 계정의 이름으로 바꿉니다.

<form action="https://github.com/organizations/ORGANIZATION/settings/apps/new?state=abc123" method="post">
 register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
 <input type="submit" value="Submit">
</form>

<script>
 input = document.getElementById("manifest")
 input.value = JSON.stringify({
   "name": "Octoapp",
   "url": "https://www.example.com",
   "hook_attributes": {
     "url": "https://example.com/github/events",
   },
   "redirect_url": "https://example.com/redirect",
   "callback_urls": [
     "https://example.com/callback"
   ],
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

2. GitHub는 사용자를 사이트로 다시 리디렉션

사용자가 GitHub 앱 만들기를 클릭하면 GitHub는 코드 매개 변수에서 임시 code를 사용하여 redirect_url로 다시 리디렉션됩니다. 예시:

https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679

state 매개 변수를 제공한 경우 redirect_url에도 해당 매개 변수가 표시됩니다. 예시:

https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679&state=abc123

3. 임시 코드를 교환하여 앱 구성 검색

핸드셰이크를 완료하려면 POST 요청의 임시 code를 매니페스트에서 GitHub 앱 만들기 엔드포인트로 보냅니다. 응답에는 id(GitHub 앱 ID), pem(프라이빗 키), webhook_secret이 포함됩니다. GitHub는 자동으로 앱에 대한 웹후크 비밀을 만듭니다. 이러한 값을 앱 서버의 환경 변수에 저장할 수 있습니다. 예를 들어, 앱에서 dotenv를 사용하여 환경 변수를 저장하는 경우 변수를 앱의 .env 파일에 저장합니다.

1시간 내에 GitHub 앱 매니페스트 흐름의 이 단계를 완료해야 합니다.

참고: 이 엔드포인트는 속도가 제한됩니다. 현재 속도 제한 상태를 가져오는 방법을 알아보려면 속도 제한을 참조하세요.

POST /app-manifests/{code}/conversions

엔드포인트의 응답에 관한 자세한 내용은 매니페스트에서 GitHub 앱 만들기를 참조하세요.

매니페스트 흐름의 마지막 단계가 완료되면 흐름에서 앱을 등록하는 사용자는 개인 리포지토리에 설치할 수 있는 등록된 GitHub 앱의 소유자가 됩니다. GitHub API를 사용하여 앱을 확장하거나, 소유권을 다른 사용자에게 이전하거나, 언제든지 삭제하도록 선택할 수 있습니다.

Probot을 사용하여 GitHub 앱 매니페스트 흐름 구현

Probot은 웹후크 유효성 검사, 인증 수행 등 모든 GitHub 앱에 필요한 많은 작업을 수행하는 Node.js로 빌드된 프레임워크입니다. Probot은 GitHub 앱 매니페스트 흐름을 구현하므로 GitHub 앱 참조 디자인을 쉽게 만들고 GitHub 커뮤니티와 공유할 수 있도록 합니다.

공유할 수 있는 Probot 앱을 만들려면 다음 단계를 수행합니다.

새 GitHub 앱을 생성합니다.
생성한 프로젝트를 열고 app.yml 파일의 설정을 사용자 지정합니다. Probot은 app.yml의 설정을 GitHub 앱 매니페스트 매개 변수로 사용합니다.
애플리케이션의 사용자 지정 코드를 추가합니다.
GitHub 앱을 로컬로 실행하거나 원하는 위치에 호스트합니다. 호스트된 앱의 URL로 이동하면 사용자가 클릭하여 미리 구성된 앱을 등록할 수 있는 GitHub 앱 등록 단추가 있는 웹 페이지를 찾을 수 있습니다.

dotenv를 사용하면 Probot은 .env 파일을 만들고 앱 구성에서 검색된 값으로 APP_ID, PRIVATE_KEY 및 WEBHOOK_SECRET 환경 변수를 설정합니다.

Glitch를 사용하여 앱 호스트

Glitch를 사용하여 앱을 호스트하고 공유하는 예제 Probot 앱을 볼 수 있습니다. 이 예제에서는 Checks API를 사용하고 app.yml 파일에서 필요한 Checks API 이벤트 및 권한을 선택합니다. Glitch는 “자신만의 앱을 리믹스”할 수 있는 도구입니다. 앱을 리믹스하면 Glitch가 호스트하고 배포하는 앱 복사본이 만들어집니다. Glitch 앱 리믹스에 관한 자세한 내용은 "Glitch 정보"를 참조하세요.

이 문서의 내용