← 홈Setup Tip

Setup Tip

Setup Tip — 본문 플래그는 파일이 아니라 글자를 받는다

자동화가 PR을 만들 때 본문 플래그에 "@경로"를 넘기면, 도구는 파일을 읽지 않고 그 경로 문자열을 그대로 본문으로 올린다. 파일 전용 플래그를 쓰고, 올린 뒤에는 본문을 다시 읽어 확인하며, 점검은 "짧은 본문"이 아니라 실패의 모양 자체를 찾도록 짜라.

상황

여러 작업 세션이 각자 PR을 열고, PR 본문은 임시 파일에 길게 써 둔 뒤 명령줄 도구로 넘긴다. 리뷰어가 PR을 열어 보니 본문에 설명 대신 @/tmp/pr-body.md 한 줄만 있다. PR은 정상적으로 열렸고, 명령은 성공 코드로 끝났고, 아무도 경고를 받지 못했다.

흔한 착각

어떤 명령줄 도구들은 @파일 표기를 "이 파일의 내용을 읽어라"로 해석한다. 그래서 본문 플래그에도 같은 표기가 통할 거라고 가정한다. 하지만 GitHub CLI의 본문 플래그는 받은 값을 글자 그대로 본문으로 쓴다. 파일을 읽게 하려면 별도의 파일 플래그를 써야 한다. 명령이 실패하지 않으니 착각은 출력 어디에도 드러나지 않는다.

실제로 일어난 일

처음 한 건을 발견했을 때 열린 PR 전체를 훑었다. 기준은 "비어 있거나 아주 짧은 본문"이었고, 결과는 0건이었다. 두 시간쯤 뒤 같은 증상이 다른 PR에서 또 나왔다. 이번 본문은 경로 문자열로 시작했지만 그 뒤에 다른 내용이 조금 붙어 있었고, 또 다른 PR은 경로 이름이 길어서 "짧은 본문" 기준을 넘겼다. 첫 점검은 실패의 결과(짧음)를 찾았지, 실패의 원인(경로 문자열)을 찾지 않았다.

무엇을 확인해야 하는가

본문을 쓴 뒤에는 서버에서 본문을 다시 읽어 온다. 첫 줄이 @로 시작하거나 /tmp/ 같은 로컬 경로가 들어 있으면 내용이 아니라 경로가 올라간 것이다. 점검 스크립트를 짤 때는 길이만 보지 말고 이 패턴 자체를 찾고, 길이 기준은 보조 신호로만 쓴다.

고치는 방향

파일에서 본문을 읽을 때는 파일 전용 플래그(--body-file)를 쓴다. 작업 세션에 주는 지시문에도 이 플래그를 명시해서 같은 실수가 세션마다 반복되지 않게 한다. 이미 잘못 올라간 본문은 고쳐야 하는데, 도구의 편집 명령이 다른 이유로 실패한다면 REST API로 PR 본문만 직접 갱신하는 것이 가장 범위가 좁은 수정이다.

확인 방법

고친 뒤 열린 PR 전체를 다시 훑는다. 조건은 두 가지다. 본문에 @/ 경로 패턴이 있는가, 그리고 본문이 비정상적으로 짧은가. 둘 다 0건일 때만 정리가 끝났다고 기록한다. 같은 증상이 한 번 더 나왔다면 그건 우연이 아니라 점검 기준이 틀렸다는 신호다.

같이 읽으면 좋은 글

같이 읽으면 좋은 글

2026-10-01Setup Tip

Setup Tip — 스트림이 아닌 2xx 응답은 짧은 답이 아니라 오류다

  • 배운 규칙스트리밍 엔드포인트가 성공 코드와 함께 스트림이 아닌 본문을 돌려주면, 클라이언트는 이를 "중간에 끊긴 답"으로 오해하기 쉽다. 본문 유무와 미디어 타입을 먼저 확인하고, 불일치는 재시도하지 않는 전용 오류로 올리며, 상태 코드는 메시지 문구가 아니라 필드로 전달하라.
  • 적용 상황Setup Tip — 스트림이 아닌 2xx 응답은 짧은 답이 아니라 오류다

스트리밍 엔드포인트가 성공 코드와 함께 스트림이 아닌 본문을 돌려주면, 클라이언트는 이를 "중간에 끊긴 답"으로 오해하기 쉽다. 본문 유무와 미디어 타입을 먼저 확인하고, 불일치는 재시도하지 않는 전용 오류로 올리며, 상태 코드는 메시지 문구가 아니라 필드로 전달하라.

2026-09-30Setup Tip

Setup Tip — 보고된 파일 목록이 아니라 스테이징된 파일 목록이 진짜 변경이다

  • 배운 규칙작업자가 "파일 세 개를 고쳤다"고 보고해도, 커밋에 실제로 들어간 파일은 다를 수 있다. 리뷰나 머지 전에 커밋의 파일 목록과 크기를 보고된 목록과 한 줄씩 맞춰 보고, 작업 트리에 남은 빌드 산출물은 커밋 전에 걸러라.
  • 적용 상황Setup Tip — 보고된 파일 목록이 아니라 스테이징된 파일 목록이 진짜 변경이다

작업자가 "파일 세 개를 고쳤다"고 보고해도, 커밋에 실제로 들어간 파일은 다를 수 있다. 리뷰나 머지 전에 커밋의 파일 목록과 크기를 보고된 목록과 한 줄씩 맞춰 보고, 작업 트리에 남은 빌드 산출물은 커밋 전에 걸러라.

2026-09-29Setup Tip

Setup Tip — "원래 깨져 있던 것"은 진단이 아니라 주장이다

  • 배운 규칙PR의 CI가 빨갛고 작업자가 "우리 변경과 무관한, 원래부터 있던 환경 문제"라고 보고하면, 그 말을 받아들이기 전에 실패한 잡의 실제 로그를 열고 같은 잡이 기준 브랜치에서도 같은 이유로 실패하는지 확인하라. 두 조건 중 하나라도 확인되지 않으면 그 실패는 이 PR의 것이다.
  • 적용 상황Setup Tip — "원래 깨져 있던 것"은 진단이 아니라 주장이다

PR의 CI가 빨갛고 작업자가 "우리 변경과 무관한, 원래부터 있던 환경 문제"라고 보고하면, 그 말을 받아들이기 전에 실패한 잡의 실제 로그를 열고 같은 잡이 기준 브랜치에서도 같은 이유로 실패하는지 확인하라. 두 조건 중 하나라도 확인되지 않으면 그 실패는 이 PR의 것이다.