GitHub · GitLab 연결

저장소를 GoalTrack 에 연결하면 이슈를 손으로 옮기지 않아도 됩니다.

이슈 키(ENG-12)가 든 브랜치·PR 을 열면 이슈가 팀의 첫 “진행” 상태로 옮겨집니다.
그 PR 을 머지하면 이슈가 팀의 첫 “완료” 상태로 옮겨집니다(닫는 연결일 때만 — 아래 이슈와 PR 잇기).
이슈 상세의 개발 칸에 PR 카드(열림·머지됨·닫힘)가 보이고, 누르면 GitHub·GitLab 으로 갑니다.
활동 탭에는 행위자 “GitHub”·“GitLab” 과 출처 “GitHub/GitLab 연동” 이 남습니다.

GoalTrack 은 webhook 으로 받기만 합니다. GitHub·GitLab 에는 아무것도 쓰지 않습니다(PR 댓글·체크 상태 없음).

누가 연결하나

워크스페이스 소유자·관리자가 설정 › 연동 에서 연결합니다. 저장소 하나, 또는 조직(그룹) 전체에 webhook 하나를 걸 수 있습니다. 워크스페이스당 연결은 20개까지입니다.

1. GoalTrack 에서 연결 만들기

설정 › 연동 의 GitHub(또는 GitLab) 카드에서 [연결 추가] 를 누릅니다.
연결 이름(예: acme/api)과 대상 팀을 고릅니다. 대상 팀을 고르면 그 팀의 이슈 키만 연결됩니다. GitLab 은 호스트도 적습니다(기본 gitlab.com, 자체 호스팅이면 그 주소).
수신 주소와 비밀값이 나옵니다. 🔴 비밀값은 이 화면에서 한 번만 보입니다 — 닫기 전에 복사하세요. 잃어버렸으면 연결 줄의 [비밀값 다시 만들기] 로 새로 받습니다.

2-a. GitHub 에 webhook 걸기

GitHub 저장소(또는 조직) › Settings › Webhooks › Add webhook 을 엽니다.
Payload URL 에 수신 주소를 붙여 넣습니다.
Content type 은 application/json 을 고릅니다(application/x-www-form-urlencoded 도 받습니다).
Secret 에 비밀값을 붙여 넣습니다.
Which events would you like to trigger this webhook? 에서 Let me select individual events 를 고르고 Pull requests 만 체크합니다(기본으로 체크된 Pushes 는 꺼도 됩니다).
Add webhook 을 누르면 GitHub 이 바로 확인 신호(ping)를 보냅니다. GoalTrack 카드의 연결 줄이 “연결 확인됨” 으로 바뀌면 끝입니다.

2-b. GitLab 에 webhook 걸기

GitLab 프로젝트(또는 그룹) › Settings › Webhooks › Add new webhook 을 엽니다.
URL 에 수신 주소를 붙여 넣습니다.
요청을 검증할 방법을 하나 고릅니다.
- 서명 토큰(권장, GitLab 19.0 이상): Generate signing token 으로 토큰(whsec_ 로 시작)을 만들고, GoalTrack 연결 결과 화면의 서명 토큰 칸에 붙여 넣어 [서명 토큰 저장] 을 누릅니다(나중에 하려면 연결 줄의 [서명 토큰 붙여 넣기]). 저장한 뒤로 이 연결은 서명된 요청만 받습니다. 서명 시각이 5분보다 오래된 요청은 거절합니다.
- 비밀 토큰(GitLab 19.0 미만): Secret token 칸에 GoalTrack 비밀값을 붙여 넣습니다. 토큰이 요청 헤더에 그대로 실려 서명보다 약합니다 — 카드에 “약함” 으로 표시됩니다. 서명 토큰을 쓸 수 있으면 그쪽을 쓰세요.
Trigger 에서 Merge request events 만 체크합니다.
Add webhook 을 누릅니다. GitLab 은 저장할 때 확인 신호를 보내지 않으므로, 첫 머지 요청 이벤트가 도착하면 연결 줄의 상태가 바뀝니다.

이슈와 PR 잇기

GoalTrack 은 PR 의 브랜치 이름·제목·본문에서 이슈 키를 찾습니다. 대소문자는 가리지 않습니다(eng-12 = ENG-12).

어디에	예	연결
브랜치 이름	`eng-12-fix-login`	닫는 연결 — 머지하면 완료
PR 제목	`ENG-12 로그인 고침`	닫는 연결
본문 + 닫는 말	`Fixes ENG-12` · `Closes ENG-12` · `Resolves ENG-12`	닫는 연결
본문 + 참조 말	`Refs ENG-12` · `Part of ENG-12` · `Related to ENG-12`	참조 — 카드만 붙고 상태는 그대로
제목·본문 + 예외 말	`skip ENG-12` · `ignore ENG-12`	연결하지 않음

본문에 키만 적고 닫는 말·참조 말이 없으면 연결하지 않습니다.
이슈 상세의 [브랜치 이름 복사](⌘/Ctrl + ⇧ + .)가 키가 든 브랜치 이름을 만들어 줍니다.
초안(draft) PR 은 카드만 붙고 이슈 상태는 그대로입니다. 초안을 풀면(GitHub Ready for review · GitLab 초안 표시 해제) 진행 중으로 옮깁니다.
닫는 PR 이 여러 개면 열려 있는(초안 포함) PR 이 하나도 남지 않은 채 머지가 올 때 이슈가 완료로 갑니다(머지 없이 닫힌 PR 은 기다리지 않습니다).
이미 진행 중이거나 완료·취소된 이슈는 되돌리지 않습니다. PR 이 열려도 완료된 이슈가 진행 중으로 돌아가지 않습니다.
이슈를 옮기는 것은 PR 이 열리고·다시 열리고·초안을 벗고·머지될 때와, 수정으로 키가 새로 들어갔을 때뿐입니다. 사람이 상태를 직접 바꾼 뒤에 같은 PR 에 push 하거나 제목을 고쳐도 다시 옮기지 않습니다.
보관한 이슈는 새로 잇지도 옮기지도 않습니다(이미 붙은 PR 카드는 남고 PR 상태를 계속 따라갑니다).
팀에서 이슈를 옮겨 키가 바뀌었어도 옛 키로 연결됩니다.

외부 기여자의 PR

아무나 PR 제목에 이슈 키를 적을 수 있으므로, 외부에서 온 PR 은 열려도 이슈를 움직이지 않고 카드도 붙이지 않습니다. 유지보수자가 머지하면 그때 카드가 붙고 이슈가 완료로 갑니다. 머지된 뒤에 그 PR 의 제목·본문을 고쳐도 아무것도 바뀌지 않습니다(키를 더 적어 다른 이슈를 닫을 수 없습니다).

GitHub: 작성자가 저장소의 소유자 · 조직 멤버 · 협업자(GitHub 이 PR 에 붙이는 작성자 관계 OWNER · MEMBER · COLLABORATOR)가 아닌 PR 전부 — 포크에서 왔든 같은 저장소의 브랜치에서 왔든 같습니다.
GitLab: 포크에서 온 머지 요청 전부(작성자가 멤버여도).

연결 줄의 상태 읽기

상태	뜻 · 할 일
확인 대기	아직 아무것도 오지 않았습니다. webhook 주소·비밀값을 다시 확인하세요.
연결 확인됨 · 정상	받고 있습니다.
⚠ 점검 필요	받았지만 처리하지 못한 이벤트가 있습니다. 예: 이슈 키를 찾지 못함(브랜치·제목에 키가 있는지, 대상 팀이 맞는지) · 팀에 진행/완료 분류 상태가 없음.
⚠ 최근 거부	이벤트 선택이나 형식이 틀렸습니다. GitHub 은 Pull requests, GitLab 은 Merge request events 를 골랐는지, Content type 이 맞는지 확인하세요.
꺼짐	GoalTrack 쪽에서 받기를 멈췄습니다.

GitHub 이 보낸 것이 실제로 어떻게 처리됐는지는 GitHub webhook 화면의 Recent Deliveries 에서도 볼 수 있습니다. 실패한 배달은 거기서 Redeliver 로 다시 보낼 수 있습니다.

끄기 · 삭제 · 비밀값 다시 만들기

끄기: GoalTrack 만 받기를 멈춥니다. GitHub·GitLab 의 webhook 은 그대로라 다시 켜면 바로 이어 받습니다.
삭제: 수신 주소가 더는 받지 않습니다. GitHub·GitLab 쪽 webhook 도 지우세요(GitLab 은 거절이 이어지면 webhook 을 스스로 끕니다). 이미 붙은 PR 카드는 기록으로 남고 더 갱신되지 않습니다.
비밀값 다시 만들기: 옛 값은 그 순간부터 거절됩니다. 새 값을 바로 GitHub·GitLab 에 붙여 넣으세요. 그 사이에 온 배달은 GitHub Recent Deliveries · GitLab Recent events 에서 다시 보내면 됩니다. 서명 토큰을 쓰는 GitLab 연결은 5분이 지난 배달을 다시 보내면 서명 시각 때문에 거절될 수 있습니다.

한도

연결 하나당 분당 600건까지 받습니다. 넘으면 429 로 거절하고 카드에 “분당 상한 초과” 경고가 뜹니다 — GitHub 은 실패한 배달을 스스로 다시 보내지 않으니 Recent Deliveries 에서 다시 보내세요.
워크스페이스 하나가 24시간 동안 기록하는 배달은 10,000건까지입니다. 넘으면 나머지는 처리하지 않고 카드에 “기록 상한” 경고가 뜹니다.
요청 본문은 1 MiB 까지 받습니다.

백업과 내보내기

Git 연결·PR 카드·받은 기록은 워크스페이스 내보내기·백업에 들어가지 않습니다(연결 비밀값이 파일로 새지 않게). 복원한 뒤 다시 연결하면 그 뒤에 오는 이벤트부터 PR 카드가 붙습니다.