노션 패치노트 자동 작성 CI 구축기 - API의 사용성에 대해서 뼈저리게 배웠습니다ㅜㅠ

안녕하세요. 오늘은 노션 패치노트를 자동 작성해주는 CI를 구축했던 경험을 공유해드리려고 합니다.
 
노션 태스크에 연결한 Github Pull Request가 병합되었을 때, 자동으로 패치노트를 작성하는 간단한 CI를 구축하려고 했는데 어려움이 많았어서 생각보다 재미 있는 경험을 할 수 있었는데요. 간단하게 공유 드려 보겠습니다 :)

• 바로 예제 코드를 보고 싶으신 분은 내용 마지막에 github repository 주소를 적어뒀으니 바로 내려가시면 됩니다!

---

1. 노션 & Github 연동

노션에서 Github 연동을 지원하고 있다는 사실 아시나요?
엄청 많은 기능들을 지원하는 것은 아니지만 Github에 Pull Request를 만들고, Pull Request가 병합됨에 따라서 태스크의 상태를 자동으로 변경 시킬 수 있습니다.

• 참고 링크: https://www.notion.so/ko-kr/integrations/github
• 이런 식으로 태스크와 Github Pull Request가 자동으로 연동됩니다.

 

Notion에서 Github Pull Request 상태에 따른 태스크 상태 설정 & Github Pull Request에 태스크 링크 자동 추가 

태스크에 Github Pull Request 자동 연동

 

• 저는 노션을 편리한 문서 도구 정도로만 생각했었는데 프로젝트 관리 영역까지 넘보고 있더라고요.
  • 올 해 스프린트 관리 기능도 출시되면서 노션을 이용한 프로젝트 관리가 훨씬 쉬워졌습니다!
  • 참고 링크: https://www.notion.so/help/sprints

 
태스크와 Pull Request가 이렇게 자연스럽게 연동되는 것을 보고, "Pull Request가 머지될 때, notion page 추가하는 것 정도는 쉽겠는데?" 하면서 가벼운 마음으로 패치 노트 자동 작성 작업을 시작했습니다.

• 이런 형태의 아주 간단한 패치노트를 만드려는 계획이었습니다.

커밋 ID를 이용해서 제목을 만들고, 원래 티켓 링크를 작성

2. Notion API

Pull Request가 머지될 때, Notion page를 추가하므로 github action을 이용해서 이를 이루려고 했습니다.
그러면 제가 태스크에 대해서 가지고 있는 정보는 Pull Request의 제목에 적어둔 태스크 ID 정도입니다.
 
그래서 태스크의 ID로 페이지 링크를 찾을 수 있는 Notion API Reference에서 페이지 검색 기능을 찾았는데, 찾았는데...

• 참고 링크: https://developers.notion.com/reference/retrieve-a-page
• search로 찾고 있었는데 retrieve더라고요 ㅋㅋㅋㅋ

page id로만 검색할 수 있고, page의 property로는 검색할 수 없더라고요!
 
태스크 ID와 Notion API로는 원하는 페이지를 찾을 수 없다고 판단하여 다른 방법을 찾아보게 되었습니다.

• 노션 page 중에서 ID가 Pull Request에 포함되어 있는 태스크 ID와 일치하는지 검사하는 것은 너무나 비효율적인 방법이기에 고려하지 않았습니다.

 

3. Notion API 통합 갤러리

혹시 이를 지원해줄 수 있는 툴들이 있는지 살펴봤는데 못 찾겠더라고요 ㅜㅠ

• 참고 링크: https://www.notion.so/ko-kr/integrations/all

여기까지 도달하니 이렇게 간단해보이는 문제를 해결하지 못하는 건가 하고 낙담하고 있었습니다...
 

4. Github Pull Request 에 노션봇이 작성한 comment

그러던 와중에 노션 봇이 자동으로 작성해주는 comment에 노션 페이지 링크가 있는 것이 불현듯 떠올랐습니다!

노션 페이지 링크가 여기 있네요?

comment에 작성된 노션 페이지 링크는 다음과 같은 형태로 이뤄져 있습니다.

• https://www.notion.so/{page-id}?pvs=8&n=github_linkback

여기서 https://www.notion.so/, ?pvs=8&n=github_linkback 만 제거하면 page id를 얻을 수 있는 것이죠!
 

5. Github Pull Request comment 가져오기

자 그러면 어떻게 Pull Request에 작성되어 있는 comment를 가져올 수 있을까요?
Github REST API 문서를 살펴봤는데 두 페이지가 눈에 띄더라고요!

• list review comments on a pull request
• list comments for a pull request review

바로 API를 테스트 해봤습니다. 그런데 어떤 Pull Request 번호를 사용하더라도 comment가 없다는 응답이 오더라고요;;;
 
응답 안 오는 것 확인했으면서도 괜히 API 요청 다시 날려보고, API 문서 한번 보기를 몇번 반복하다 보니 정답을 찾을 수 있었습니다 ㅜ
 
리뷰 없이 작성한 Pull Request comment는 issue의 comment로 찾아야 하는 것이더라고요!

pull request는 issue의 서브셋!

• 링크: https://docs.github.com/en/rest/issues/issues?apiVersion=2022-11-28

list-issue-comments API를 이용해서 노션 봇이 작성한 페이지 링크를 추출할 수 있었습니다...!
 

6. Notion 패치 노트 페이지 작성

5에서 얻은 page id와 페이지 정보 조회 API, 페이지 작성 API를 이용해서 패치 노트를 작성할 수 있습니다!

• https://developers.notion.com/reference/retrieve-a-page
• https://developers.notion.com/reference/post-page

 

7. 완성!

지금까지의 과정이 담긴 github action 스크립트를 아래의 repository에 정리해뒀습니다.
데이터를 어떻게 얻을 수 있는지, 어떤 API를 사용해야 하는지 준비 과정이 길었지만 결과물 자체는 간단하네요 ㅎㅎ

• https://github.com/goodahn/notion-integration-example

---

이렇게 노션 패치노트를 자동으로 작성할 수 있었습니다.
 
처음에는 노션과 깃허브의 API가 왜 이렇게 사용하기 어려운지 불평만 했습니다.
그렇지만 조금 지나고 보니 제가 만든 API들도 매한가지, 아니 더 사용하기 어렵더라고요;;;
"개발자가 API 스펙 보고 개발하면 되지. 무슨 사용성이 중요해!"라고 생각했을 때의 제가 생각나면서 얼굴이 뜨거워지더라고요 ㅋㅋㅋ
 
그리고 워크플로우 자동화의 일부분을 직접 구현해본 셈인데 왜 유료 서비스를 사용하는지 십분 이해가 갔습니다.
워크플로우가 자동으로 관리되면서 메이커들이 꼭 필요한 업무들에 집중할 수 있도록 만들어줄 수 있겠더라고요.

• 패치 노트 자동 작성, 메시지 자동 작성 같이 작은 업무들도 하나, 둘 모이면 메이커들의 집중력을 잃어버리게 만들더라고요 ㅜㅠ

 
또 재미난 일 있으면 공유드리도록 하겠습니다!
 
P.S.
추가적으로 노션 API 응답을 이용해서 슬랙 메시지에 패치노트 링크를 보내봤는데 좋더라고요 ㅎㅎㅎ
워크플로우 자동화 고민해봐야겠습니다...!