# GitHub 연결하기

Mocco는 GitHub 저장소 또는 조직 웹훅을 통해 push, pull request, 이슈, 릴리스, 워크플로 실행 이벤트를 받습니다. GitHub에서는 **Mocco가 서명 시크릿을 생성**하며, 사용자가 그 시크릿을 GitHub에 붙여 넣습니다.

이 작업은 배포 거버넌스를 위해 Mocco GitHub App을 연결하는 것과 별개입니다. 알림 소스는 일반 웹훅이며, 관리자 권한이 있는 저장소나 조직이면 어디든 추가할 수 있습니다.

Mocco의 소유자나 관리자여야 하고, 저장소 웹훅이면 해당 저장소의 관리자, 조직 웹훅이면 해당 조직의 소유자여야 합니다.

## 1. Mocco에서 소스 만들기

1. **Notifications > Sources**를 열고 **Add source**를 클릭합니다.
2. **Kind**에서 **GitHub**를 고르고, `acme/web` 같은 **Name**을 입력합니다.
3. **Create source**를 클릭합니다.

Mocco는 새 시크릿을 한 번만 보여 줍니다. **Copy**를 클릭하고, GitHub에 붙여 넣을 때까지 보관하세요. **Mocco는 시크릿을 다시 보여 주지 않습니다.** 잃어버렸다면 소스에서 **Rotate secret**을 클릭해 새 시크릿을 받고, 그 시크릿을 GitHub에 붙여 넣으세요.

![소스를 만든 직후 한 번만 표시되는 GitHub 시크릿](https://fi-workers-mocco-storage.s3.ap-northeast-2.amazonaws.com/pub/w/93e11fe8-0494-4e3d-b1cb-fe4dffd3ee7e/p/d64785b8-9a23-4fa1-a81d-550af30e203a/helpcenter/d2e0d061-4c4b-4fbb-82ce-f537217a2a0c/github-secret.png)

목록에서 소스의 **Ingest URL**도 복사합니다.

## 2. GitHub에 웹훅 추가

저장소의 경우:

1. GitHub에서 저장소를 열고 **Settings**를 클릭합니다.
2. 왼쪽 사이드바에서 **Webhooks**, **Add webhook**을 차례로 클릭합니다.

조직의 경우: 프로필 사진, **Your organizations**, 해당 조직 옆의 **Settings**를 차례로 클릭한 다음 **Webhooks**와 **Add webhook**을 클릭합니다.

그런 다음 양식을 채웁니다.

1. **Payload URL**: Mocco에서 복사한 소스의 ingest URL.
2. **Content type**: **application/json**을 고릅니다. Mocco는 폼 인코딩 형식을 읽을 수 없습니다. 그런 전달은 `malformed JSON body`라는 사유와 함께 `ignored`로 기록됩니다.
3. **Secret**: Mocco가 생성한 시크릿을 붙여 넣습니다.
4. "Which events would you like to trigger this webhook?"에서 **Let me select individual events**를 고르고, 다음 목록에서 원하는 이벤트를 선택합니다. push(`push`), pull request(`pull_request`), 이슈(`issues`), 릴리스(`release`), 워크플로 실행(`workflow_run`)입니다. 그 밖의 이벤트는 `ignored`로 기록됩니다.
5. **Active**를 선택한 상태로 두고 **Add webhook**을 클릭합니다.

GitHub는 곧바로 `ping`을 보냅니다. 이 이벤트는 Mocco의 **Activity** 탭에 사유 `ping`과 함께 `ignored`로 나타나며, URL과 시크릿이 올바르다는 뜻입니다.

## 받게 되는 이벤트

| GitHub 이벤트 | Mocco 이벤트 |
|---|---|
| `push` | `github.push` |
| `pull_request` opened / reopened | `github.pull_request.opened` / `github.pull_request.reopened` |
| `pull_request` closed, merged | `github.pull_request.merged` |
| `pull_request` closed, not merged | `github.pull_request.closed` |
| `issues` opened / reopened / closed | `github.issues.opened` / `.reopened` / `.closed` |
| `release` published | `github.release.published` |
| 실패, 시간 초과, 시작 실패로 끝난 `workflow_run` completed | `github.workflow_run.failed` |
| 성공으로 끝난 `workflow_run` completed | `github.workflow_run.succeeded` |
| 그 밖의 모든 action 또는 이벤트(`pull_request` edited, `issues` labeled, 취소된 실행 등) | `ignored`로 기록 |

필터 키:

| 이벤트 | 키 |
|---|---|
| `github.push` | `repo`(`acme/web`), `refType`(`branch` 또는 `tag`), `branch`(브랜치 push에만), `hasCommits`(`true` 또는 `false`) |
| `github.pull_request.*` | `repo`, `baseBranch`(pull request가 대상으로 하는 브랜치) |
| `github.issues.*`, `github.release.published` | `repo` |
| `github.workflow_run.*` | `repo`, `workflow`(워크플로 이름), `branch` |

`hasCommits`는 텍스트가 아니라 true/false 값입니다. **GitHub** 프리셋은 `hasCommits` = true인 `github.push`(브랜치 삭제와 빈 push는 조용히 넘어갑니다), pull request 이벤트 네 개, 이슈 이벤트 세 개, `github.release.published`, `github.workflow_run.failed`를 추가합니다. `main`에 대한 push만 받으려면 `github.push`에 `branch=main` 필터를 건 규칙을 추가하세요.

## 동작 확인

저장소에 커밋을 push합니다. push가 **Activity**에 `published` 결과로 나타납니다.

GitHub에서 웹훅을 열고 **Recent deliveries**를 클릭하면 최근 3일간의 전달 내역과 각각에 대한 Mocco의 응답을 볼 수 있습니다. `202`는 Mocco가 기록했다는 뜻입니다. Mocco가 전달을 거부했다면(예를 들어 시크릿을 잘못 넣어 `401`이 나온 경우) 원인을 고치고 **Redeliver**를 클릭하세요. Mocco는 GitHub 전달 ID마다 기록을 하나만 보관하므로, 이미 기록한 전달을 다시 보내도 달라지는 것은 없습니다. 다른 응답은 [문제 해결](https://www.mocco.club/docs/ko/articles/pmzrkr-troubleshooting)을 참고하세요.