GitHub 앱에 웹후크 사용

웹후크 및 GitHub Apps

정보

웹후크를 사용하면 사용자가 커밋을 푸시하거나 앱이 액세스할 수 있는 리포지토리에서 끌어오기 요청을 여는 경우와 같이 GitHub에서 이벤트가 발생할 때 GitHub App에서 실시간 알림을 받을 수 있습니다. 웹후크에 대한 자세한 내용은 웹후크 정보을(를) 참조하세요. GitHub App에서 웹후크를 사용하는 방법을 보여 주는 자습서는 웹후크 이벤트에 응답하는 GitHub 앱 빌드을(를) 참조하세요.

GitHub에서 특정 이벤트에 대한 웹후크를 수신하고 자동으로 작업을 수행하도록 GitHub App을(를) 구성할 수 있습니다. 수신할 수 있는 다른 유형의 웹후크에 대한 자세한 내용은 웹후크 이벤트 및 페이로드을(를) 참조하세요.

GitHub App에서 웹후크 이벤트를 수신하려면 GitHub App 등록에 대해 웹후크를 활성화하고 웹후크 URL을 지정해야 합니다. 여기서 GitHub은(는) 웹후크 페이로드를 전송합니다.

GitHub App이(가) 웹후크에 응답할 필요가 없거나 인증에만 사용되는 경우 GitHub App 등록에 대한 웹후크 함수를 비활성화할 수 있습니다. 웹후크 URL을 지정할 필요가 없습니다.

GitHub App 등록에 대한 자세한 내용은 GitHub 앱 등록 항목을 참조하세요. GitHub App 등록이 구독하는 웹후크를 변경하는 방법에 대한 자세한 내용은 GitHub 앱 등록 수정을(를) 참조하세요.

웹후크 URL 선택

GitHub App 등록에 대한 웹후크를 활성화하는 경우 웹후크 URL을 지정해야 합니다. 웹후크 URL은 GitHub App에 전송된 웹후크 이벤트 페이로드를 수신하는 웹 서버의 주소입니다. 그러면 서버는 페이로드의 내용에 따라 작업을 수행할 수 있습니다. GitHub App에서 발생하는 웹후크 트래픽 볼륨에 적합한 웹 서버를 선택해야 합니다.

개발 및 테스트를 위한 웹후크 URL 선택

앱을 개발하고 테스트하는 동안 Smee와 같은 웹후크 페이로드 제공 서비스를 사용하여 웹후크 페이로드를 캡처하고 로컬 개발 환경에 전달할 수 있습니다. Smee 채널은 인증되지 않았거나 안전하지 않으므로 프로덕션 환경에서 애플리케이션에 Smee를 사용해서는 안 됩니다. 로컬 컴퓨터를 인터넷에 노출하는 ngrok, localtunnel 또는 Hookdeck Console과 같은 도구를 사용하여 페이로드를 수신할 수도 있습니다.

Smee를 사용하여 웹후크 URL 만들기

Smee를 사용하여 GitHub이(가) 로컬 개발 환경을 인터넷에 노출하지 않으면서 웹후크 페이로드를 보낼 수 있는 고유한 작업을 만들 수 있습니다. Smee는 "웹후크 프록시 URL"이라는 이 고유한 도메인을 호출합니다. Smee의 웹후크 프록시 URL을 GitHub App의 웹후크 URL로 사용할 수 있습니다.

1. Smee를 사용하여 고유한 도메인을 만들려면 https://smee.io로 이동하여 새 채널 시작을 클릭합니다.
2. Smee 채널 페이지에서 "CLI 사용"의 지침에 따라 Smee 클라이언트를 설치하고 실행합니다.
3. Smee 웹후크 URL을 GitHub App에 연결하려면 GitHub App 등록 페이지의 "웹후크 URL" 필드에 고유한 Smee 도메인을 입력합니다. 자세한 내용은 GitHub 앱 등록 및 GitHub 앱 등록 수정을(를) 참조하세요.

프로덕션 환경의 웹후크 URL 선택

낮은 볼륨의 웹후크 트래픽을 수신하는 프로덕션 환경의 애플리케이션은 동적 애플리케이션 서버에서 호스트할 수 있습니다. 웹후크를 처리하기 위한 서버 쪽 코드는 이벤트를 수신하고, JSON 페이로드를 역직렬화하며, 데이터베이스에 데이터를 저장하거나 GitHub API를 호출하는 등의 수행할 작업을 결정할 수 있습니다.

프로덕션 환경에서 대규모 앱에 대해 더 많은 양의 웹후크 트래픽을 처리하려면 전용 서버에서 비동기 웹후크 처리를 사용하는 것이 좋습니다. 웹후크 처리기가 데이터를 큐에 푸시하고 별도의 프로세스가 이벤트에 따라 후속 작업을 수행하는 큐를 사용하여 이 작업을 수행할 수 있습니다. 또한 Azure Functions, AWS Lambda 또는 Hookdeck과 같은 클라우드 함수를 사용하여 대량의 웹후크 이벤트를 처리하도록 앱 크기를 조정할 수 있습니다.

웹후크 비밀로 웹후크 보호

페이로드를 수신하도록 서버를 구성하고 나면, 서버에 전송된 모든 페이로드를 수신 대기합니다. 보안상의 이유로, 들어오는 요청을 GitHub에서 시작된 요청으로만 제한해야 합니다. 앱의 웹후크 비밀을 만들어 이렇게 할 수 있습니다.

GitHub 앱의 웹후크 비밀을 만들려면 GitHub App 등록 페이지의 "웹후크 비밀" 아래에 비밀 토큰을 입력합니다. 엔트로피가 높은 임의의 텍스트 문자열을 선택해야 합니다. 자세한 내용은 GitHub 앱 등록 및 GitHub 앱 등록 수정을(를) 참조하세요.

앱의 웹후크 비밀을 만든 후에는 웹후크 비밀 토큰을 안전하게 저장하고 유효성을 검사하도록 서버를 구성해야 합니다. 자세한 내용은 웹후크 제공 유효성 검사하기을(를) 참조하세요.

웹후크 이벤트 구독

GitHub App을(를) 구독하여 특정 이벤트에 대한 웹후크 페이로드를 수신할 수 있습니다. GitHub App 등록에 대해 선택할 수 있는 특정 웹후크 이벤트는 앱에 대해 선택한 사용 권한 유형에 따라 결정됩니다. 먼저 앱에 부여할 사용 권한을 선택한 다음 해당 사용 권한 집합과 관련된 웹후크 이벤트에 앱을 구독할 수 있습니다. 자세한 내용은 GitHub 앱의 권한 선택을(를) 참조하세요.

예를 들어 리포지토리에서 새 이슈가 열릴 때마다 앱이 웹후크 이벤트 페이로드를 수신하도록 하려면 먼저 "리포지토리 권한"의 "이슈"에 액세스할 권한을 앱에 부여해야 합니다. 그런 다음, "이벤트 구독"에서 "이슈"를 선택할 수 있습니다.

각 웹후크 이벤트에 필요한 권한에 대한 자세한 내용은 웹후크 이벤트 및 페이로드을(를) 참조하세요.