@uzysjung/agent-harness 26.177.0 → 26.178.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/{chunk-JIVFWRYB.js → chunk-543MIQR5.js} +16 -2
- package/dist/chunk-543MIQR5.js.map +1 -0
- package/dist/index.js +39 -7
- package/dist/index.js.map +1 -1
- package/dist/trust-tier-drift.js +1 -1
- package/package.json +1 -1
- package/templates/rules/ship-checklist.md +1 -1
- package/templates/rules/test-policy.md +8 -8
- package/templates/settings.json +1 -1
- package/templates/skills/self-hosted-github-runner/SKILL.md +78 -45
- package/templates/skills/self-hosted-github-runner/scripts/runner.sh +205 -0
- package/dist/chunk-JIVFWRYB.js.map +0 -1
package/dist/trust-tier-drift.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@uzysjung/agent-harness",
|
|
3
|
-
"version": "26.
|
|
3
|
+
"version": "26.178.0",
|
|
4
4
|
"description": "Curate vetted AI-coding skills & plugins by your tech stack — install only what you need, across Claude Code, Codex, OpenCode & Antigravity",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"publishConfig": {
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
무엇으로 검증할지는 이 저장소가 정한다. **어느 정도까지**는 Testing 룰이, 그 결과가 **언제** 있어야 하는지는 이 룰이 정한다.
|
|
4
4
|
|
|
5
|
-
- **검증의 리듬**: 구현 중에는 변경 부분의 빠른 검사만 한다. 사용자 씬의 수정분이 모였을 때가 독립 검토를 **판단하는** 시점이다 — 걸지는 아래 머지 전 기준으로 정한다. 수정이 끝난 뒤 통합 테스트 · 빌드 ·
|
|
5
|
+
- **검증의 리듬**: 구현 중에는 변경 부분의 빠른 검사만 한다. 사용자 씬의 수정분이 모였을 때가 독립 검토를 **판단하는** 시점이다 — 걸지는 아래 머지 전 기준으로 정한다. 수정이 끝난 뒤 영향받은 통합 테스트 · 빌드 · 바뀐 사용자 흐름을 검증한다(전체 스위트 · 전체 E2E 는 배포 몫). 작은 수정마다 전체 검증을 반복하지 않고, 재검사는 영향받은 부분만 한다. 계획·위임문에 적었다는 것만으로는 검증을 넓히지 않는다.
|
|
6
6
|
- **머지 전 독립 검증**은 핵심 사용자 기능 · 되돌리기 어려운 변경 · 돈·권한처럼 틀리면 큰 사고인 것에만 건다. UX 의 큰 변경은 사용자 페르소나 리뷰(선택). 그 밖(테스트 하네스 · 문서 · 리팩터 · 문구 · UI · 리뷰어 처방)은 리그레션 테스트로 들어온다. 독립 검증의 판정은 만든 쪽이 아니라 검증자가 요구사항·변경분·결과를 직접 확인하고 내린다. 어느 쪽이든 변경 위험에 맞는 검증을 **실행하고 결과를 확인한다** — high risk 는 더 많은 증거를 갖고 들어오고, **실행하지 않은 상태는 통과가 아니다.** 필수 보안 · 데이터 보호 검사는 유지한다.
|
|
7
7
|
- **배포**: 배포 전에 풀 테스트 · E2E 를 거친다(Testing 룰의 CI/CD 일정 몫). 독립 검증은 **단계가 아니라** 머지 전과 같은 기준(영향 · 불확실성 · 복구 비용 · 이미 있는 증거)으로 판단한다 — 배포라는 이유로 다시 걸지 않는다. 머지 전에 검증된 것과 **같은 artifact** 를 내보내고, 배포 뒤 실제 환경에서 smoke · health · 핵심 기능을 확인한다.
|
|
8
8
|
- **머지·게시 경로가 위 기준대로 고른 검증과 저장소의 필수 체크 통과에 의존해야 한다.** 별개 경로면 아무도 우회하려 하지 않았는데 red 가 그대로 나간다. 의존하지 않는 상태를 발견하면 경로를 고치기 전에 먼저 보고한다.
|
|
@@ -3,10 +3,12 @@
|
|
|
3
3
|
**How far** to verify scales with the risk of the change; **when** those results must exist
|
|
4
4
|
belongs to the Delivery rule.
|
|
5
5
|
|
|
6
|
-
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
6
|
+
- **Before running tests, name the affected scope** — what changed and which tests exercise it,
|
|
7
|
+
including the callers, data, and configuration it shares — and run that with static checks.
|
|
8
|
+
Widen only for a reason you can name: shared code or configuration changed, the scope cannot be
|
|
9
|
+
established (widen along what it shares, not to the whole suite), or a high-risk area below, in
|
|
10
|
+
proportion to what it touches and what failure would cost. Independent verification only where
|
|
11
|
+
the Delivery rule requires it.
|
|
10
12
|
- Preserve required outcomes with the least burdensome reliable protection.
|
|
11
13
|
Prefer fixing the cause and reusing or improving existing mechanisms within scope;
|
|
12
14
|
no new guard is needed when those suffice. Judge safeguards by credible risk,
|
|
@@ -20,7 +22,7 @@ belongs to the Delivery rule.
|
|
|
20
22
|
- High-risk includes at least authentication, authorization, payments and settlement, personal
|
|
21
23
|
data, data integrity, concurrency, state transitions, and migrations.
|
|
22
24
|
- Full regression, full E2E, full mutation, and periodic security scanning belong to the CI/CD
|
|
23
|
-
schedule
|
|
25
|
+
schedule and the release step. For an ordinary change, ask before running them.
|
|
24
26
|
- For a high-risk change, cover normal, boundary, failure, misuse, and recovery paths,
|
|
25
27
|
omitting one only when failure on it is not plausible.
|
|
26
28
|
- Use production-compatible dependencies when a substitute's behavioral differences could affect
|
|
@@ -30,6 +32,4 @@ belongs to the Delivery rule.
|
|
|
30
32
|
adding indiscriminate retries. Correct or consolidate tests when their expectations are
|
|
31
33
|
wrong, obsolete, or redundant; preserve coverage of the accepted contract and follow project
|
|
32
34
|
policy for changes to mandatory gates.
|
|
33
|
-
-
|
|
34
|
-
(callers, data, configuration), not to the whole suite by default. After an environment or CI
|
|
35
|
-
fix, rerun what failed and what the fix could affect.
|
|
35
|
+
- After an environment or CI fix, rerun what failed and what the fix could affect.
|
package/templates/settings.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"_comment": "프로젝트 .claude/settings.json 템플릿. $CLAUDE_PROJECT_DIR 사용으로 절대 경로 제거. committable. 글로벌 ~/.claude/settings.json은 절대 건드리지 않음.",
|
|
3
3
|
"statusLine": {
|
|
4
4
|
"type": "command",
|
|
5
|
-
"command": "npx -y @owloops/claude-powerline@1.32.
|
|
5
|
+
"command": "npx -y @owloops/claude-powerline@1.32.5 --style=tui"
|
|
6
6
|
},
|
|
7
7
|
"hooks": {
|
|
8
8
|
"SessionStart": [
|
|
@@ -61,28 +61,28 @@ jobs:
|
|
|
61
61
|
|
|
62
62
|
전 잡에 적용해야 한다. 하나라도 빠뜨리면 그 잡만 호스티드를 기다리다 영원히 큐에 남는다.
|
|
63
63
|
|
|
64
|
-
## Step 2 —
|
|
64
|
+
## Step 2 — Mac 에서는 네이티브 arm64 로 띄우고, 실제 실행으로 확인한다
|
|
65
65
|
|
|
66
|
-
|
|
67
|
-
것들이 여기서 깨진다. 두 선택지가 있고, **추측하지 말고 재라**:
|
|
66
|
+
Apple Silicon Mac 에서 amd64 컨테이너는 에뮬레이션으로 돈다. 같은 잡이 이만큼 차이 난다:
|
|
68
67
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
console.log('$P ms='+(Date.now()-s));"
|
|
74
|
-
done
|
|
75
|
-
```
|
|
68
|
+
| 실측(M-series) | linux/arm64 | linux/amd64 |
|
|
69
|
+
|---|---|---|
|
|
70
|
+
| 정수 루프 마이크로벤치(Docker Desktop) | 127ms | 497ms |
|
|
71
|
+
| 실제 CI `checks` 잡 — npm ci · typecheck · lint · 테스트 685개(OrbStack, 2026-10-30) | **55~100초**(3회) | 3분 35초 |
|
|
76
72
|
|
|
77
|
-
|
|
73
|
+
그래서 [`scripts/runner.sh`](scripts/runner.sh) 는 **호스트 아키텍처를 기본값**으로 쓴다(Apple
|
|
74
|
+
Silicon → `linux/arm64`). 다만 속도는 **의존성이 그 아키텍처에서 실제로 도는 다음**의 기준이다 —
|
|
75
|
+
네이티브 모듈 하나만 prebuild 가 없어도 스위트가 통째로 죽는다. 그 확인을 추측이나 벤치마크가
|
|
76
|
+
아니라 **실제 워크플로 1회**로 한다:
|
|
78
77
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
78
|
+
- 첫 실행에서 설치·빌드·테스트가 통과하면 arm64 를 계속 쓴다. 위 실측 레포가 이 경우다.
|
|
79
|
+
- 네이티브 모듈·바이너리 실패가 나오면 코드 결함으로 읽기 전에 **같은 커밋을 `PLATFORM=linux/amd64`
|
|
80
|
+
로 한 번 더 돌려 대조한다.** amd64 에서만 통과하면 아키텍처 문제다(아래 함정들). 대조 없이 고치기
|
|
81
|
+
시작하면 "CI 환경이 달라서인가"를 끝내 지우지 못한다.
|
|
82
|
+
- **amd64 로 고정하는 경우**: 워크플로가 amd64 전용 바이너리를 받거나, 이 실행이 배포 산출물을
|
|
83
|
+
만든다(산출물이 `ubuntu-latest` 의 것과 같아야 한다).
|
|
82
84
|
|
|
83
|
-
|
|
84
|
-
prebuild 를 갖고 있다"를 확인한 뒤에 성능 최적화로 택하라. 아키텍처를 맞춰 두면 실패했을 때
|
|
85
|
-
"CI 환경이 달라서인가"를 먼저 의심하지 않아도 된다 — 그 의심을 지우는 값이 3.9배보다 크다.
|
|
85
|
+
보고에는 어느 아키텍처에서 돌았는지 적는다(§보고할 때).
|
|
86
86
|
|
|
87
87
|
### 흔히 깨지는 것: 아키텍처 하드코딩된 도구 설치
|
|
88
88
|
|
|
@@ -164,28 +164,40 @@ npm 캐시인가"로 몇 시간 쫓다가 결국 `ldd` 한 줄로 끝냈다.
|
|
|
164
164
|
docker run --rm --entrypoint sh <이미지> -c 'grep PRETTY_NAME /etc/os-release; ldd --version | head -1'
|
|
165
165
|
```
|
|
166
166
|
|
|
167
|
-
|
|
167
|
+
띄우기·내리기·상태 확인은 함께 들어 있는 스크립트 하나가 한다. 레포 루트에서 실행한다:
|
|
168
168
|
|
|
169
169
|
```bash
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
cat > "$ENVFILE" <<EOF
|
|
174
|
-
REPO_URL=https://github.com/<owner>/<repo>
|
|
175
|
-
RUNNER_NAME=local-docker
|
|
176
|
-
RUNNER_TOKEN=$TOKEN
|
|
177
|
-
RUNNER_WORKDIR=/tmp/runner/work
|
|
178
|
-
LABELS=<고유 라벨>
|
|
179
|
-
EPHEMERAL=true
|
|
180
|
-
EOF
|
|
181
|
-
|
|
182
|
-
docker run -d --name ci-runner --env-file "$ENVFILE" \
|
|
183
|
-
-v ci-runner-work:/tmp/runner myoung34/github-runner:latest
|
|
184
|
-
rm -f "$ENVFILE"
|
|
185
|
-
|
|
186
|
-
gh variable set CI_RUNNER_LABEL --body '<고유 라벨>' --repo <owner>/<repo>
|
|
170
|
+
bash <이 스킬 폴더>/scripts/runner.sh up --jobs 2 # 러너가 뜬 뒤 변수 설정 + 잡 2개를 차례로 처리
|
|
171
|
+
bash <이 스킬 폴더>/scripts/runner.sh status
|
|
172
|
+
bash <이 스킬 폴더>/scripts/runner.sh down # 원복(Step 5)
|
|
187
173
|
```
|
|
188
174
|
|
|
175
|
+
**`up` 은 N 개 잡이 끝날 때까지 터미널을 붙잡는다.** 백그라운드나 별도 셸에서 띄우고, `runner 1/N
|
|
176
|
+
listening` 이 찍힌 **뒤에** `gh run rerun` · `gh workflow run` 을 실행한다 — 변수는 그때 설정되므로,
|
|
177
|
+
먼저 재실행하면 잡이 다시 호스티드로 가서 실패하고 `up` 은 오지 않을 잡을 기다린다. `up` 이 끝난 뒤
|
|
178
|
+
`down` 한다.
|
|
179
|
+
|
|
180
|
+
`<이 스킬 폴더>` 를 빼고 `scripts/runner.sh` 로 부르지 마라 — 레포 루트에서는 그 레포 자신의
|
|
181
|
+
`scripts/` 를 가리킨다. 스크립트가 출력하는 원복 명령은 자기 경로를 그대로 쓴다.
|
|
182
|
+
|
|
183
|
+
기본값은 이렇다 — 레포는 `gh repo view`, 라벨은 `<레포 이름>-local`, 이미지는
|
|
184
|
+
`myoung34/github-runner:ubuntu-noble`(24.04), 아키텍처는 호스트 하드웨어 것(Rosetta 셸에서도 arm64).
|
|
185
|
+
`REPO` · `LABEL` · `IMAGE` · `PLATFORM` 환경변수로 바꾼다. 기본 라벨·이름은 이 레포에서 스크립트를
|
|
186
|
+
쓰는 모든 사람에게 같으므로, 두 사람이 동시에 띄우지 말거나 서로 다른 `LABEL` 을 쓴다. 이럴 때는 아무것도 바꾸지 않고 멈춘다:
|
|
187
|
+
private 이 아닌 레포(public · internal) · fork PR 워크플로가 켜진 private 레포 · `CI_RUNNER_LABEL` 에 남의 값이 이미 있음 · 다른 이름의 러너가 이미 같은 라벨을 달고 있음(대소문자 무시 — 상시 러너의 라벨을 `LABEL` 로 빌려 쓰지 마라) · GitHub 상태를 읽지 못함(인증·네트워크 —
|
|
188
|
+
"없음"으로 읽지 않는다) · 러너가 뜨지 않음(변수는 러너가 `Listening for Jobs` 를 찍은 뒤에야 설정한다).
|
|
189
|
+
스크립트는 아래 세 기본값을 그대로 구현한다 — 손으로 띄울 때도 같은 이유로 지킨다.
|
|
190
|
+
|
|
191
|
+
### Mac 호스트에서 알아 둘 것
|
|
192
|
+
|
|
193
|
+
- OrbStack 에서 실측했다(2026-10-30). Docker Desktop · Colima 는 이 스크립트로 아직 돌려 보지 않았다.
|
|
194
|
+
토큰 파일을 `$HOME` 아래에 만들어 마운트하므로, 엔진이 홈 디렉터리를 공유해야 한다(원격
|
|
195
|
+
`DOCKER_HOST` · 원격 context 는 안 된다). 자원은 §자원.
|
|
196
|
+
- 이미지를 받을 때 macOS 가 **키체인 접근 허용**을 물을 수 있다. `~/.docker/config.json` 의
|
|
197
|
+
`"credsStore": "osxkeychain"` 때문에 Docker CLI 가 레지스트리 자격증명을 키체인에서 찾는 것이다 —
|
|
198
|
+
OrbStack·러너 문제가 아니다. 거부하면 공개 이미지도 받기가 실패할 수 있다. 전역 Docker 설정이므로
|
|
199
|
+
바꿀지는 사용자가 정한다.
|
|
200
|
+
|
|
189
201
|
### 안전한 기본값 세 가지 — 하나씩 이유가 있다
|
|
190
202
|
|
|
191
203
|
**1. 라벨에 `self-hosted` 를 쓰지 마라.** GitHub 이 **모든** self-hosted 러너에 자동으로 붙이는
|
|
@@ -195,9 +207,26 @@ gh variable set CI_RUNNER_LABEL --body '<고유 라벨>' --repo <owner>/<repo>
|
|
|
195
207
|
**2. `EPHEMERAL=true`.** 비-ephemeral 러너는 잡 사이에 작업 디렉터리와 프로세스 상태가 남는다 —
|
|
196
208
|
한 잡이 심어 놓은 것이 다음 잡에서 실행된다(러너 오염). ephemeral 이면 잡 하나를 처리하고
|
|
197
209
|
등록을 스스로 해제한다. **다음 잡을 돌리려면 다시 띄워야 해서 불편한데, 그 불편이 곧 격리다.**
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
210
|
+
잡이 여럿인 워크플로(`checks` → `ci-gate` 처럼 `needs:` 로 이어진 것)는 `--jobs N` 으로 그 수만큼
|
|
211
|
+
차례로 다시 띄운다. N 은 이 이벤트가 **실제로 돌릴** 잡 수다 — matrix 다리는 하나씩 세고, `if:` 로
|
|
212
|
+
건너뛰는 잡은 세지 않는다. 많이 세면 `up` 이 마지막 잡을 영영 기다리고, 적게 세면 남은 잡이 큐에
|
|
213
|
+
머문다. 중간에 Ctrl-C 로 끊었으면 `down` 을 실행한다(스크립트가 그 명령을 출력한다).
|
|
214
|
+
|
|
215
|
+
**3. 등록 토큰을 컨테이너 환경 설정에 넣지 마라.** `-e` 든 `--env-file` 이든 Docker 데몬에는 같은
|
|
216
|
+
`Config.Env` 로 가서 `docker inspect` 에 평문으로 남는다 — `--env-file` 은 명령줄·셸 기록만 피한다.
|
|
217
|
+
스크립트는 토큰을 600 권한 파일에 쓰고 **읽기 전용 마운트**로 넘긴 뒤, 엔트리포인트 앞에서 그 파일을
|
|
218
|
+
읽어 환경변수로 바꾸고, 러너가 등록되면 파일을 지운다(실측 2026-10-30: `docker inspect` 의 env 에
|
|
219
|
+
`RUNNER_TOKEN` 없음). 컨테이너 안에서 root 로 도는 잡 코드는 여전히 프로세스 환경에서 토큰을 읽을 수
|
|
220
|
+
있다 — 그래서 ephemeral 과 짧은 수명이 함께 필요하다. 러너가 등록되면 파일을 **비운 뒤** 지운다 — 리눅스 Docker 엔진의 파일 bind mount 는 inode 를 쥐고
|
|
221
|
+
있어서, 지우기만 하면 컨테이너 안에서는 그대로 읽힌다(OrbStack 은 지우는 것만으로 안에서도
|
|
222
|
+
사라졌다 — 2026-10-30 대조 실측). 토큰은 1시간 동안 유효하고 그 안에 다른 러너를 등록하는 데
|
|
223
|
+
쓰일 수 있다고 보고 다룬다. 그래서 `up` 은 시작할 때 다른 러너가 그 라벨을 달고 있지 않음을 확인하고
|
|
224
|
+
이 머신에 "이 레포에서 이 라벨을 쓴다"는 기록을 남긴다(`${XDG_STATE_HOME:-~/.local/state}/self-hosted-github-runner/`,
|
|
225
|
+
프로젝트 폴더 밖). `down` 은 우리 이름의 러너를 늘 등록 해제하고, **그 기록이 있을 때만** 같은 라벨을 단
|
|
226
|
+
다른 이름의 러너까지 등록 해제하고 `CI_RUNNER_LABEL` 을 지운 뒤 기록을 지운다. 기록이 없으면 그런 러너와
|
|
227
|
+
변수는 알리기만 하고 남긴다 — 그 라벨이 설치자의 상시 러너 것일 수 있어서다. 그래서 `up` 이 남의 러너
|
|
228
|
+
때문에 거부하면 `down` 이 아니라 **다른 `LABEL`** 로 다시 띄운다(이 머신의 앞선 `up` 이 남긴 러너일 때만
|
|
229
|
+
`up` 이 `down` 을 권한다).
|
|
201
230
|
|
|
202
231
|
### `services:` 를 쓸 때만 docker.sock 을 붙인다 — 기본은 끈다
|
|
203
232
|
|
|
@@ -206,7 +235,7 @@ gh variable set CI_RUNNER_LABEL --body '<고유 라벨>' --repo <owner>/<repo>
|
|
|
206
235
|
|
|
207
236
|
**이건 사실상 호스트 장악 권한이다** — 그 소켓에 닿는 코드는 호스트 파일시스템을 마운트한 root
|
|
208
237
|
컨테이너를 띄울 수 있다. 필요 없는 잡까지 이 권한 아래 돌리지 마라. 워크플로에 `services:` 가
|
|
209
|
-
없으면 **빼라.**
|
|
238
|
+
없으면 **빼라.** 스크립트는 `--docker` 를 줄 때만 붙인다.
|
|
210
239
|
|
|
211
240
|
**소켓만 주면 반쯤만 동작한다 — `--network host` 가 같이 필요하다.** 러너가 컨테이너 안이면
|
|
212
241
|
서비스 컨테이너는 **호스트 포트**에 게시되는데, 워크플로는 `localhost:5432` 를 본다. GitHub
|
|
@@ -235,6 +264,8 @@ docker rm -f probe
|
|
|
235
264
|
의존성에 대한 것이 아니다.
|
|
236
265
|
|
|
237
266
|
public 레포면 **하지 마라.** fork PR 이 임의 코드를 실행한다 — GitHub 이 명시적으로 말린다.
|
|
267
|
+
internal 레포와, fork PR 워크플로(`Settings → Actions → Fork pull request workflows`)를 켠 private
|
|
268
|
+
레포도 같다. 스크립트는 `private` 이고 그 설정이 꺼져 있을 때만 띄운다.
|
|
238
269
|
|
|
239
270
|
private 레포라면 착수 전에 실측해서 알린다:
|
|
240
271
|
|
|
@@ -260,6 +291,10 @@ gh workflow run <wf>.yml --ref <branch>
|
|
|
260
291
|
# 잡이 실제로 시작하는지 본다 — queued 에서 안 움직이면 라벨이 안 맞는 것이다
|
|
261
292
|
```
|
|
262
293
|
|
|
294
|
+
**이미 실패한 PR 실행은 새 커밋 없이 `gh run rerun <run-id>` 로 옮긴다.** 다시 실행할 때 `vars` 를
|
|
295
|
+
새로 읽으므로, 변수를 설정한 뒤 재실행하면 같은 PR 실행이 self-hosted 에 배정되고 PR 체크도 그
|
|
296
|
+
결과로 갱신된다(2026-10-30 실측).
|
|
297
|
+
|
|
263
298
|
**결제 실패 계정에서도 self-hosted 러너에는 잡이 배정된다** — 2026-08-20 실측. 같은 레포에서
|
|
264
299
|
호스티드 잡은 `"The job was not started because recent account payments have failed…"` 로 2~4초 만에
|
|
265
300
|
스텝 0개로 죽었는데, self-hosted 로 라벨을 옮기니 같은 워크플로가 정상적으로 스텝을 밟았다.
|
|
@@ -278,12 +313,10 @@ gh workflow run <wf>.yml --ref <branch>
|
|
|
278
313
|
|
|
279
314
|
임시 조치는 **끝내는 방법이 있을 때만 임시**다. 없으면 그냥 새 영구 상태다.
|
|
280
315
|
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
docker rm -f ci-runner
|
|
286
|
-
```
|
|
316
|
+
`bash <이 스킬 폴더>/scripts/runner.sh down` 이 세 가지를 한다 — 변수 삭제(우리 라벨이고 이 머신의 `up`
|
|
317
|
+
기록이 있을 때만 · 호스티드로 복귀) · 러너 등록 해제(우리 이름 + `up` 이후 우리 라벨로 붙은 것 — Step 3
|
|
318
|
+
안전한 기본값 3) · 컨테이너 제거. 기록이 있으면 끝에 변수를 다시 읽어 아직 우리 라벨일 때 실패로
|
|
319
|
+
끝난다. 마치면 `status` 로 셋 다 비었는지 확인한다.
|
|
287
320
|
|
|
288
321
|
**등록 해제를 빼먹지 마라.** 컨테이너만 지우면 GitHub 에는 offline 러너가 남고, 그 라벨로 오는
|
|
289
322
|
잡은 영영 큐에 머문다.
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Temporary ephemeral self-hosted runner for the current GitHub repository, in a Linux container.
|
|
3
|
+
#
|
|
4
|
+
# Usage (from the repository root):
|
|
5
|
+
# bash <skill>/scripts/runner.sh up [--jobs N] [--docker] # serve N jobs, then set CI_RUNNER_LABEL
|
|
6
|
+
# bash <skill>/scripts/runner.sh down # restore hosted runners
|
|
7
|
+
# bash <skill>/scripts/runner.sh status # variable, registered runners, container
|
|
8
|
+
#
|
|
9
|
+
# Environment (all optional):
|
|
10
|
+
# REPO owner/name default: gh repo view
|
|
11
|
+
# LABEL runs-on label default: <name>-local (never a GitHub default label)
|
|
12
|
+
# PLATFORM linux/arm64|linux/amd64 default: the host hardware (Apple Silicon → arm64, even under Rosetta)
|
|
13
|
+
# IMAGE runner image default: myoung34/github-runner:ubuntu-noble (= ubuntu-latest's 24.04)
|
|
14
|
+
#
|
|
15
|
+
# --jobs N ephemeral runners serve one job each: N = the jobs this event will actually run
|
|
16
|
+
# (matrix legs count, jobs skipped by `if:` do not). Interrupted? run `down`.
|
|
17
|
+
# --docker mount the host Docker socket and use host networking — only for `services:` /
|
|
18
|
+
# Docker-based jobs. It gives jobs host-level control; leave it off otherwise.
|
|
19
|
+
# The registration token goes in through a 600 file mounted read-only, never through the
|
|
20
|
+
# container's environment config, so `docker inspect` does not show it.
|
|
21
|
+
# `up` refuses a LABEL another runner of this repository already carries, then claims the label
|
|
22
|
+
# on this machine (${XDG_STATE_HOME:-~/.local/state}/self-hosted-github-runner/). Only under that
|
|
23
|
+
# claim does `down` delete CI_RUNNER_LABEL or unregister other runners carrying the label; without
|
|
24
|
+
# it, it names them and leaves them.
|
|
25
|
+
# Exit codes: 2 usage · 3 refused or GitHub state unknown · 4 runner failed to start.
|
|
26
|
+
set -euo pipefail
|
|
27
|
+
|
|
28
|
+
SELF=$0
|
|
29
|
+
die() { echo "runner.sh: $1" >&2; exit "${2:-3}"; }
|
|
30
|
+
lower() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]'; }
|
|
31
|
+
for bin in gh docker; do command -v "$bin" >/dev/null || die "$bin not found"; done
|
|
32
|
+
|
|
33
|
+
REPO=${REPO:-$(gh repo view --json nameWithOwner --jq .nameWithOwner)}
|
|
34
|
+
[ -n "$REPO" ] || die "cannot resolve the repository; set REPO=owner/name"
|
|
35
|
+
LABEL=${LABEL:-${REPO#*/}-local}
|
|
36
|
+
NAME="${REPO%/*}-${REPO#*/}-runner"
|
|
37
|
+
IMAGE=${IMAGE:-myoung34/github-runner:ubuntu-noble}
|
|
38
|
+
CLAIM="${XDG_STATE_HOME:-$HOME/.local/state}/self-hosted-github-runner/${REPO%/*}@${REPO#*/}"
|
|
39
|
+
if [ -z "${PLATFORM:-}" ]; then
|
|
40
|
+
arch=$(uname -m)
|
|
41
|
+
# A Rosetta shell on Apple Silicon reports x86_64; ask the hardware instead.
|
|
42
|
+
[ "$(uname -s)" = Darwin ] && [ "$(sysctl -n hw.optional.arm64 2>/dev/null || echo 0)" = 1 ] && arch=arm64
|
|
43
|
+
case "$arch" in
|
|
44
|
+
arm64|aarch64) PLATFORM=linux/arm64 ;;
|
|
45
|
+
x86_64|amd64) PLATFORM=linux/amd64 ;;
|
|
46
|
+
*) die "unknown host architecture $arch; set PLATFORM" ;;
|
|
47
|
+
esac
|
|
48
|
+
fi
|
|
49
|
+
case "$LABEL" in ''|*[!A-Za-z0-9._-]*) die "LABEL may contain only letters, digits, '.', '_' and '-'" 2 ;; esac
|
|
50
|
+
case "$(lower "$LABEL")" in
|
|
51
|
+
self-hosted|linux|macos|windows|x64|arm64|arm)
|
|
52
|
+
die "LABEL=$LABEL is a default label that any self-hosted runner matches" ;;
|
|
53
|
+
esac
|
|
54
|
+
|
|
55
|
+
# Prints the current CI_RUNNER_LABEL. Returns 1 only when GitHub says it does not exist;
|
|
56
|
+
# any other failure (auth, network, rate limit) stops the script rather than reading as unset.
|
|
57
|
+
label_var() {
|
|
58
|
+
local out
|
|
59
|
+
if out=$(gh api "/repos/$REPO/actions/variables/CI_RUNNER_LABEL" --jq .value 2>&1); then
|
|
60
|
+
printf '%s' "$out"; return 0
|
|
61
|
+
fi
|
|
62
|
+
case "$out" in *"HTTP 404"*) return 1 ;; esac
|
|
63
|
+
die "cannot read CI_RUNNER_LABEL: $out"
|
|
64
|
+
}
|
|
65
|
+
read_label() { # sets CURRENT; exits on an unknown state
|
|
66
|
+
local rc=0
|
|
67
|
+
CURRENT=$(label_var) || rc=$?
|
|
68
|
+
[ "$rc" -le 1 ] || exit "$rc"
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
# Prints "<id> <name>" of the runners named $NAME or carrying $LABEL (case-insensitive, as GitHub matches).
|
|
72
|
+
label_runners() {
|
|
73
|
+
gh api --paginate "/repos/$REPO/actions/runners" \
|
|
74
|
+
--jq ".runners[]|select(.name==\"$NAME\" or any(.labels[]; (.name|ascii_downcase)==\"$(lower "$LABEL")\"))|\"\(.id) \(.name)\""
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
# True when an earlier `up` on this machine claimed $LABEL for $REPO.
|
|
78
|
+
claimed() { [ "$(cat "$CLAIM" 2>/dev/null || true)" = "$(lower "$LABEL")" ]; }
|
|
79
|
+
|
|
80
|
+
TOKENFILE=""
|
|
81
|
+
VAR_SET=0
|
|
82
|
+
cleanup() {
|
|
83
|
+
local rc=$?
|
|
84
|
+
[ -z "$TOKENFILE" ] || { : > "$TOKENFILE"; rm -f "$TOKENFILE"; }
|
|
85
|
+
if [ "$rc" -ne 0 ] && [ "$VAR_SET" = 1 ]; then
|
|
86
|
+
echo "runner.sh: stopped with CI_RUNNER_LABEL=$LABEL still set; restore with: bash $SELF down" >&2
|
|
87
|
+
fi
|
|
88
|
+
}
|
|
89
|
+
trap cleanup EXIT
|
|
90
|
+
trap 'exit 130' INT TERM
|
|
91
|
+
|
|
92
|
+
launch() {
|
|
93
|
+
local -a extra=()
|
|
94
|
+
# Under $HOME, not $TMPDIR: engines like Colima share only the home directory with the VM.
|
|
95
|
+
TOKENFILE=$(mktemp "$HOME/.runner-token.XXXXXX"); chmod 600 "$TOKENFILE"
|
|
96
|
+
gh api -X POST "/repos/$REPO/actions/runners/registration-token" --jq .token > "$TOKENFILE"
|
|
97
|
+
[ "$DOCKER" = 1 ] && extra=(-v /var/run/docker.sock:/var/run/docker.sock --network host)
|
|
98
|
+
docker rm -f "$NAME" >/dev/null 2>&1 || true
|
|
99
|
+
docker run -d --name "$NAME" --platform "$PLATFORM" \
|
|
100
|
+
-e "REPO_URL=https://github.com/$REPO" -e "RUNNER_NAME=$NAME" -e "LABELS=$LABEL" \
|
|
101
|
+
-e RUNNER_WORKDIR=/tmp/runner/work -e EPHEMERAL=true \
|
|
102
|
+
-v "$TOKENFILE:/run/runner-token:ro" ${extra[@]+"${extra[@]}"} \
|
|
103
|
+
--entrypoint bash "$IMAGE" \
|
|
104
|
+
-c 'RUNNER_TOKEN=$(cat /run/runner-token); export RUNNER_TOKEN; exec /entrypoint.sh ./bin/Runner.Listener run --startuptype service' \
|
|
105
|
+
>/dev/null
|
|
106
|
+
for _ in $(seq 1 40); do
|
|
107
|
+
if docker logs "$NAME" 2>&1 | grep -q "Listening for Jobs"; then
|
|
108
|
+
# Empty it before unlinking: the container keeps the mounted inode, and job code runs as root.
|
|
109
|
+
: > "$TOKENFILE"; rm -f "$TOKENFILE"; TOKENFILE=""
|
|
110
|
+
return 0
|
|
111
|
+
fi
|
|
112
|
+
[ "$(docker inspect -f '{{.State.Running}}' "$NAME" 2>/dev/null)" = true ] || break
|
|
113
|
+
sleep 3
|
|
114
|
+
done
|
|
115
|
+
docker logs "$NAME" 2>&1 | tail -5 >&2
|
|
116
|
+
die "runner did not start listening" 4
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
cmd=${1:-}; shift || true
|
|
120
|
+
case "$cmd" in
|
|
121
|
+
up)
|
|
122
|
+
JOBS=1; DOCKER=0
|
|
123
|
+
while [ $# -gt 0 ]; do
|
|
124
|
+
case "$1" in
|
|
125
|
+
--jobs) [ $# -ge 2 ] || die "--jobs needs a number" 2; JOBS=$2; shift 2 ;;
|
|
126
|
+
--docker) DOCKER=1; shift ;;
|
|
127
|
+
*) die "unknown option $1" 2 ;;
|
|
128
|
+
esac
|
|
129
|
+
done
|
|
130
|
+
case "$JOBS" in ''|*[!0-9]*|0*) die "--jobs must be a positive integer" 2 ;; esac
|
|
131
|
+
visibility=$(gh api "/repos/$REPO" --jq .visibility) || die "cannot read $REPO visibility"
|
|
132
|
+
# Only private repositories, and only when fork PRs cannot start workflows: a fork PR's
|
|
133
|
+
# code would otherwise run on this machine. Anything unreadable counts as a refusal.
|
|
134
|
+
[ "$visibility" = private ] || die "$REPO visibility is '${visibility:-unknown}', not private"
|
|
135
|
+
fork_prs=$(gh api "/repos/$REPO/actions/permissions/fork-pr-workflows-private-repos" \
|
|
136
|
+
--jq .run_workflows_from_fork_pull_requests) || die "cannot read $REPO fork PR workflow setting"
|
|
137
|
+
case "$fork_prs" in
|
|
138
|
+
false) ;;
|
|
139
|
+
true) die "$REPO runs workflows from fork pull requests; disable that first" ;;
|
|
140
|
+
*) die "cannot confirm $REPO blocks fork pull request workflows (setting is '${fork_prs:-empty}')" ;;
|
|
141
|
+
esac
|
|
142
|
+
read_label
|
|
143
|
+
[ -z "$CURRENT" ] || [ "$CURRENT" = "$LABEL" ] || die "CI_RUNNER_LABEL is already '$CURRENT'; not overwriting"
|
|
144
|
+
# A runner we did not start already answers to this label: `down` must never be able to
|
|
145
|
+
# mistake it for one of ours, so refuse here instead.
|
|
146
|
+
held=$(label_runners) || die "cannot read $REPO runners"
|
|
147
|
+
others=$(while read -r _ rname; do [ -z "$rname" ] || [ "$rname" = "$NAME" ] || printf ' %s' "$rname"; done <<< "$held")
|
|
148
|
+
if [ -n "$others" ]; then
|
|
149
|
+
if claimed; then die "runner(s)$others carry label '$LABEL' since an earlier up on this machine; run down first"; fi
|
|
150
|
+
die "runner(s)$others already carry label '$LABEL'; choose another LABEL"
|
|
151
|
+
fi
|
|
152
|
+
mkdir -p "${CLAIM%/*}"
|
|
153
|
+
lower "$LABEL" > "$CLAIM"
|
|
154
|
+
echo "repo=$REPO label=$LABEL platform=$PLATFORM docker=$DOCKER jobs=$JOBS"
|
|
155
|
+
for i in $(seq 1 "$JOBS"); do
|
|
156
|
+
launch
|
|
157
|
+
echo "runner $i/$JOBS listening"
|
|
158
|
+
if [ "$VAR_SET" = 0 ]; then
|
|
159
|
+
# Route jobs here only once a runner is listening, so a failed start leaves CI as it was.
|
|
160
|
+
[ "$CURRENT" = "$LABEL" ] || gh variable set CI_RUNNER_LABEL --body "$LABEL" --repo "$REPO"
|
|
161
|
+
VAR_SET=1
|
|
162
|
+
fi
|
|
163
|
+
docker wait "$NAME" >/dev/null
|
|
164
|
+
docker logs "$NAME" 2>&1 | grep -E "Running job|completed with result" || true
|
|
165
|
+
docker rm -f "$NAME" >/dev/null 2>&1 || true
|
|
166
|
+
done
|
|
167
|
+
echo "served $JOBS job(s); restore hosted runners with: bash $SELF down"
|
|
168
|
+
;;
|
|
169
|
+
down)
|
|
170
|
+
# Without this machine's claim the label may be the installer's own: change only what is ours by name.
|
|
171
|
+
ours=0
|
|
172
|
+
if claimed; then ours=1; fi
|
|
173
|
+
read_label
|
|
174
|
+
if [ "$CURRENT" = "$LABEL" ] && [ "$ours" = 1 ]; then
|
|
175
|
+
gh api -X DELETE "/repos/$REPO/actions/variables/CI_RUNNER_LABEL" >/dev/null
|
|
176
|
+
elif [ "$CURRENT" = "$LABEL" ]; then
|
|
177
|
+
echo "CI_RUNNER_LABEL is '$CURRENT' but no up on this machine claimed it; left as is" >&2
|
|
178
|
+
elif [ -n "$CURRENT" ]; then
|
|
179
|
+
echo "CI_RUNNER_LABEL is '$CURRENT', not '$LABEL'; left as is" >&2
|
|
180
|
+
fi
|
|
181
|
+
# Ours by name, always. Others carrying our label only under the claim: `up` refused the label
|
|
182
|
+
# while another runner held it, so they appeared afterwards (e.g. job code with the token).
|
|
183
|
+
ids=$(label_runners)
|
|
184
|
+
left=""
|
|
185
|
+
while read -r id rname; do
|
|
186
|
+
[ -n "$id" ] || continue
|
|
187
|
+
if [ "$rname" != "$NAME" ] && [ "$ours" = 0 ]; then left="$left $rname ($id)"; continue; fi
|
|
188
|
+
gh api -X DELETE "/repos/$REPO/actions/runners/$id"
|
|
189
|
+
echo "unregistered runner $rname ($id)"
|
|
190
|
+
done <<< "$ids"
|
|
191
|
+
[ -z "$left" ] || echo "runner.sh: left runner(s)$left carrying label '$LABEL': no up on this machine claimed it" >&2
|
|
192
|
+
[ "$ours" = 0 ] || rm -f "$CLAIM"
|
|
193
|
+
docker rm -f "$NAME" >/dev/null 2>&1 || true
|
|
194
|
+
read_label
|
|
195
|
+
[ "$ours" = 0 ] || [ "$CURRENT" != "$LABEL" ] || die "CI_RUNNER_LABEL is still '$LABEL'"
|
|
196
|
+
echo "restored: $NAME unregistered and removed; CI_RUNNER_LABEL is ${CURRENT:-unset}"
|
|
197
|
+
;;
|
|
198
|
+
status)
|
|
199
|
+
read_label
|
|
200
|
+
echo "CI_RUNNER_LABEL=${CURRENT:-<unset>}"
|
|
201
|
+
gh api "/repos/$REPO/actions/runners" --jq '.runners[] | "\(.name) \(.status) " + ([.labels[].name]|join(","))'
|
|
202
|
+
docker ps -a --filter "name=^${NAME}$" --format '{{.Names}} {{.Status}}'
|
|
203
|
+
;;
|
|
204
|
+
*) sed -n '2,25p' "$0" >&2; exit 2 ;;
|
|
205
|
+
esac
|