소개
GitHub Apps을(를) 사용하면 프로세스를 자동화하거나 다른 플랫폼을 GitHub과(와) 통합할 수 있습니다. 자세한 내용은 "GitHub 앱 만들기 정보"을(를) 참조하세요.
이 빠른 시작에서는 GitHub App을(를) 빠르게 만드는 방법을 설명합니다. 앱에 액세스 권한이 부여된 리포지토리에서 끌어오기 요청이 열리면, 앱은 끌어오기 요청에 주석을 추가합니다.
이 빠른 시작에서는 미리 작성된 코드를 사용하여 빠르게 시작할 수 있습니다. 코드를 작성하는 데 도움이 되는 자세한 자습서는 "웹후크 이벤트에 응답하는 GitHub 앱 빌드"을(를) 참조하세요.
필수 조건
컴퓨터 또는 codespace는 Node.js 버전 12 이상이어야 합니다. 자세한 내용은 Node.js를 참조하세요.
1단계: 앱 코드 복제
빠르게 시작할 수 있도록, 여러분이 사용할 수 있는 코드를 미리 작성해 두었습니다. 코드를 직접 작성하는 방법을 알아보려면 "웹후크 이벤트에 응답하는 GitHub 앱 빌드"을(를) 참조하세요.
- github/github-app-js-sample 리포지토리를 복제합니다. 자세한 내용은 "리포지토리 복제"을(를) 참조하세요. 로컬 복제본 또는 GitHub Codespaces을(를) 사용할 수 있습니다.
- 터미널 창에서 복제본이 저장된 디렉터리로 이동합니다.
npm install
을 실행하여 종속성을 설치합니다.
2단계: 웹후크 프록시 URL 가져오기
로컬로 앱을 개발하려면 웹후크 프록시 URL을 사용하여 웹후크를 GitHub에서 컴퓨터 또는 codespace로 전달할 수 있습니다. 이 빠른 시작에서는 Smee.io 사용하여 웹후크 프록시 URL를 제공하고 웹후크를 전달합니다.
- 브라우저에서 https://smee.io/로 이동합니다.
- 새 채널 시작을 클릭합니다.
- "웹후크 프록시 URL"에서 전체 URL을 복사합니다. 이 URL은 이후 단계에서 사용합니다.
3단계: GitHub App
등록하기
다음 단계에서는 이 빠른 시작에 필요한 앱 설정을 구성하는 방법을 안내합니다. 설정에 대한 자세한 내용은 "GitHub 앱 등록"을(를) 참조하세요.
- GitHub의 페이지 오른쪽 위 모서리에서 프로필 사진을 클릭합니다.
- 계정 설정으로 이동합니다.
- 개인 계정 소유한 앱의 경우 설정을 클릭합니다.
- 조직이 소유한 앱의 경우:
- 사용자의 조직을 클릭합니다.
- 조직 오른쪽에서 설정을 클릭합니다.
- 왼쪽 사이드바에서 개발자 설정을 클릭합니다.
- 왼쪽 사이드바에서 GitHub Apps 을 클릭합니다.
- 새 GitHub 앱을 클릭합니다.
- "GitHub 앱 이름"에서 앱의 이름을 입력합니다. 예를 들어
USERNAME-quickstart-app
에서USERNAME
은 GitHub 사용자 이름입니다. - "홈페이지 URL"에
https://github.com/github/github-app-js-sample#readme
를 입력합니다. - 이 빠른 시작의 "사용자 식별 및 권한 부여" 및 "설치 후" 섹션은 건너뜁니다. 이러한 설정에 대한 자세한 내용은 "GitHub 앱 등록"을(를) 참조하세요.
- "웹후크"에서 활성이 선택되어 있는지 확인합니다.
- "웹후크 URL"에서 이전의 웹후크 프록시 URL을 입력합니다. 자세한 내용은 "2단계: 웹후크 프록시 URL 가져오기"를 참조하세요.
- "웹후크 비밀"에서 임의의 문자열을 입력합니다. 해당 문자열은 이후에 사용합니다.
- "리포지토리 권한"의 "끌어오기 요청" 옆에 있는 읽기 및 쓰기를 선택합니다.
- "이벤트 구독"에서 끌어오기 요청을 선택합니다.
- "이 GitHub 앱을 설치할 수 있는 위치"에서 이 계정만을 선택합니다.
- GitHub 앱 만들기를 클릭합니다.
4단계: 식별 정보 및 자격 증명 저장
이 빠른 시작에서는 앱의 자격 증명과 식별 정보를 .env
파일에 환경 변수로 저장합니다. 앱을 배포할 때 자격 증명을 저장하는 방법을 변경하려고 할 것입니다. 자세한 내용은 앱 배포를 참조하세요.
자격 증명을 로컬로 저장하므로 이러한 단계를 수행하기 전에 안전한 컴퓨터를 사용 중인지 확인합니다.
.env
파일을 만듭니다.
복제된 리포지토리의 .gitignore
파일에 .env
가 포함됩니다. 이렇게 하면 실수로 앱의 자격 증명을 커밋하는 것을 방지할 수 있습니다. .gitignore
파일에 대한 자세한 내용은 "Ignoring files(파일 무시)"을(를) 참조하세요.
-
github/github-app-js-sample의 복제본이 저장된 디렉터리로 이동합니다.
-
이 디렉터리의 최상위 수준에
.env
(이)라는 파일을 만듭니다. -
.env
파일에 다음 내용을 추가합니다. 이후 단계에서 값을 업데이트합니다.Text APP_ID="YOUR_APP_ID" WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET" PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"
APP_ID="YOUR_APP_ID" WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET" PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"
앱 설정으로 이동합니다.
앱을 만든 후 앱 설정에서 나간 경우 앱의 설정 페이지로 이동합니다.
- GitHub의 페이지 오른쪽 위 모서리에서 프로필 사진을 클릭합니다.
- 계정 설정으로 이동합니다.
- 개인 계정 소유한 앱의 경우 설정을 클릭합니다.
- 조직이 소유한 앱의 경우:
- 사용자의 조직을 클릭합니다.
- 조직 오른쪽에서 설정을 클릭합니다.
- 왼쪽 사이드바에서 개발자 설정을 클릭합니다.
- 왼쪽 사이드바에서 GitHub Apps 을 클릭합니다.
- 앱 이름 옆에 있는 편집을 클릭합니다.
앱 자격 증명 및 식별 정보 가져오기
- 앱의 설정 페이지에서 "앱 ID" 옆에 있는 앱의 앱 ID를 찾습니다.
.env
파일에서YOUR_APP_ID
를 앱의 앱 ID로 바꿉니다.- 앱의 설정 페이지에서 "프라이빗 키"에서 프라이빗 키 생성을 클릭합니다. 컴퓨터에 다운로드된 PEM 형식의 프라이빗 키가 표시됩니다. 자세한 내용은 "GitHub 앱에 대한 프라이빗 키 관리"을(를) 참조하세요.
- codespace를 사용하는 경우 codespace가 파일에 액세스할 수 있도록 다운로드한 PEM 파일을 codespace로 이동합니다.
.env
파일에서YOUR_PRIVATE_KEY_PATH
의 전체 경로를.pem
확장명을 포함한 프라이빗 키로 바꿉니다..env
파일에서YOUR_WEBHOOK_SECRET
을 앱의 웹후크 비밀로 바꿉니다. 웹후크 비밀을 잊어버린 경우 "웹후크 비밀(선택 사항)"에서 비밀 변경을 클릭합니다. 새 비밀을 입력한 다음 변경 내용 저장을 클릭합니다.
5단계: 앱 설치
앱이 리포지토리의 끌어오기 요청에 대한 주석을 남기려면 리포지토리를 소유하고 해당 리포지토리에 대한 액세스 권한을 부여한 계정에 앱을 설치해야 합니다. 앱은 비공개이므로 앱을 소유한 계정에만 설치할 수 있습니다.
- 만든 앱을 소유한 계정에서 앱을 설치할 새 리포지토리를 만듭니다. 자세한 내용은 "새 리포지토리 만들기"을(를) 참조하세요.
- 앱을 만든 후 앱 설정에서 나간 경우 앱의 설정 페이지로 이동합니다. 자세한 내용은 "앱 설정으로 이동"을 참조하세요.
- 공개 페이지를 클릭합니다.
- 설치를 클릭합니다.
- 리포지토리만 선택을 선택합니다.
- 리포지토리 선택 드롭다운 메뉴를 선택하고 이 섹션의 시작 부분에서 선택한 리포지토리를 클릭합니다.
- 설치를 클릭합니다.
6단계: 서버 시작
테스트를 위해 컴퓨터 또는 codespace를 서버로 사용합니다. 서버가 실행 중일 때만 앱이 활성화됩니다.
-
터미널 창에서 github/github-app-js-sample의 복제본이 저장된 디렉터리로 이동합니다.
-
Smee.io에서 전달된 웹후크를 받으려면
npx smee -u WEBHOOK_PROXY_URL -t http://localhost:3000/api/webhook
를 실행합니다.WEBHOOK_PROXY_URL
을 웹후크 프록시 URL로 바꿉니다. URL을 잊어버린 경우 앱 설정 페이지의 "웹후크 URL" 필드에서 찾을 수 있습니다.다음과 같은 출력이 표시됩니다. 여기서
WEBHOOK_PROXY_URL
은 웹후크 프록시 URL입니다.Forwarding WEBHOOK_PROXY_URL to http://localhost:3000/api/webhook Connected WEBHOOK_PROXY_URL
-
두 번째 터미널 창에서 github/github-app-js-sample의 복제본이 저장된 디렉터리로 이동합니다.
-
npm run server
를 실행합니다. 터미널에Server is listening for events at: http://localhost:3000/api/webhook
라고 표시되어야 합니다.
7단계: 앱 테스트
이제 서버가 실행 중이고 전달된 웹후크 이벤트를 수신했으므로 끌어오기 요청을 열어 앱을 테스트합니다.
- 5단계: 앱 설치에서 만든 리포지토리에서 끌어오기 요청을 엽니다. 자세한 내용은 "끌어오기 요청 만들기"을(를) 참조하세요.
- smee.io에서 웹후크 프록시 URL로 이동합니다.
pull_request
이벤트가 표시됩니다. 이는 끌어오기 요청을 만들 때 GitHub이(가) 끌어오기 요청 이벤트를 성공적으로 전송했음을 나타냅니다. npm run server
를 실행한 터미널에 "#1에 대한 끌어오기 요청 이벤트 수신됨"과 같은 항목이 표시됩니다. 여기서#
뒤의 정수는 사용자가 연 끌어오기 요청의 수입니다.- 끌어오기 요청의 타임라인에 앱의 주석이 표시됩니다. 주석에는 복제된 리포지토리에 있는
message.md
파일의 내용이 사용됩니다. - 두 터미널 창에서 Ctrl+C를 입력하여 서버를 중지하고 전달된 웹후크 수신을 중지합니다.
다음 단계
이제 앱이 있으므로 앱의 코드를 확장하고, 앱을 배포하고, 앱을 공개할 수 있습니다.
앱 코드 수정
github/github-app-js-sample 리포지토리를 포크하고, 다른 웹후크 이벤트에 응답하거나 다른 API 요청을 만들도록 코드를 수정합니다. 코드에 대한 자세한 내용은 "웹후크 이벤트에 응답하는 GitHub 앱 빌드"을(를) 참조하세요.
만들려는 API 요청 또는 수신하려는 웹후크 이벤트에 대한 추가 권한이 앱에 필요한 경우 앱의 권한을 업데이트해야 합니다. 자세한 내용은 "GitHub 앱의 권한 선택"을(를) 참조하세요.
앱 배포
이 자습서에서는 컴퓨터 또는 codespace를 서버로 사용했습니다. 앱이 프로덕션 사용을 위해 준비되면 앱을 전용 서버에 배포해야 합니다. 예를 들어 Azure App Service를 사용할 수 있습니다.
서버가 준비되면 앱 설정에서 웹후크 URL을 업데이트합니다. 프로덕션에서 웹후크를 전달하는 데 Smee.io를 사용해서는 안 됩니다.
또한 코드에서 port
및 host
상수도 업데이트해야 합니다. 자세한 내용은 "웹후크 이벤트에 응답하는 GitHub 앱 빌드"을(를) 참조하세요.
앱의 프라이빗 키 또는 웹후크 비밀은 절대 공개해서는 안 됩니다. 이 자습서에서는 앱의 자격 증명을 gitignored .env
파일에 저장했습니다. 앱을 배포할 때 자격 증명을 저장하고 코드를 업데이트하여 값을 적절하게 가져오는 안전한 방법을 선택해야 합니다. 예를 들어 앱이 배포된 서버의 환경 변수에 자격 증명을 저장할 수 있습니다. Azure Key Vault와 같은 비밀 관리 서비스를 사용할 수도 있습니다.
앱 공유
앱을 다른 사용자 및 조직과 공유하려면 앱을 퍼블릭으로 설정하세요. 자세한 내용은 "공개 또는 비공개 GitHub 앱 만들기"을(를) 참조하세요.
모범 사례 준수
GitHub App을(를) 사용하는 모범 사례를 따르는 것을 목표로 해야 합니다. 자세한 내용은 "GitHub App을 만드는 모범 사례"을(를) 참조하세요.