GitHub Actions on monkshark.dev

GitHub 프로필에 블로그 글 자동으로 띄우기 — 네 번 막힌 기록

Mon, 08 Jun 2026 00:00:00 +0000

프로필 README(monkshark/monkshark)에 블로그 최신 글을 자동으로 띄우고 싶었다. 글을 쓸 때마다 직접 README를 고치는 건 귀찮다.

gautamkrishnar/blog-post-workflow를 쓰면 된다. README에 마커를 두 개 박아두면, 액션이 RSS를 읽어 그 사이를 최신 글로 채워준다.

1
2
3
4


## 📝 Latest Posts

<!-- BLOG-POST-LIST:START -->
<!-- BLOG-POST-LIST:END -->

처음 작성한 워크플로우는 이랬다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


name: Latest blog posts
on:
 push:
 branches: [main]
 schedule:
 - cron: "0 */6 * * *"
permissions:
 contents: write
jobs:
 update-readme:
 runs-on: ubuntu-latest
 steps:
 - uses: gautamkrishnar/blog-post-workflow@v1
 with:
 feed_list: "https://monkshark.github.io/index.xml"
 template: "- [$title]($url) <sub>$newline_$date</sub>$newline"
 date_format: "yyyy-MM-dd"

5분이면 끝날 줄 알았다. 네 번 막혔다.

1. `code: 128` — checkout이 없었다

push하니 워크플로우는 돌았는데 실패했다. 로그를 보면 피드는 멀쩡히 가져왔다.

1
2


https://monkshark.github.io/index.xml runner succeeded. Post count: 29
##[error]{"code":128,"outputData":""}

글은 잘 읽었는데 마지막 커밋 단계에서 code: 128. git의 exit 128은 보통 “여긴 git 저장소가 아니다"다. 당연했다. 워크플로우에 actions/checkout이 없으니, 러너에는 README는커녕 .git조차 없었다. 액션이 커밋하려는데 저장소가 없으니 터진 것.

1
2
3


 steps:
 - uses: actions/checkout@v4  # 이게 없었다
 - uses: gautamkrishnar/blog-post-workflow@v1

체크아웃을 넣으니 다음 단계로 넘어갔다. 그리고 더 황당한 게 기다리고 있었다.

2. `2026-00-30` — dateformat의 `MM`은 월이 아니다

이제 글 목록은 채워졌는데 날짜가 이랬다.

1
2


- [#13 - ...] 2026-00-30
- [#11 - ...] 2026-55-14

00월? 55월? date_format: "yyyy-MM-dd"를 줬는데 월 자리에 이상한 숫자가 들어갔다.

원인은 이 액션이 쓰는 dateformat 라이브러리의 토큰 규칙이었다. 흔히 아는 Java SimpleDateFormat이나 date-fns와 다르다.

토큰	dateformat에서의 의미
`mm`	월 (01–12)
`MM`	분 (00–59)

즉 MM은 월이 아니라 분이다. 2026-00-30은 “분이 00”, 2026-55-14는 “분이 55"였던 것. 글이 작성된 시각의 분이 월 자리에 박혀 있었다.

1

 date_format: "yyyy-mm-dd" # MM → mm

mm으로 바꾸니 2026-05-30이 제대로 나왔다. 대소문자 하나 차이로 한참 들여다봤다.

3. 첫 글이 사라진다 — HTML 주석에 붙은 리스트

날짜는 고쳤는데, 이번엔 첫 번째 글만 렌더링이 깨졌다. 나머지 넷은 멀쩡한 불릿인데 첫 줄만 텍스트로 풀려버렸다.

원인은 마커였다. 액션은 START 주석 바로 뒤에 내용을 이어 붙인다. 내 템플릿이 ...$newline으로 끝나니, 결과가 이렇게 됐다.

1
2


<!-- BLOG-POST-LIST:START -->- [#13 - ...] <sub>2026-05-30</sub>
- [#12 - ...] <sub>2026-05-23</sub>

첫 글이 와 같은 줄에 붙어 있다. Markdown에서 리스트 항목의 -는 줄 맨 앞에 와야 하는데, 앞에 주석이 있으니 첫 줄은 리스트로 인식되지 않는다.

해결은 템플릿 앞쪽에 줄바꿈을 두는 것. 그러면 첫 글이 주석 다음 줄에서 시작한다.

1

 template: "$newline- [$title]($url) <sub>$date</sub>"

1
2


<!-- BLOG-POST-LIST:START -->
- [#13 - ...] <sub>2026-05-30</sub> ← 이제 자기 줄에서 시작

4. 권한: 워크플로우가 저장소 설정을 못 이긴다

사실 위 세 개를 고치는 사이, 더 먼저 막혔던 게 권한이었다. 워크플로우에 분명히 이렇게 적어뒀는데도 커밋이 거부됐다.

1
2


permissions:
 contents: write

워크플로우 레벨의 permissions는 저장소 기본 설정을 넘어설 수 없다. 저장소 기본이 read-only면, YAML에서 write를 선언해도 토큰은 read-only로 발급된다. 워크플로우 권한은 “상한선 안에서 줄이는” 용도지, “상한선을 올리는” 용도가 아니다.

저장소 설정에서 한 번 열어줘야 한다.

Settings → Actions → General → Workflow permissions → Read and write permissions

이걸 켜고 나서야 커밋이 통과했다.

최종 워크플로우

네 번을 거쳐 정착한 형태.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


name: Latest blog posts
on:
 schedule:
 - cron: "0 */6 * * *"
 workflow_dispatch:
 push:
 branches: [main]
permissions:
 contents: write
jobs:
 update-readme:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Pull latest posts into README
 uses: gautamkrishnar/blog-post-workflow@v1
 with:
 feed_list: "https://monkshark.github.io/index.xml"
 max_post_count: 3
 template: "$newline- [$title]($url) <sub>$date</sub>"
 date_format: "yyyy-mm-dd"
 commit_message: "chore: update latest blog posts"

마무리

네 번의 실패는 종류가 전부 달랐다.

checkout 누락 — 액션이 동작할 전제를 안 깔아줬다
MM vs mm — 라이브러리마다 포맷 토큰이 다르다는 걸 잊었다
주석에 붙은 첫 줄 — 출력이 어디에 어떻게 삽입되는지 안 봤다
권한 상한선 — 선언한 권한과 실제 발급되는 권한은 다르다

네 개를 관통하는 한 줄은, “되겠지” 하고 넘긴 전제마다 정확히 한 번씩 막혔다는 것이다. 5분짜리 액션도 남의 추상 위에서 돌아가는 한, 그 추상이 어디서 새는지는 직접 밟아봐야 안다.

#11 - rate limit 한 줄에서 4계층 fallback 까지

Thu, 21 May 2026 20:00:00 +0900

LSP 설치 다이얼로그를 열었더니 버전 목록 자리가 비어 있었다. 한 줄짜리 안내가 떠 있었다 — “no version available (network or rate limit)”. 네트워크는 안 죽었고, 다른 사이트는 다 잘 응답했다. 남은 단어 하나가 그날의 과제였다.

한 줄짜리 메시지의 뒤편

PAGE 의 KLS (Kotlin Language Server) 설치 흐름은 GitHub Releases API 두 곳을 호출한다 — Monkshark fork 한 번, fwcd upstream 한 번. 다이얼로그를 열 때마다 두 번씩 친다. 문제는 GitHub API 의 익명 호출이 IP 당 시간당 60 회로 묶여 있다는 점이다. 한 명이 다이얼로그를 몇 번 여닫으면 두 자리수가 그어지고, NAT 뒤의 여러 사람이 같이 쓰는 IP 라면 한 사람이 열기 전에 이미 한도가 차 있을 수 있다.

배포 시나리오를 생각하면 더 분명해진다. PAGE 가 손에 닿는 사람이 늘수록 — 회사 네트워크, 학교 네트워크, 같은 ISP — IP 한 자리에 한도가 누적된다. “no version available” 이 사람 손이 아니라 시간대의 함수가 된다. 처음 깔자마자 다이얼로그를 열었는데 비어 있으면 두 번 다시 열지 않을 사람이 많다.

첫 우회 — cache + ETag, 응답 회로 한 번 줄이기

가장 가까운 해결은 응답 한 번을 디스크에 적어 두고, 다음 호출이 같은 시간대 안이면 그걸 그대로 쓰는 것. TTL 한 시간으로 잡았다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


object LspReleasesCache {

 data class Cached(
 val fetchedAt: Long,
 val source: String,
 val etagFork: String?,
 val etagUpstream: String?,
 val etagManifest: String?,
 val fork: List<TaggedRelease>,
 val upstream: List<TaggedRelease>,
 )

 const val DEFAULT_TTL_MS: Long = 60 * 60 * 1000L

 fun isFresh(cached: Cached?, now: Long = System.currentTimeMillis(), ttlMs: Long = DEFAULT_TTL_MS): Boolean {
 if (cached == null) return false
 return (now - cached.fetchedAt) < ttlMs
 }
}

TTL 한 시간 안에서는 디스크 한 번 읽고 끝. API 호출 0 회. 그 뒤에도 응답 자체가 안 바뀌었을 가능성이 높으니까 ETag 를 같이 들고 다닌다 — If-None-Match 헤더로 보내면 서버가 304 만 돌려준다. 그 304 응답도 rate limit 카운터에는 잡힌다 (GitHub 쪽 정책이 그렇다) 는 점이 한 가지 함정. 그래서 ETag 는 호출 횟수의 절감이 아니라 응답 본문 다운로드의 절감이다.

여기까지만 했을 때 한 사람의 사용 패턴은 견딘다. 한 시간에 한 번씩 두 번 친다고 가정하면 시간당 두 자리 호출. 한도 안쪽. 그러나 한 IP 에 사람이 여럿이면 — 한 한도를 N 명이 나눠 쓰는 구조 — 이 계산은 N 으로 나뉜다. 한 계층 더 필요했다.

두 번째 우회 — static manifest, API 의존 자체 빼기

다음 자리의 결정은 한 줄로 적으면 — API 를 쓰지 않는 길을 메인 경로로 만들기. PAGE 의 docs 가 이미 monkshark.github.io/page-ide 로 Pages 서빙되고 있었다. 같은 자리에 fork + upstream 의 release 목록을 JSON 한 파일로 적어 두면, IDE 는 그 한 파일만 받아서 쓰면 된다.

1
2
3
4
5
6
7
8


object KlsReleasesManifest {

 const val DEFAULT_URL: String = "https://monkshark.github.io/page-ide/lsp/kotlin.json"

 fun fetch(url: String = DEFAULT_URL, ifNoneMatch: String? = null): FetchedManifest? {
 return runCatching { fetchOrThrow(url, ifNoneMatch) }.getOrNull()
 }
}

GitHub Pages 는 CDN 뒤에 있고, rate limit 이 없다. 한 명이든 만 명이든 같은 정적 파일을 받아 가는 사람이 누구든. fetch 가 실패하면 그제서야 live API 로 fall back. 평소 경로에서는 API 한 번 안 친다.

그래서 호출 우선순위가 이렇게 정렬됐다.

1
2
3
4


disk cache (fresh)
 → static manifest (ETag/304)
 → live API (Monkshark + fwcd)
 → installed labels (오프라인 마지막 보루)

네 계층 어디에서 끊겨도 다이얼로그는 비지 않는다. 한 자리에 한도가 차도 옆자리가 받는다.

자동화 — manifest 를 누가 갱신할 것인가

문제는 그 manifest 가 stale 해지면 안 된다는 점이다. 새 KLS release 가 fork 든 upstream 이든 나왔는데 manifest 가 어제 자라면 IDE 는 새 버전을 모른다. 그래서 manifest 갱신은 사람 손이 아니라 GitHub Actions 한 잡이어야 했다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


name: Update KLS release manifest

on:
 schedule:
 - cron: '0 3 * * *'
 workflow_dispatch:

permissions:
 contents: write
 pull-requests: write

jobs:
 refresh:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Generate manifest
 uses: actions/github-script@v7
 with:
 script: |
 const fork = await fetchReleases('Monkshark', 'kotlin-language-server');
 const upstream = await fetchReleases('fwcd', 'kotlin-language-server');
 fs.writeFileSync('docs/lsp/kotlin.json', JSON.stringify({ fork, upstream }, null, 2) + '\n');
 - name: Create pull request
 id: cpr
 uses: peter-evans/create-pull-request@v6
 with:
 token: ${{ secrets.MANIFEST_BOT_PAT }}
 branch: chore/kls-manifest-refresh
 - name: Enable auto-merge
 if: steps.cpr.outputs.pull-request-number
 env:
 GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 run: gh pr merge --auto --squash --delete-branch "${{ steps.cpr.outputs.pull-request-number }}"

매일 03:00 UTC 에 fork + upstream release 목록을 다시 그려서 PR 을 띄우고, 그 PR 에 즉시 auto-merge 플래그를 켠다. CI 가 통과하면 사람 손 없이 머지된다. 사람이 손댈 일은 — 이론상 — 0.

이론상.

두 함정

처음 굴렸을 때 두 자리에서 멈췄다.

첫째는 workflow 정의 스냅샷 타이밍. workflow_dispatch 로 첫 실행을 손으로 트리거했더니 이전 워크플로 정의로 돌았다. peter-evans 의 PR 생성까지는 됐는데 auto-merge step 이 없는 옛 버전이라 PR 이 그냥 떠 있었다. 두 번째 실행부터는 새 정의로 갈아엎혔다. GitHub Actions 의 workflow_dispatch 가 트리거 시점의 정의를 잡는다는 점, 그리고 그 시점이 항상 main 의 가장 최근이라고는 못 한다는 점을 그때 알았다.

두 번째 함정이 더 무거웠다. auto-merge 플래그가 켜졌는데 PR 이 BLOCKED 로 멈췄다. 이유 — “Required status check ‘Gradle build’ is expected.” 그런데 CI 가 아예 돌지 않았다. peter-evans 가 push 를 GITHUB_TOKEN 으로 했고, GitHub 의 보안 정책상 GITHUB_TOKEN 으로 push 된 commit 은 자식 워크플로 (CI) 를 트리거하지 않는다. 무한 재귀 방지의 안전장치인데, 이 자리에서는 정확히 안전장치가 자동화를 막는 자리가 됐다.

해결은 fine-grained PAT (Personal Access Token) 을 따로 발급해서 secret 으로 박는 것. peter-evans 가 그 토큰으로 push 하면, GitHub 입장에서는 사용자 권한의 commit 이라 자식 워크플로가 정상적으로 트리거된다.

1
2
3
4
5


- name: Create pull request
 id: cpr
 uses: peter-evans/create-pull-request@v6
 with:
 token: ${{ secrets.MANIFEST_BOT_PAT }}

이 한 줄을 더한 다음 실행에서 PR #74 가 12:34:17Z 에 생성됐고, 같은 워크플로 안에서 auto-merge 가 12:34:20Z 에 켜졌고, CI 가 정상적으로 트리거돼서 12:35:00Z 에 머지됐다. 43 초, 사람 손 0 회.

돌아보면

“no version available” 한 줄이 보였을 때 그게 GitHub Actions 의 자식 워크플로 트리거 정책까지 들춰 보게 될 일이라고는 짐작 못 했다. 한 자리에서 시작해서 인접한 자리를 한 번씩 옮겨 가며 — cache → ETag → static manifest → automation → PAT → child workflow trigger 정책 — 한 계열의 결정이 줄로 이어졌다. 한 발이 다음 한 발의 자리를 정하는 식의 진행.

네 계층 fallback 이라는 결과 자체보다, 그 네 계층이 같은 IP 한 자리에 응답을 누가 줄 거냐 라는 한 질문의 네 가지 답이라는 점이 더 기억에 남는다. cache 는 자기 디스크가 답하고, manifest 는 CDN 이 답하고, live API 는 GitHub 이 답하고, installed labels 는 이미 받아 둔 파일이 답한다. 어느 한 자리가 멈춰도 옆자리가 답을 한다. rate limit 한 줄이 가르친 게 있다면 — 한 응답의 근거를 한 자리에만 두지 않기.

그리고 자동화의 마지막 한 자리. gh pr merge --auto --squash --delete-branch 가 띄운 그 43 초가 사람 손이 닿을 자리를 한 자리 더 줄였다. 매일 03:00 UTC 의 cron 한 줄이, 다음 사람이 PAGE 를 깔았을 때 다이얼로그에 든 버전 목록 한 칸이 비어 있지 않게 한다.