GitHub 앱 빌드에 대한 빠른 시작

소개

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 Enterprise Server의 페이지 오른쪽 위 모서리에서 프로필 사진을 클릭합니다.
계정 설정으로 이동합니다.
- 개인 계정 소유한 앱의 경우 설정을 클릭합니다.
- 조직이 소유한 앱의 경우:
  1. 사용자의 조직을 클릭합니다.
  2. 조직 오른쪽에서 설정을 클릭합니다.
왼쪽 사이드바에서 개발자 설정을 클릭합니다.
왼쪽 사이드바에서 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 파일에 다음 내용을 추가합니다. YOUR_HOSTNAME을 GitHub Enterprise Server 인스턴스의 이름으로 바꿉니다. 이후 단계에서 다른 값을 업데이트합니다.

Text

APP_ID="YOUR_APP_ID"
WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET"
PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"
HOSTNAME="YOUR_HOSTNAME"

APP_ID="YOUR_APP_ID"
WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET"
PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"
HOSTNAME="YOUR_HOSTNAME"

앱 설정으로 이동합니다.

앱을 만든 후 앱 설정에서 나간 경우 앱의 설정 페이지로 이동합니다.

GitHub Enterprise Server의 페이지 오른쪽 위 모서리에서 프로필 사진을 클릭합니다.
계정 설정으로 이동합니다.
- 개인 계정 소유한 앱의 경우 설정을 클릭합니다.
- 조직이 소유한 앱의 경우:
  1. 사용자의 조직을 클릭합니다.
  2. 조직 오른쪽에서 설정을 클릭합니다.
왼쪽 사이드바에서 개발자 설정을 클릭합니다.
왼쪽 사이드바에서 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을 만드는 모범 사례"을(를) 참조하세요.

이 문서의 내용