Claude Code에게 "Qiita와 GitHub의 자동 게시 연동을 만들어줘"라고 통째로 맡겨본 제작기

「Claude Code에서의 대화를 Qiita 기사로 남기고 싶다」는 생각에, 그 메커니즘을 만드는 것 자체를 Claude Code에게 통째로 맡겨본 기록입니다.

최종적으로 「로컬에서 Markdown을 편집하고 git push를 하면, GitHub Actions가 Qiita로 자동 게시해 주는」 환경이 완성되었습니다. 대화의 흐름을 거의 그대로, 막혔던 부분까지 포함하여 남깁니다.

환경: Windows 11 / PowerShell / Node.js v22 / Claude Code

처음에는 대략적인 상담부터 시작했습니다. 돌아온 선택지는 크게 3가지였습니다.

(A) GitHub에서 기사를 버전 관리 → Qiita로 자동 게시하는 메커니즘 -
(B) 대화 로그에서 기사 소재를 반자동으로 추출하는 메커니즘 -
(C) 우선 수동으로 1건 작성

정석적인 방법으로 추천받은 것이 Qiita 공식의 「Qiita CLI」 + GitHub Actions 조합입니다. 기사를 Markdown으로 리포지토리(Repository) 관리하면서, push로 자동 게시할 수 있습니다. (A)를 선택했습니다.

mkdir qiita-articles; cd qiita-articles
git init
npm install @qiita/qiita-cli --save-dev
...

npx qiita init

을 실행하자 다음과 같이 자동 생성되었습니다.

파일	역할
.github/workflows/publish.yml	main/master로 push할 때 Qiita로 자동 게시하는 Actions
qiita.config.json	Qiita CLI 설정
.gitignore	node_modules 등을 제외

Qiita → 설정 → 애플리케이션 → 개인용 액세스 토큰(Personal Access Token) (스코프 read_qiita + write_qiita)을 발행하여,

npx qiita login # 토큰을 붙여넣기 (대화형 입력)

npx qiita pull

이 Successful!

을 반환하면 인증 OK.

💡

배운 점: 토큰 입력은 대화형(Interactive) 방식입니다. AI 에이전트에게 대행시키지 않고, 자신의 터미널에서 직접 입력하는 것이 안전합니다.

npx qiita new 기사명

으로 생성되는 .md 파일의 상단은 다음과 같습니다.

---
title: 기사 제목
tags:
...

포인트는 id: null 상태로 push하면 신규 게시가 되고, ID가 채번되어 이 파일에 다시 기록된다는 점입니다. 이후에는 동일한 파일을 편집하여 push하면 「갱신」이 됩니다. 신규 게시와 갱신 모두 동일한 작업으로 끝나는 점이 쾌적합니다.

여기서부터가 본론입니다. 실제로 막혔던 부분을 그대로 남깁니다.

gh auth status

를 입력하면 gh는 인식되지 않습니다라는 메시지가 뜹니다. winget도 마찬가지입니다.

→ 실체를 직접 호출하여 해결.

& "C:\Program Files\GitHub CLI\gh.exe" auth status

gh 자체는 설치되어 있었습니다 (PATH가 설정되지 않았을 뿐).

gh repo create ... --push

를 했더니, 리포지토리는 생성되었으나 push만 거부되었습니다.

! [remote rejected] HEAD -> main
(refusing to allow an OAuth App to create or update workflow
`.github/workflows/publish.yml` without `workflow` scope)

.github/workflows/ 하위 파일을 push하려면 OAuth 토큰에 workflow 스코프가 필요하다는 GitHub의 보안 사양 때문입니다.

gh auth refresh -h github.com -s workflow # 브라우저 인증으로 1회 추가

이로써 재 push가 통과되었습니다.

push로 실행된 첫 번째 Actions는 failure였습니다. 이유는 그 시점에 QIITA_TOKEN의 Secret을 아직 등록하지 않았기 때문입니다.

gh secret set QIITA_TOKEN --repo <owner>/qiita-articles # 토큰을 붙여넣기

Secret 등록 후 수동으로 재실행했더니 success.

gh workflow run "Publish articles" --repo <owner>/qiita-articles

💡

배운 점: 「push → Actions 실패」는 순서의 문제일 뿐이다. Secret을 입력한 후 workflow run으로 다시 실행하면 통과한다.

로컬에서 public/*.md 편집
│ git push (main)
▼
...

그리고 실제로, 이 기사의 바탕이 된 샘플 기사가 Qiita 측에 id가 포함된 상태로 등록되고, git pull을 통해 로컬로 ID가 다시 써지는 것까지 확인할 수 있었다. 사이클이 한 바퀴 돌아간 순간은 소소하게 감동적이었다.

cd qiita-articles
npx qiita new 기사명 # 신규 (임의)
# public/ 의 .md 편집
...

private: true인 기사는 한정 공유 (초안). 공개 시 false로 변경하여 push - 토큰은 채팅이나 커밋에 붙여넣지 말 것. 유출되면 무효화 → 재발급

• Qiita CLI + GitHub Actions로 「push 하면 Qiita에 반영」을 만들 수 있음
• 주의할 점은 workflow 스코프와 Secret 등록 순서 이 두 가지가 거의 전부 - 셋업 자체를 AI 에이전트에게 맡기더라도, 토큰 입력과 브라우저 인증만은 직접 수행하는 것이 안전함

이 기사 자체도 그 메커니즘을 통해 게시되었습니다.