Notion ↔ GitHub Pages 자동 동기화에 성공하였다.

Summary Notion과 GitHub Pages 간의 자동 동기화를 통해 글쓰기와 배포 과정을 완벽하게 분리한 시스템을 구축하였다. Notion API, Hugo, GitHub Actions를 활용하여 데이터 무결성, 효율성, 내결함성을 고려한 자동화 파이프라인을 설계하였고, 이를 통해 기술적 마찰 없이 글쓰기에만 집중할 수 있는 환경을 조성하였다. 이 과정은 개인적인 질문에 대한 엔지니어링적 해결책을 찾는 여정이었으며, 지속적으로 발전할 수 있는 플랫폼을 만들었다.

나만의 콘텐츠 플랫폼 구축기: 완벽한 동기화를 향한 고민의 기록

결론부터 말하자면, 나는 글쓰기에만 온전히 몰입할 수 있는 나만의 환경을 구축하는 데 성공했다. 이제 Notion의 편리한 편집기에서 생각을 기록하고 정리하면, 그 결과물은 자동으로 최적화된 블로그에 배포된다. 이 글은 단순히 기술을 나열하는 설명서가 아니다. 최고의 편집 도구와 최고의 배포 시스템을 결합하여, 창작 과정의 모든 마찰을 제거하고자 했던 한 엔지니어의 고민과 선택에 대한 회고다.

무엇이 문제였나: Notion에 대한 애증과 엔지니어로서의 숙제

나는 Notion을 애용한다. 생각을 구조화하고, 지식을 엮어내는 데 이보다 더 좋은 도구는 없다고 생각했다. 모든 아이디어의 파편과 지식의 체계가 Notion 안에서 자라나고 있었다. 하지만 이 애정은 곧 기술적인 고민으로 이어졌다. Notion은 ‘창작’과 ‘관리’에는 탁월했지만, ‘배포’라는 측면에서는 명확한 한계를 가지고 있었다.

검색 엔진에 제대로 노출되지 않는 문제, 내 모든 데이터가 결국 Notion이라는 특정 플랫폼에 종속된다는 불안감, 그리고 독자에게 순수한 콘텐츠를 보여주기엔 너무 무겁고 느리다는 웹 성능의 문제까지. 이 세 가지는 엔지니어로서 언젠가 반드시 풀어야 할 숙제처럼 느껴졌다. 내 지식이 더 넓은 세상과 만나고, 온전히 나의 통제하에 있으며, 독자에게 쾌적한 경험을 제공해야 한다는 당위성이 이 프로젝트의 시작이었다.

어떻게 해결하려 했는가: 신뢰할 수 있는 자동화 파이프라인의 설계

문제를 해결하기 위해 내가 선택한 조합은 Notion API, Hugo, 그리고 GitHub Actions였다. 핵심은 Notion에 작성된 콘텐츠를 정적 파일로 변환하여 GitHub Pages에 배포하는 과정을 ‘완전히 자동화’하는 것이었다. 나는 이 자동화 시스템을 단순한 스크립트가 아닌, 신뢰할 수 있는 데이터 파이프라인으로 설계하고자 했다.

가장 먼저 고민한 것은 데이터의 무결성이었다. Notion에서 입력한 제목이나 내용에 포함된 특수문자가 변환 과정에서 문제를 일으켜 빌드 전체를 실패하게 만드는 상황을 막아야 했다. 모든 입력값을 안전하게 처리하는 로직을 추가하여 파이프라인의 안정성을 확보했다.

다음은 효율성이었다. 글이 수백 개로 늘어났을 때, 매번 모든 글을 Notion API로 가져오는 것은 비효율적이다. 나는 마지막 수정 시간을 기록하는 캐시(cache) 파일을 도입했다. 워크플로우가 실행될 때마다 이 캐시를 참조하여 변경된 페이지만 다시 가져오도록 설계했다. 이를 통해 API 요청을 최소화하고 빌드 속도를 획기적으로 개선할 수 있었다.

마지막으로 가장 중요하게 생각한 것은 내결함성이었다. 만약 동기화 스크립트가 중간에 알 수 없는 오류로 실패한다면 어떻게 될까? 최악의 경우 기존에 있던 콘텐츠가 모두 삭제되고 블로그가 통째로 비워질 수 있었다. 나는 이를 막기 위해 원자적 연산(Atomic Operation) 개념을 도입했다. 새로운 콘텐츠를 가져와 파일 변환을 완전히 마친 후에야 기존의 콘텐츠를 대체하도록 로직을 구성했다. 중간에 어떤 문제가 발생하더라도, 블로그는 항상 이전의 안정된 상태를 유지하게 된다. 이 세 가지 원칙 덕분에, 자동화 시스템은 단순한 편의 도구를 넘어 신뢰할 수 있는 서비스로 완성되었다.

그래서 무엇을 얻었는가: 마찰 없는 글쓰기, 그 이상의 가치

이 시스템을 통해 나는 글을 쓰는 행위와 그것을 외부에 발행하는 행위를 완벽하게 분리했다. 이제 나는 Notion에서 오직 생각과 글쓰기에만 집중한다. 발행이 필요할 때면 그저 데이터베이스의 상태 값을 ‘Published’로 바꾸기만 하면 된다. 기술적인 배포 과정의 모든 번거로움은 GitHub Actions가 구축한 파이프라인이 묵묵히 처리해 준다.

결과적으로 나는 기술적 마찰이 완전히 제거된 글쓰기 환경을 얻었다. 이것은 단순히 블로그 자동화 시스템을 만든 것을 넘어, 나의 필요에 맞춰 계속해서 성장하고 개선될 수 있는 살아있는 플랫폼을 구축한 과정이었다. ‘어떻게 하면 더 편하고, 더 잘 쓸 수 있을까?’ 라는 개인적인 질문에 대해 엔지니어링으로 답을 찾아 나간 여정이었고, 그 과정 자체가 나에게는 큰 즐거움과 성취감을 안겨주었다.

이 시스템의 구체적인 구현 과정이나 기술적 세부 사항이 궁금하다면, 별도로 정리해 둔 아래 기록을 참고하길 바란다.

🔗 https://cybecho.github.io/archives/notion-github-sync/