b3os-github-workflow

Files (1)

• SKILL.md

SKILL.md (first lines)

# GitHub 워크플로 — 변경을 PR로 올려 머지까지

**코드·주석·커밋·PR·문서는 인과관계와 사실로 쓴다. 회고와 사람의 발언은 저장소 밖에서 다룬다. 간결하게, 짧은 문장으로.**

b3os 인프라(소스·config·registry·릴리스)를 고치면 `b3os-infra-safety` 를 먼저 보고 이 절차를 얹는다.

## 무엇을 쓰나 — 저장소에 남는 글은 사실과 인과만

저장소에 들어가는 것은 전부 공개물이다. 용도가 정해져 있다.

| 어디 | 무엇을 |
|---|---|
| README·가이드 | 하는 방법 + 확인 방법 |
| PR 본문 | 무엇이 문제인가(사실) → 왜 그렇게 되나(인과) → 어떻게 고쳤나 → 검증 결과 |
| 커밋 메시지 | 무엇을 바꿨고 왜 그게 맞는가 |
| 코드 주석 | 이 코드가 무엇을 하는가, 왜 이 조건이 필요한가 |
| **메모리·SHARED.md** | **회고·리뷰는 전부 여기.** 밖에 안 나간다 |

**빼는 것은 회고성 서술이다** — 사고 경위, "오늘 우리가", 작업 과정의 날짜, 그 일에 관계없는 사람 이름.

**이 규칙은 PR·문서만이 아니라 코드와 주석에도 적용된다.** 저장소에 남거나 밖으로 나가는 글 전부가 대상이다 — 코드, 주석, 커밋 메시지, PR, 이슈, 외부 문서.

### 빼는 것 셋

**① 팀 대화 인용.** 팀장·팀원이 무슨 말을 했는지는 저장소에 남기지 않는다. 변경의 근거는 **요구사항이나 측정값**으로 적는다. 누가 요청했는지는 근거가 아니다 — 그게 근거라면 다음 사람은 그 말을 찾을 수 없어 판단을 재현하지 못한다.

대상은 **팀 내부 대화**다. **외부 출처는 인용한다** — 업스트림 이슈, 벤더 문서, 표준 문서의 문장이 우회 코드의 유일한 근거인 경우가 있다. 그건 링크와 함께 남긴다. 다음 사람이 실제로 찾아가 확인할 수 있기 때문이다.

**② 자기비판·반성.** "내가 놓쳤다", "이걸 몰라서 밟았다" 는 저장소 밖으로 간다. 남길 값은 후회가 아니라 **무엇이 참인가**다.

**③ 사람에게 귀속된 리뷰 이력.** "누구 리뷰에서 나왔다" 대신 **무엇이 관측됐는지**를 적는다.

### 이렇게 바꾼다

| 쓰지 않는다 | 대신 |
|---|---|
| `팀장님 지시 2026-07-30` | `요구사항:` |
| `GD 결정` · `팀 리드 결정` | `제품 결정:` |
| `팀장님 실측` · `<팀원> 지적` | `실측:` · `리뷰 지적:` |
| `codex 리뷰에서 나온` · `dbak 지적` | `리뷰에서 관측된` |
| `오늘 4건이 조용히 사라졌다` | `이 경로에서 4건이 통보 없이 유실된다` |
| `내가 세 번째까지는 요청했다` | (삭제) |

**남기는 것**: 관측값, 재현 조건, 인과, 검증 방법, 그리고 그 판단이 왜 맞는가.

**절차가 요구하는 신원은 그대로 쓴다** — 커밋 author, `Co-authored-by` 를 비롯한 git trailer, PR 본문의 `Submitted-by`, 리뷰 승인 계정, 코드에서 참조하는 버전·날짜. 이건 인용이 아니라 추적에 필요한 사실이다.

★그중 일부는 기계가 읽는 값이다.★ `Approved-by: <이름>` 은 산문이 아니라 머지 게이트가 `merge_approvers_normal` 과 대조하는 입력이다(`skills/b3os-release-ops/scripts/release-preflight.sh`). 이 규칙을 "사람 이름을 빼라" 로 읽고 지우면 게이트가 깨진다.

### 왜 이게 규칙인가

저장소는 공개물이고, 개인 이름·역할·대화는 코드와 함께 영구히 나간다. 그리고 회고성 서술은 **다음 사람에게 쓸모가 없다** — 그가 필요한 것은 "누가 언제 무엇을 말했다" 가 아니라 "지금 이 조건이 왜 이래야 하는가" 다.

회고·리뷰·교훈은 **메모리와 `SHARED.md`** 로 간다. 없애는 게 아니라 자리를 옮기는 것이다.

## 설정에서 읽을 값

아래 값은 **이 문서에 적지 않는다.** 환경마다 다르고, 문서에 박히면 그 자체가 공격 지점 안내가 된다.

| 값 | 어디서 읽나 |
|---|---|
| 팀원 작업용 GitHub 계정 | 설정 `github_team_account` |
| 승인용 GitHub 계정 | 설정 `github_approver_account` |

이 단계를 건너뛰면 PR 이 승인 계정으로 만들어져 머지가 막힌다.

**읽는 법:**

```bash
S=$(curl -fsS http://127.0.0.1:7878/team/api/settings)
TEAM_ACCOUNT=$(printf '%s' "$S" | python3 -c 'import json,sys;print(json.load(sys.stdin)["github_team_account"])')
[ -n "$TEAM_ACCOUNT" ] || { echo "설정이 비어 있다 — 중단"; exit 1; }
```

**비어 있으면 팀장에게 물어서 채운다.** 값을 지어내지 않는다. 물어볼 것은 둘이다 —
**PR 을 올릴 계정**과 **승인할 계정**. 두 계정은 서로 달라야 리뷰 요건이 성립한다.

**쓰는 법:**

```bash
curl -X PUT -H 'Content-Type: application/json' \
  -d '{"github_team_account":"<팀 작업 계정>","github_approver_account":"<승인 계정>","merge_approvers_normal":"<승인 가능한 팀원>"}' \
  http://127.0.0.1:7878/team/api/settings
# 성공하면 반드시 다시 읽어 확인한다 — 쓰기 성공이 반영을 뜻하지 않는다
curl -fsS http://127.0.0.1:7878/team/api/settings | python3 -m json.tool | grep github
```

**세 값은 한 번에 검증되고 한 번에 저장된다** — 하나가 틀리면 **아무것도 안 바뀐다**
(반쯤 바뀐 보안 설정이 제일 위험하다). 이름에 한글·`@` 를 쓰면 **쓰는 시점에 400** 이다 — 판정기가 못 읽는 값을 넣어두면 **머지할 때 알 수 없는 이유로 막힌다.**

**API 응답에 그 키가 없으면 아직 이 변경이 배포되기 전이다.** 그때 한해 DB 에서 직접 읽어 진행할 수 있다
(그 기능을 처음 올리는 부트스트랩 상황).
**배포 후에는 API 만 쓴다** — DB 직접 읽기는 정상 경로가 아니다.
| 커밋 신원 이메일 | 설정 `github_team_commit_email` |
| tier별 승인자 | 설정 (`merge_approvers_*`) · 판정은 `approvals.ts` |
| 저장소·조직 | `git remote` 실측 |

**설정이 비어 있으면 진행하지 않는다.** 기본값으로 때우면 팀장 개인 계정으로 나가고, 그게 이 절차가 막으려는 바로 그 일이다.

## 핵심 원칙 — 절차는 "확인되는 형태"로

이 스킬의 모든 단계에는 **확인 명령**이 붙어 있다. 이유가 있다.

**안내가 시키는 것과 실제로 벌어지는 일은 어긋날 수 있고, 어긋나도 아무 표시가 없다.**
커밋 메시지에 "테스트 추가"라고 적혀도 리포에 테스트가 없을 수 있다.

그래서 이 절차는 **믿지 않고 확인한다.** 확인 명령이 기대와 다르게 나오면 **그 자리에서 멈춘다**(fail-closed). 조용히 진행하는 것보다 시끄럽게 멈추는 게 항상 낫다.

## 절차

### ① 격리 — 브랜치와 worktree

한 과제 = 한 브랜치. 공유 main 워킹트리에 직접 쓰지 않는다. 상세는 `b3os-infra-safety` ①②.

```bash
git worktree add <경로> -b <브랜치> origin/main
```

### ② 커밋 신원 — 팀원 이름 + 팀 계정 (★조용히 틀리는 지점★)

From b3rys/b3rys-team-os, Apache-2.0.

More from b3rys/b3rys-team-os