⚙️ [웹사이트 제작 5편] 노션 글 자동 반영! 깃허브 액션 초보자 연동법

🤔 매번 수동으로 배포 버튼을 누르고 계신가요?

📌 한 줄 요약: GitHub Actions를 활용해 Notion의 콘텐츠를 주기적으로 가져오고 웹사이트를 다시 빌드하는 과정을 자동화하는 방법을 알아본다.

2편에서는 AI 바이브코딩으로 웹사이트의 기본 코드를 만들고 GitHub에 저장했다. 3편에서는 Notion을 콘텐츠 관리 도구(CMS)처럼 활용하기 위한 API와 데이터베이스를 준비했고, 4편에서는 GitHub의 웹사이트 코드를 Cloudflare Pages에 연결해 실제 웹사이트로 배포했다.

여기까지 했다면 이제 웹사이트에 글을 올릴 준비가 거의 끝난 것처럼 보인다.

그런데 실제로 블로그를 운영하다 보면 한 가지 번거로운 문제가 생긴다.

“Notion에서 글을 수정했는데, 왜 웹사이트에는 바로 반영되지 않을까?”

Notion의 내용이 바뀌었다고 해서 GitHub에 저장된 웹사이트 코드가 자동으로 변경되는 것은 아니다. 변경된 데이터를 다시 가져오고, 웹사이트를 다시 빌드한 뒤, 변경된 결과물을 배포하는 과정이 필요하다.

물론 이 작업을 매번 직접 할 수도 있다.

하지만 글을 하나 작성하거나 수정할 때마다 같은 작업을 반복해야 한다면 장기적으로는 상당히 번거롭다.

그래서 이번 편에서는 GitHub Actions를 활용해 이 반복 작업을 자동화해보려고 한다.

💡 GitHub Actions이란 무엇일까?

📌 한 줄 요약: GitHub Actions는 GitHub에서 특정 조건이나 일정에 따라 반복적인 작업을 자동으로 실행할 수 있도록 도와주는 기능이다.

GitHub Actions라는 이름이 처음에는 어렵게 느껴질 수 있다.

쉽게 생각하면 “정해진 시간이나 특정 상황이 되면 내가 해야 할 일을 대신 해주는 자동 작업 도구”라고 이해하면 된다.

예를 들어 다음과 같은 작업을 자동으로 실행하도록 설정할 수 있다.

• 정해진 시간에 작업 실행하기
• 외부 서비스에서 데이터 가져오기
• 웹사이트 코드 빌드하기
• 테스트 실행하기
• 변경된 파일을 GitHub에 반영하기

이번 프로젝트에서는 이 기능을 Notion과 웹사이트를 연결하는 자동화 과정에 활용한다.

즉, 사람이 직접 여러 단계를 반복하는 대신 GitHub Actions가 정해진 작업을 대신 수행하도록 만드는 것이다.

🔄 우리가 만들 자동화 구조는 이렇게 작동한다

📌 한 줄 요약: Notion에서 콘텐츠를 작성하면 GitHub Actions가 데이터를 가져오고, 웹사이트를 다시 빌드한 뒤 Cloudflare Pages를 통해 변경된 내용을 배포하는 구조다.

전체 흐름을 먼저 이해하면 이후 설정 과정도 훨씬 쉽게 따라갈 수 있다.

여기서 각각의 역할을 나누어 보면 더 간단하다.

이 구조의 핵심은 방문자가 Notion에 접속하는 것이 아니라는 점이다.

Notion은 콘텐츠를 작성하고 관리하는 공간으로 사용하고, GitHub Actions가 필요한 데이터를 가져와 웹사이트를 업데이트한다. 방문자는 최종적으로 Cloudflare Pages에 배포된 웹사이트를 이용하게 된다.

🛠️ GitHub Actions Workflow를 만들어보자

📌 한 줄 요약: GitHub Actions에서 실행할 작업을 Workflow 파일로 정의하면 Notion 데이터 가져오기와 웹사이트 빌드같은 반복 작업을 자동화할 수 있다.

GitHub Actions에게 “이 작업을 해줘”라고 알려주려면 Workflow(워크플로)라는 설정이 필요하다.

Workflow는 쉽게 말해 “자동으로 어떤 작업을 어떤 순서로 실행할지 적어놓은 작업 설명서”다.

예를 들어 이번 프로젝트에서는 다음과 같은 작업을 Workflow에 정의할 수 있다.

Notion에 접근하기 → 콘텐츠 가져오기 → 웹사이트 빌드하기 → 변경사항 저장하기

GitHub Actions에서는 이러한 Workflow를 YAML 형식의 파일로 작성한다.

처음 보면 YAML이라는 형식 때문에 어렵게 느껴질 수 있다.

하지만 이번 시리즈의 목적은 YAML 문법을 처음부터 공부하는 것이 아니다.

2편에서 AI에게 웹사이트 코드를 작성하도록 요청했던 것처럼, 이번에도 AI를 활용해 필요한 Workflow를 작성하고 실제 실행 결과를 확인하면서 수정하는 방식으로 접근할 수 있다.

즉, 직접 모든 코드를 처음부터 작성하고 이해해야 하는 것은 아니다.

🤖 AI에게 GitHub Actions Workflow 작성을 요청하는 방법

📌 한 줄 요약: 현재 프로젝트의 구조와 원하는 자동화 과정을 AI에게 설명하면 GitHub Actions Workflow 작성에 필요한 초안을 만들 수 있다.

2편에서 AI에게 웹사이트의 디자인과 기능을 설명했던 것처럼 GitHub Actions도 자연어로 요구사항을 설명하면서 만들 수 있다.

예를 들어 다음과 같이 요청할 수 있다.

“현재 GitHub 저장소의 웹사이트는 Notion API를 통해 콘텐츠를 가져오는 구조야. GitHub Actions를 이용해서 정해진 시간마다 Notion 데이터를 가져오고 웹사이트를 다시 빌드할 수 있는 Workflow를 만들어줘. 필요한 환경 변수와 실행 조건도 함께 설명해줘.”

이때 중요한 것은 사용 중인 프로젝트의 실제 구조를 AI에게 함께 알려주는 것이다.

프로젝트마다 사용하는 프레임워크, 빌드 명령어, 결과물이 저장되는 위치 등이 다를 수 있기 때문이다.

따라서 AI가 만들어준 Workflow를 무조건 그대로 사용하는 것보다는 현재 프로젝트의 파일 구조와 빌드 방법을 확인한 뒤 적용하는 것이 좋다.

이 과정 역시 2편에서 했던 AI 바이브코딩과 비슷하다.

요구사항 설명 → AI가 코드 작성 → 실제 실행 → 오류 확인 → AI에게 수정 요청

이 과정을 반복하면서 현재 프로젝트에 맞는 Workflow를 완성해 나가는 것이다.

🔐 GitHub Secrets에 Notion 인증 정보 등록하기

📌 한 줄 요약: Notion API 토큰과 데이터베이스 ID 같은 민감한 정보는 Workflow 코드에 직접 입력하지 않고 GitHub Secrets에 안전하게 저장한다.

Workflow가 만들어졌다고 해서 바로 Notion의 데이터를 가져올 수 있는 것은 아니다.

3편에서 만들었던 Notion API 인증 토큰과 Database ID가 필요하다.

그런데 여기서 중요한 문제가 있다.

이런 정보를 Workflow 파일에 그대로 적어 GitHub에 저장하면 다른 사람이 볼 수 있는 위험이 있다.

그래서 GitHub에서는 API 키나 비밀번호 같은 민감한 정보를 별도로 저장할 수 있도록 Secrets 기능을 제공한다.

쉽게 표현하면 다음과 같다.

Workflow

→ “Notion 데이터를 가져와줘.”

GitHub Secrets

→ “Notion에 접근하는 데 필요한 인증 정보는 여기에 안전하게 보관해둘게.”

이렇게 역할을 분리하는 것이다.

GitHub 저장소에서 다음 메뉴로 이동한다.

Settings → Secrets and variables → Actions

그다음 New repository secret을 선택해 필요한 값을 등록한다.

예를 들어 프로젝트에서 다음과 같은 이름을 사용하도록 구성했다면,

• ‘NOTION_API_KEY’ → Notion API 인증 토큰
• ‘NOTION_DATABASE_ID’ → Notion Database ID

각각의 Secret에 실제 값을 입력한다.

단, 변수명은 사용하는 Workflow나 프로젝트 코드에서 지정한 이름과 정확하게 일치해야 한다.

따라서 위 이름을 무조건 그대로 사용해야 하는 것은 아니다. AI가 작성한 Workflow나 현재 프로젝트에서 요구하는 변수명이 있다면 그 이름을 그대로 사용해야 한다.

▶️ 직접 실행해서 정상적으로 작동하는지 확인하기

📌 한 줄 요약: 자동 실행을 설정하기 전에 GitHub Actions를 직접 실행해 Notion 데이터 가져오기부터 웹사이트 빌드까지 정상적으로 작동하는지 확인한다.

처음부터 자동 실행만 설정하는 것보다는 직접 실행해서 정상적으로 작동하는지 확인하는 과정이 중요하다.

GitHub 저장소의 Actions 메뉴에서 설정한 Workflow를 선택하고, 수동 실행 기능이 구성되어 있다면 Run workflow를 통해 실행할 수 있다.

실행이 시작되면 GitHub Actions가 각 작업을 순서대로 처리한다.

정상적으로 완료되었다면 성공 표시가 나타난다.

반대로 오류가 발생했다면 실패한 작업을 클릭해 로그를 확인할 수 있다.

초보자라면 오류 메시지가 어렵게 느껴질 수 있다.

이럴 때는 오류 내용을 그대로 AI에게 보여주고 다음과 같이 요청하면 된다.

• “GitHub Actions를 실행했는데 다음 오류가 발생했어. 현재 프로젝트의 구조를 고려해서 원인이 무엇인지 설명하고 수정 방법을 알려줘.”

이 역시 2편에서 했던 실행 → 오류 확인 → AI에게 질문 → 수정 방식과 같다.

⏰ 정해진 시간마다 자동으로 실행하기

📌 한 줄 요약: Workflow에 실행 일정을 설정하면 GitHub Actions가 정해진 주기마다 자동으로 Notion 데이터를 확인하도록 만들 수 있다.

직접 실행해서 정상적으로 작동하는 것을 확인했다면 이제 자동 실행을 설정할 차례다.

GitHub Actions에서는 Workflow가 언제 실행될지를 여러 가지 방식으로 설정할 수 있다.

예를 들어,

• GitHub 저장소에 코드가 변경되었을 때
• 사용자가 직접 실행했을 때
• 정해진 시간에 실행되도록 설정했을 때

등이 있다.

이번 프로젝트에서는 정해진 시간마다 Notion의 콘텐츠를 확인하는 방식을 사용할 수 있다.

예를 들어 1시간마다 실행하도록 설정한다면 GitHub Actions가 일정한 주기로 Notion 데이터를 확인하고 변경된 콘텐츠를 웹사이트에 반영하는 작업을 수행하게 된다.

다만 예약 실행은 정확히 설정한 시각에 실행된다고 보장되는 것은 아니다. GitHub Actions의 실행 상황에 따라 일정이 다소 지연될 수 있다.

따라서 “Notion에서 글을 저장하는 순간 웹사이트가 바로 바뀐다”라고 이해하기보다는,

“설정한 주기에 따라 GitHub Actions가 Notion의 변경사항을 확인하고 웹사이트를 업데이트한다.”

라고 이해하는 것이 정확하다.

📝 원하는 글만 웹사이트에 발행하기

📌 한 줄 요약: Notion 데이터베이스의 발행 상태를 조건으로 사용하면 작성 중인 글은 그대로 두고 공개할 콘텐츠만 웹사이트에 반영할 수 있다.

3편에서는 Notion 데이터베이스에 상태(Status) 또는 체크박스(Checkbox)를 활용해 발행 여부를 관리하는 방법을 살펴봤다.

이 기능은 자동화 과정에서도 활용할 수 있다.

예를 들어 Notion에 다음과 같이 콘텐츠가 있다고 생각해보자.

자동화 과정에서 발행 상태인 콘텐츠만 가져오도록 조건을 설정하면 작성 중인 글이 실수로 웹사이트에 공개되는 것을 막을 수 있다.

여기서 한 가지 기억해야 할 것이 있다.

발행 상태를 변경하는 것 자체가 GitHub Actions를 실행시키는 것은 아니다.

예를 들어 Notion에서 체크박스를 켰다고 해서 GitHub Actions가 바로 실행되는 것은 아니다.

설정된 실행 일정이 도래하거나 수동 실행 등의 조건이 충족되었을 때 Workflow가 실행되고, 그 과정에서 발행 상태에 맞는 콘텐츠를 가져오는 것이다.

🚨 자동화가 작동하지 않을 때 확인할 것

📌 한 줄 요약: 자동화가 정상적으로 작동하지 않는다면 Secrets, Notion 권한, Workflow 설정, 빌드 오류 순서로 확인하면 원인을 찾기 쉽다.

처음 GitHub Actions를 설정하면 한 번에 정상적으로 작동하지 않을 수도 있다.

특히 초보자가 자주 확인해야 할 부분은 다음과 같다.

① GitHub Secrets 확인

Notion API 토큰이나 Database ID의 변수명이 Workflow에서 사용하는 이름과 일치하는지 확인한다.

② Notion 권한 확인

3편에서 설정했던 Integration의 데이터베이스 접근 권한이 제대로 부여되어 있는지 확인한다.

권한이 없다면 GitHub Actions가 Notion 데이터를 가져오는 과정에서 오류가 발생할 수 있다.

③ Workflow 설정 확인

자동 실행 일정이나 실행 조건이 제대로 설정되어 있는지 확인한다.

④ 웹사이트 빌드 확인

Notion 데이터는 정상적으로 가져왔지만 웹사이트 빌드 과정에서 오류가 발생할 수도 있다.

이 경우 GitHub Actions의 실행 로그에서 어느 단계에서 실패했는지 확인한다.

⑤ Cloudflare Pages 배포 확인

GitHub 쪽 작업이 정상적으로 끝났다면 4편에서 연결한 Cloudflare Pages의 배포 상태도 확인한다.

즉, 문제가 발생했을 때는 무작정 코드를 수정하기보다 어느 단계에서 문제가 발생했는지 먼저 확인하는 것이 중요하다.

🙋‍♂️ GitHub Actions 연동, 궁금했던 점 (Q&A)

(👉 질문을 클릭하면 자세한 답변이 펼쳐집니다)

📚 웹사이트 제작 9부작 시리즈 전체 목차

Pixoas에서는 웹사이트 제작을 쉽게 따라 할 수 있도록 9편의 튜토리얼로 쪼개어 연재한다.
차근차근 따라오면 어느새 나만의 개인 웹사이트가 완성되어 있을 것이다.

• 💡 [웹사이트 제작 1편] 유지비 0원? 워드프레스 대신 노션 택한 이유
• 🎨 [웹사이트 제작 2편] AI로 코딩 없이 웹사이트 뼈대 구축하기
• 📝 [웹사이트 제작 3편] 노션을 웹사이트 CMS로 쓰는 법
• ☁️ [웹사이트 제작 4편] Cloudflare Pages로 웹사이트 배포하기
• ⚙️ [웹사이트 제작 5편] 노션 글 자동 반영! 깃허브 액션 연동법 (현재 글)
• 🚨 [웹사이트 제작 6편] 노션 이미지 엑스박스 오류 해결
• 📈 [웹사이트 제작 7편] 검색엔진 등록 & 도메인 연결
• 💰 [웹사이트 제작 8편] 애드센스 승인, 가치 없는 콘텐츠 피하기
• 🤖 [웹사이트 제작 9편] AI로 블로그 방문자 늘리기

이 시리즈는 특정 서비스를 무조건 추천하기 위한 글이 아니다. 내가 직접 여러 방법을 비교하고 운영하면서 선택한 구조를 공유하는 기록에 가깝다. 5편에서는 Notion과 GitHub Actions를 연결해 콘텐츠 업데이트 과정을 자동화하는 방법을 살펴봤다.

이어지는 6편에서는 이 구조를 실제로 운영하면서 자주 발생할 수 있는 Notion 이미지 엑스박스(깨짐) 문제의 원인과 해결 방법을 자세히 알아볼 예정이다.

✅ 마무리 정리

1. Notion의 콘텐츠를 웹사이트에 반영할 때마다 수동으로 데이터를 가져오고 다시 빌드하는 작업은 번거로울 수 있다.
2. GitHub Actions를 활용하면 Notion 데이터 가져오기, 웹사이트 빌드 등 반복적인 작업을 자동화할 수 있다.
3. GitHub Actions에서 실행할 작업은 Workflow로 정의하며, 프로젝트의 구조에 맞게 설정해야 한다.
4. Notion API 토큰과 Database ID 같은 민감한 정보는 GitHub Secrets에 저장해 Workflow에서 안전하게 사용할 수 있다.
5. Notion의 발행 상태를 조건으로 활용하면 작성 중인 콘텐츠와 실제 웹사이트에 공개할 콘텐츠를 구분할 수 있다.
6. 자동화 과정에서 오류가 발생하면 Secrets → Notion 권한 → Workflow → 빌드 → Cloudflare Pages 순서로 확인하면 문제를 찾기 쉽다.

💡 참고: GitHub Actions의 실행 방식과 무료 사용량은 GitHub의 저장소 공개 여부와 요금제, 사용하는 기능에 따라 달라질 수 있다. 또한 예약 실행은 시스템 상황에 따라 지연될 수 있으므로 특정 시각에 반드시 실행된다고 보장할 수는 없다.