DEV Community

Cover image for Codex CLI가 osFoundry로 GitHub PR을 열 때 브랜치 하나만 push되는 구조
BBT for BBT 한국어

Posted on

Codex CLI가 osFoundry로 GitHub PR을 열 때 브랜치 하나만 push되는 구조

Codex CLI가 체인지셋을 GitHub나 GitLab에 올리고 싶을 때 부르는 툴이다. osFoundry MCP 서버는 로그인을 안 한 클라이언트한테도 이렇게 보여 준다.

{"name": "propose_gitnest_provider_publication",
 "description": "Ask the repository owner to review a composed GitNest change set, push only its dedicated branch using their linked Git provider account, and open a draft pull request. Approval rechecks permissions, risk policy, required checks, and target commit.",
 "inputSchema": {"properties": {
     "repository_id": {"type": "string"},
     "change_set_id": {"type": "string"},
     "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", "expected_change_set_version",
                "expected_composition_oid", "idempotency_key"],
   "additionalProperties": false},
 "annotations": {"readOnlyHint": false, "openWorldHint": true, "destructiveHint": true},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}
Enter fullscreen mode Exit fullscreen mode

눈여겨볼 건 없는 쪽이다. 브랜치 이름도, 제목도, 머지 대상 브랜치도, draft 플래그도, 토큰도 없다. 클라이언트가 넘기는 건 체인지셋 하나랑 그걸 읽었을 때 본 사실 두 개뿐이고, 나머지는 전부 오너가 승인하는 순간 오너 쪽에서 채워진다. 이 글에서 뜯어볼 건 "push only its dedicated branch"라는 약속이다. 보통 그 앞에 먼저 불리는 propose_gitnest_file_import도 같이 보고, 200 KB라는 한도가 실제 파일에서 어느 정도인지도 재 봤다.

이 Mac에는 codex 바이너리가 없어서 클라이언트 쪽은 Python 스크립트로 대신했다(Apple M1, uv로 Python 3.12, git 2.39.5). 네트워크 수치는 일본에서 잰 값이다.

$ uv run --with tiktoken --with jsonschema python3 publish_sim.py
== Part 1: live tools/list (no token) ==
tools/list x5 median 505.7 ms; 59 tools, 13 GitNest
read_gitnest_repository               osfoundry:read  ro=True  openWorld=False destructive=False
propose_gitnest_file_import           osfoundry:write ro=False openWorld=False destructive=True
propose_gitnest_native_publication    osfoundry:write ro=False openWorld=True  destructive=True
propose_gitnest_provider_publication  osfoundry:write ro=False openWorld=True  destructive=True
these four = 989 of 12662 tokens
Enter fullscreen mode Exit fullscreen mode

(위 출력에서 required 목록은 잘랐다. 토큰 수는 cl100k_base 기준이라 Codex 토크나이저랑은 조금 다를 수 있다.) 네 툴을 다 합쳐도 목록 전체 12,662 토큰 중 1,000도 안 된다. Codex 설정의 enabled_tools에 이 넷만 적어 두면 나머지 55개는 프롬프트에 안 들어간다.

왜 공개 툴 둘은 "open world"고 가져오기는 아닐까

openWorldHint는 툴이 닫힌 시스템 밖까지 손을 뻗는지를 클라이언트한테 알려 주는 값이다. 파일 가져오기는 프로젝트 안에서만 보이는 GitNest 저장소에 쓰는 거라 밖으로 안 나간다. 반면 PR은 네이티브든 아니든 다른 사람한테 알림이 가고, 다른 사람이 보고 움직이는 물건이다. Codex는 이런 어노테이션을 보고 언제 멈춰서 물어볼지 정하니까, 서버가 붙인 힌트가 osFoundry 승인 카드보다 먼저 오는 승인 체인의 첫 단계가 된다.

파일 가져오기에는 뭘 실을 수 있을까

거의 다 스키마에 답이 있다. 라이브 inputSchema에 12가지 케이스를 jsonschema(Draft 2020-12)로 돌려 봤다.

file_import            20 files                           ok
file_import            21 files                           REJECT maxItems
file_import            one file 100,000 chars             ok
file_import            one file 100,001 chars             REJECT maxLength
file_import            file with mode '100755'            REJECT additionalProperties
file_import            delete: {'path','delete':true}     REJECT required
file_import            idempotency_key 7 chars            REJECT minLength
native_publication     full pin                           ok
native_publication     no expected_composition_oid        REJECT required
provider_publication   expected_change_set_version 0      REJECT minimum
provider_publication   extra 'draft': false               REJECT additionalProperties
provider_publication   extra 'target_branch'              REJECT additionalProperties
Enter fullscreen mode Exit fullscreen mode

파일 하나는 path랑 content뿐이다. 모드 비트가 없으니 스크립트는 실행 권한 없이 들어간다. 삭제도 안 된다. 삭제하려면 content 없는 엔트리가 필요한데 content가 필수라서다. 엔트리는 하나하나가 파일 전체 텍스트로 추가하거나 덮어쓰는 거고, 오너가 승인 카드에서 읽는 것도 딱 그 전체 텍스트다.

스키마로 표현 못 하는 한도가 하나 있다. 설명문에 적힌 합계 200 KB다. maxLength는 문자 수를 세는데, 이 한도는 UTF-8 바이트로 센다.

JA file: 100,000 chars passes maxLength; UTF-8 = 300,000 bytes
Enter fullscreen mode Exit fullscreen mode

일본어 파일 하나가 파일당 문자 상한에 딱 맞으면, 그것만으로 커밋 전체 한도의 1.5배다. 스키마만 보는 클라이언트는 서버가 거절할 수밖에 없는 호출을 만들게 된다. 바이트는 클라이언트에서 세 두자.

실제로 가져오면 승인 카드가 몇 장 나올까

Part 3에서는 실제 디렉터리를 20파일, 200 KB 안에 들어가게 크기순 first-fit으로 나눠 담고 제안 수를 셌다. 제안 하나가 오너가 열어 봐야 하는 카드 한 장이다.

GitNest web lib (.ts)           25 files   126,756 chars   127,210 bytes (1.00 B/char) | 2 proposals
   per proposal (files, KB): 20/115, 5/12
GitNest web components (.tsx)   22 files   274,206 chars   274,819 bytes (1.00 B/char) | 2 proposals
   per proposal (files, KB): 10/200, 12/75
Team 2 JA articles (.md)        55 files   359,213 chars   662,285 bytes (1.84 B/char) | 4 proposals
   per proposal (files, KB): 13/200, 16/196, 18/194, 8/73
Enter fullscreen mode Exit fullscreen mode

데이터는 osFoundry 프런트엔드 소스랑 이 블로그의 일본어 원고를 디스크에서 그대로 읽은 거다. 작은 소스 파일은 20파일 상한에 먼저 걸리고, 큰 컴포넌트나 라틴 문자가 아닌 텍스트는 바이트 한도에 먼저 걸린다. "KB"를 1,000으로 보든 1,024로 보든 이 세 세트에서는 결과가 똑같았다.

하나 더 볼 건 커밋 수다. 제안이 4개면 브랜치에 커밋이 4개 생기고, 하나씩 따로 승인받고, 그중 어느 것이든 오너가 거절할 수 있다. 파일들이 같이 있어야만 의미가 있다면 커밋 메시지마다 그걸 적어 두거나, 아예 카드 한 장에 들어갈 만큼 작게 가져오는 게 낫다.

"push only its dedicated branch"를 git으로 풀면

osFoundry 서버 쪽 프로바이더 push 코드는 공개돼 있지 않다. 대신 데스크톱 앱이 직접 하는 push, 그러니까 GitNest의 Push Change Set Branch 버튼 뒤에 있는 gitnest_desktop.rs의 gitnest_push_change_set_branch는 볼 수 있다. 퍼블리케이션 프리플라이트가 돌려준 값을 받아서 이 순서로 처리한다.

  1. origin의 fetch URL과 push URL을 읽고, 둘이 다른 저장소를 가리키거나 프리플라이트가 말한 프로바이더, 오너, 저장소가 아니면 거절한다.
  2. 브랜치가 정확히 osfoundry/change-set-<id>이고 <id>가 UUID인지 본다.
  3. 마커가 정확히 GitNest-Change-Set: <id>인지 본다.
  4. 합성 OID가 4~64자 16진수인지 보고, git cat-file -e <oid>^{commit}으로 실제로 있는지 확인한다.
  5. git update-ref refs/heads/<branch> <oid> <old>를 돌린다. <old>는 읽었을 때 ref가 가리키던 값이고, 없었으면 빈 값이다.
  6. refspec 하나만 push한다. git push origin refs/heads/<branch>:refs/heads/<branch>.

스크립트에서는 GitHub 대신 bare 저장소를 하나 세워서 이걸 그대로 재현했다. 클론 쪽에는 오너가 아직 push 안 한 게 두 개 있다. 로컬 브랜치 wip/secret-pricing, 그리고 release/2.4에 올라간 커밋 하나. 합성 커밋은 워크트리 없이 만든다(임시 인덱스, hash-object, update-index --cacheinfo, write-tree, commit-tree).

remote refs before: 3  (dana/refactor-cart, main, release/2.4)
`git push --all` would change 2 remote refs: ['release/2.4', 'wip/secret-pricing']
explicit refspec push changed 1 ref: osfoundry/change-set-5b0c2e8e-3f6a-4d2b-9a71-0c4e9d1f7a23 -> 73e59f27bc4f
untouched: True; marker in pushed commit: True
Enter fullscreen mode Exit fullscreen mode

명시적 refspec을 쓰는 이유는 두 번째 줄에 다 있다. 오너 클론에서 편하게 push했다면 리뷰 안 된 핫픽스랑 비공개 브랜치까지 체인지셋이랑 같이 올라갔을 거다. 명시적 refspec은 ref 하나만 움직이고, 그 이름은 체인지셋 ID에서 나오니까 누구 브랜치랑도 겹칠 일이 없다.

뭐가 거절될까

branch name 'codex/ci' instead of contract     refused: publication branch does not match the preflight contract
marker for another change set                  refused: publication marker does not match the preflight contract
OID 'HEAD' instead of hex                      refused: composition OID must be a hex commit id
hex OID that is not in the clone               refused: fatal: Not a valid object name deadbeefdeadbeefdeadbeefdeadbeefdeadbeef^{commit}
update-ref with a stale expected old value     exit 128: fatal: update_ref failed for ref 'refs/heads/osfoundry/change-set-5b0c2e8e-3f6a-
push URL differs from fetch URL                refused: origin fetch and push remotes point at different repositories
Enter fullscreen mode Exit fullscreen mode

"HEAD" 케이스는 너무 깐깐해 보이지만 그렇지 않다. 심볼릭 이름은 push하는 그 순간 체크아웃돼 있는 걸로 풀리는데, 그게 합성하고 리뷰한 커밋이라는 보장이 없다. 16진수 OID는 커밋 하나만 가리킬 수 있다. 오래된 값으로 update-ref하는 케이스는 git 자체의 compare-and-swap이다. 읽고 쓰는 사이에 로컬 브랜치가 움직였으면 몰래 덮어쓰지 않고 실패한다. URL 체크는 눈에 덜 띄는 구멍을 막는다. git remote set-url --push를 쓰면 push만 fetch와 다른 곳으로 보낼 수 있는데, 코드는 둘이 같은 저장소를 가리켜야만 통과시킨다.

승인할 때 다시 체크하면 뭐가 달라질까

git 단계는 push를 지킨다. expected_ 필드 두 개는 판단을 지킨다. Part 5에서는 툴 설명("Approval rechecks permissions, risk policy, required checks, and target commit")을 바탕으로 재확인을 재구성해 봤다.

as proposed                          publish
recomposed to v4 before the click    refused: change set is v4, card says v3
lint re-ran and failed               refused: required checks not passed: ['lint']
Enter fullscreen mode Exit fullscreen mode

Codex는 버전 3이랑 커밋 73e59f27bc4f…를 읽었고, 오너 카드에도 둘 다 나온다. 그사이 누가 체인지셋을 다시 합성하면, 카드를 승인하는 순간 아무도 안 본 걸 공개하게 되니까 제안이 실패한다. 버전만으로는 부족하다. 같은 버전이라도 합성 결과가 다를 수 있어서다. OID만으로도 부족하다. 오너가 체인지셋의 어느 편집을 뜻했는지는 OID가 말해 주지 않는다. 둘 다 고정하는 데 클라이언트가 내는 비용은 필드 두 개다.

비용은 얼마나 들까

20 runs, local bare remote: compose median 114.2 ms, checks+update-ref+push median 140.0 ms (max 430.0)
Enter fullscreen mode Exit fullscreen mode

체크 6개랑 push를 합쳐도 로컬 bare 리모트 기준 140 ms 정도다. 실제 프로바이더라면 네트워크 왕복이 대부분을 차지한다. 라이브 tools/list 5번이랑 공개 21번까지 포함해서 스크립트 전체가 실제 시간 11.7초, 유저 CPU 3.5초 걸렸다.

직접 만든다면

  • 에이전트한테는 체인지셋이랑 본 것(버전과 커밋)만 넘기게 하고, 브랜치, 제목, 대상, 토큰은 절대 받지 말자. 브랜치 이름은 체인지셋 ID에서 만든다.
  • push는 명시적 refspec 하나로. 사람도 쓰는 클론에서 --all, --mirror, 인자 없는 git push는 금지다.
  • 로컬 ref는 기대하는 이전 값과 함께 쓰고, fetch와 push URL이 같은 저장소인지 확인한다.
  • 공개될 대상은 16진수 OID만 받는다. 심볼릭 이름은 리뷰 뒤가 아니라 리뷰 전에 풀어 둔다.
  • 가져오기 한도는 바이트로 적고 클라이언트에서 확인한다. 스키마의 문자 수 제한으로는 라틴 문자가 아닌 텍스트를 못 잡는다.
  • 다른 사람한테 닿는 툴에는 openWorldHint: true를 붙여서, 내 승인보다 클라이언트 쪽 승인 프롬프트가 먼저 뜨게 하자.

저장소 안에서 체인지셋, 체크, 공개가 어떻게 이어지는지는 GitNest 페이지에, 프로토콜 쪽 이야기는 MCP 용어 설명에 정리돼 있다.

Top comments (0)