DEV Community

Cover image for Claude Code가 osFoundry에서 GitNest 체크 재실행을 제안할 때 커밋까지 박아 보내는 이유
BBT for BBT 한국어

Posted on

Claude Code가 osFoundry에서 GitNest 체크 재실행을 제안할 때 커밋까지 박아 보내는 이유

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"]}]
}
Enter fullscreen mode Exit fullscreen mode

읽는 쪽 짝은 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). 판정 순서가 곧 규칙이다.

  1. 체크가 0개면 none. passed가 아니다
  2. failure, timed_out, cancelled가 하나라도 있으면 failed
  3. success가 아닌 게 남아 있으면 running. 클라이언트가 모르는 상태값도 여기 들어간다
  4. 그다음에야 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
Enter fullscreen mode Exit fullscreen mode

"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
Enter fullscreen mode Exit fullscreen mode

가드가 없으면 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
Enter fullscreen mode Exit fullscreen mode

세 시간에 한 번 움직이는 체인지셋이라도 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
Enter fullscreen mode Exit fullscreen mode

이 중 두 개는 입력 검사가 아니라 설계다. 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
Enter fullscreen mode Exit fullscreen mode

응답을 놓쳐서 재전송해도 같은 키라 카드가 안 늘어난다. 재컴포즈하면 키가 바뀌니까 새 커밋에 대한 제안은 새 카드가 된다. 그게 맞다.

도구 무게랑 서버까지 거리

== 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)