Claude Code가 GitNest에서 떨어진 체크를 다시 돌리고 싶을 때 부르는 도구는 이거다. osFoundry MCP 엔드포인트의 tools/list는 토큰 없이 날릴 수 있어서, 실서버 스키마를 그대로 가져왔다.
{
"name": "propose_gitnest_check_rerun",
"description": "Ask the repository owner to retry one finished check on a specific composed change-set version. Approval rechecks repository access, version, commit and check state.",
"inputSchema": {
"type": "object",
"properties": {
"repository_id": {"type": "string"},
"change_set_id": {"type": "string"},
"check_name": {"type": "string", "maxLength": 200},
"expected_change_set_version": {"type": "integer", "minimum": 1},
"expected_composition_oid": {"type": "string"},
"idempotency_key": {"type": "string", "minLength": 8, "maxLength": 128}
},
"required": ["repository_id", "change_set_id", "check_name",
"expected_change_set_version", "expected_composition_oid", "idempotency_key"],
"additionalProperties": false
},
"annotations": {"readOnlyHint": false, "openWorldHint": false, "destructiveHint": true},
"securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]
}
읽는 쪽 짝은 list_gitnest_checks {repository_id, change_set_id}다. 체인지셋의 현재 컴포즈된 커밋에 대해 상한이 걸린 체크 상태를 돌려준다. 판단 재료로 list_gitnest_saved_results(limit 1~50)와 read_gitnest_work(kind는 tasks / changes / runs)도 쓴다. 셋 다 osfoundry:read, readOnlyHint: true다.
체크 하나 다시 돌리는데 필수 필드가 6개다. CI 버튼이면 잡 ID 하나면 끝난다. 늘어난 두 개, 버전과 커밋이 이 글의 주제다. 이 Mac엔 claude 바이너리가 없어서 클라이언트 역할은 checks_sim.py로 대신했다. 코드랑 전체 출력은 code/에 있다.
에이전트한테 "그린"이 뭔데
제안하기 전에 일단 체크 목록을 제대로 읽어야 한다. osFoundry의 GitNest UI는 커밋의 체크 결과를 작은 순수 함수 하나로 요약한다(check-runs.ts의 summarise). 판정 순서가 곧 규칙이다.
- 체크가 0개면
none.passed가 아니다 -
failure,timed_out,cancelled가 하나라도 있으면failed -
success가 아닌 게 남아 있으면running. 클라이언트가 모르는 상태값도 여기 들어간다 - 그다음에야
passed
이 규칙을 파이썬으로 옮기고, 모델이 알아서 짤 법한 지름길 두 개랑 비교했다.
== verdict ==
case summarise no-failure ratio
no checks none green green
all passed passed 2 green green
one queued running 1/2 green red
one failed failed: e2e red red
one timed out failed: e2e green red
one cancelled failed: e2e green red
unknown status running 1/2 green red
shortcut wrong: no-failure 5/7, ratio 1/7
"failure 없으면 그린"은 7개 중 5개를 틀린다. 아무도 안 본 커밋, 큐에 있는 체크, 타임아웃을 전부 그린이라고 한다. 비율(passed == total)은 그나마 낫지만 체크 0개면 0 == 0이라 역시 그린이 된다. GitNest 코드 주석이 제일 오해를 부른다고 적어 둔 케이스가 바로 이거다. 체크 없는 커밋은 검증된 게 아니라 아무도 안 들여다본 거다. UI는 체크 표시 없이 "No checks have run against this commit"으로 보여 준다.
Claude Code한테 "그린이야?"를 답하게 할 거면 이 네 줄을 CLAUDE.md에 넣어 두자. 도구가 돌려주는 건 상태값이지 판정이 아니다.
재실행에 왜 버전이랑 커밋이 필요한가
승인하는 사람은 특정 커밋을 보고 있고, 버튼 누르기 전에 체인지셋이 움직일 수 있어서다.
GitNest 체인지셋은 저장된 결과들을 커밋 하나로 컴포즈한 거다. 저장 결과가 늘거나 베이스가 움직여서 다시 컴포즈하면 버전도 컴포즈된 커밋도 새로 바뀌고, 체크도 처음부터 다시다. 재실행 제안은 사람을 기다린다. 제안이 "cs_4e81a0의 e2e 다시 돌려"뿐이라면, 승인 시점의 체인지셋에서 e2e가 돈다. 오너가 한 번도 안 본 커밋일 수도 있다.
checks_sim.py로 이 대기 시간을 모델링했다. 시행 1번이 제안 1건이다. 에이전트는 버전 3, 커밋 A, e2e 실패를 읽고 제안한다. 오너 리뷰 시간은 중앙값 8분 로그정규분포인데, 이건 가정이지 측정이 아니다. 기다리는 동안 체인지셋은 평균 45분에 한 번 포아송 과정으로 다시 컴포즈되고, 그 뒤 체크가 끝나기까지 4분 걸린다. 시행의 10%에선 다른 Claude Code 세션이 같은 실패를 읽고 자기 키로 제안을 냈고, 오너는 둘 다 승인한다. 승인 시점 가드 세 가지를 각각 10,000번 돌렸다.
== approval-time guards (n=10000, review median 8 min, recompose mean every 45 min, 10% second session) ==
guard ran on reviewed commit ran on unreviewed commit duplicate run refused (stale) refused (not finished)
none 7789 1411 1764 0 0
version+oid 7789 0 740 2435 0
full 7789 0 0 2435 740
가드가 없으면 1,411건이 오너가 안 본 커밋에서 체크를 다시 돌렸고, 1,764건은 이미 큐에 있거나 돌고 있는 체크를 또 쌓았다. 승인할 때 버전과 커밋을 비교하면 안 본 커밋에서 도는 건 0이 되고, 대신 낡은 카드 2,435건이 거절된다. 남은 중복 740건은 두 번째 세션 몫이다. 버전도 커밋도 같은데 첫 승인으로 이미 재큐잉된 상태다. 이걸 막는 게 세 번째 가드 "이 체크가 아직 끝난 상태인가"다. 도구 설명에 있는 "Approval rechecks repository access, version, commit and check state."가 딱 이 풀세트다.
제일 자신 없는 입력은 재컴포즈 빈도라서, 가드 없는 줄만 세 가지로 돌려 봤다.
== sensitivity: unreviewed-commit runs with guard 'none' ==
recompose every 15 min unreviewed 2449 duplicates 3128
recompose every 45 min unreviewed 1411 duplicates 1764
recompose every 180 min unreviewed 452 duplicates 1208
세 시간에 한 번 움직이는 체인지셋이라도 10,000건당 452건이 엉뚱한 커밋에서 돈다. 정상 경로에서 가드 비용은 0이다. 세 줄 다 본 커밋에서 돈 건 7,789건 그대로다.
버전, 커밋 둘 다 필요해?
이 모델에선 둘이 항상 같이 움직여서 하나만 써도 숫자는 같다. 그래도 답하는 질문이 다르다. 버전은 체인지셋 자체의 카운터고 내용이 바뀌면 올라간다. 커밋은 체크가 실제로 돈 대상이고, 카드에 "Reviewed commit: …"로 찍힌다. 클라이언트한테 둘 다 보내게 하면 서버는 어느 쪽으로든 거절할 수 있고, 오너는 내부 카운터가 아니라 커밋 해시를 카드에서 읽는다. 버전은 스키마가 1 이상 정수로 묶는다. 커밋은 그냥 문자열이라 대조는 서버 몫이다.
호출 전에 스키마로 걸러지는 것
실서버 inputSchema를 jsonschema에 그대로 먹여서 인자를 검증했다.
== propose_gitnest_check_rerun arguments ==
ok PASS
no oid REJECT 'expected_composition_oid' is a required property
version 0 REJECT 0 is less than the minimum of 1
version as string REJECT '3' is not of type 'integer'
two checks REJECT ['e2e', 'lint'] is not of type 'string'
check 201 chars REJECT 'ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc
key 7 chars REJECT 'abcdefg' is too short
extra 'force' REJECT Additional properties are not allowed ('force' was unexpected)
required: repository_id, change_set_id, check_name, expected_change_set_version, expected_composition_oid, idempotency_key
이 중 두 개는 입력 검사가 아니라 설계다. check_name이 리스트가 아니라 문자열이라서 "전부 다시"는 체크마다 카드 한 장이 되고, 오너가 하나씩 정한다. 그리고 additionalProperties: false 덕분에 모델이 "force": true를 슬쩍 붙여도 조용히 무시되지 않고 에러가 난다.
멱등 키는 시도가 아니라 제안 대상에서 만든다. 스크립트에선 "rerun-" + sha256(change_set_id, version, oid, check_name)[:32]로 했다.
key retry same: True key after recompose same: False len 38
응답을 놓쳐서 재전송해도 같은 키라 카드가 안 늘어난다. 재컴포즈하면 키가 바뀌니까 새 커밋에 대한 제안은 새 카드가 된다. 그게 맞다.
도구 무게랑 서버까지 거리
== tools/list ==
59 tools, 48140 B via json.dumps, 12722 tok (cl100k)
list_gitnest_checks 612 B 158 tok readOnly=True destructive=False scope=osfoundry:read
list_gitnest_saved_results 707 B 182 tok readOnly=True destructive=False scope=osfoundry:read
read_gitnest_work 685 B 189 tok readOnly=True destructive=False scope=osfoundry:read
propose_gitnest_check_rerun 1011 B 268 tok readOnly=False destructive=True scope=osfoundry:write
all 13 gitnest tools 11227 B 3009 tok
GitNest 도구 13개가 카탈로그 전체 토큰의 약 4분의 1이다(tiktoken cl100k_base로 센 거라 대략치). 일본에 있는 이 Mac에서 실서버로 토큰 없이 각 10번씩 날린 결과:
$ python3 probe.py
initialize HTTP 200 308 B median 566 ms min 326 max 807
capabilities: {"tools": {"listChanged": false}}
tools/list HTTP 200 45368 B median 722 ms min 420 max 1406
tools/call list_gitnest_checks HTTP 401 337 B median 552 ms min 409 max 903
401엔 error_description="Connect osFoundry to continue"와 resource_metadata URL이 붙어 있고, 이걸로 Claude Code가 OAuth 흐름에 들어간다. initialize는 푸시를 선언하지 않으니까, 재실행이 승인됐다거나 체크가 끝났다는 걸 클라이언트에 알려 줄 방법이 없다. 체크를 기다린다는 건 내 머신에서 러너가 도는 시간에 사람이 버튼 누르는 시간까지 더한 거라 밀리초가 아니라 분 단위다. 싸게 가려면 제안하고 턴을 끝낸 다음, 사용자가 승인했다고 할 때 list_gitnest_checks를 한 번만 부르면 된다.
체크는 실제로 누가 돌리나
osFoundry가 아니다. GitNest 러너 패널엔 체크가 "run on your machine, not ours"라고 적혀 있다. 등록한 러너가 자기 토큰으로 폴링하고(OSF_RUNNER_TOKEN=… osfoundry-runner --api https://api.osfoundry.io), 러너가 없으면 체크는 큐에 쌓인 채로 있다. 재실행 승인은 체크를 다시 큐에 넣을 뿐이다. Claude Code는 러너 토큰을 안 갖고 있고, 읽기 도구도 로컬 바인딩과 자격 증명은 빼고 준다. 에이전트는 e2e가 떨어진 건 볼 수 있지만, 사람과 러너 없이 뭔가를 실행시킬 수는 없다.
직접 붙인다면
- 판정 규칙은 UI뿐 아니라 클라이언트 지시에도 넣는다. 에이전트가 그린이라고 말하기 시작하는 건 "체크 없음"과 "모르는 상태값"에서다
- 재실행엔 리뷰한 시점의 커밋을 박게 한다. 대조는 제안할 때가 아니라 승인할 때 한다
- 승인할 때 체크 자체의 상태도 다시 본다. 같은 실패에 대한 제안 두 건은 버전과 커밋으론 안 막힌다
- 제안 하나에 체크 하나. 리스트를 허용하면 플레이키 테스트 재시도가 아무도 고르지 않은 전체 재실행이 된다
- 멱등 키는 (체인지셋, 버전, 커밋, 체크)로 만든다. 재전송은 합쳐지고 재컴포즈는 안 합쳐진다
- 실행은 플랫폼에도 에이전트에도 안 준다. 토큰은 러너가, 버튼은 사람이 쥔다
체크 패널이 있는 체인지셋 리뷰 화면은 GitNest 페이지에 있다. 프로토콜 전반은 MCP 용어 설명을 참고.
Top comments (0)