GitHub
원리와 실전

1장 GitHub의 기본과 첫 저장소

파일과 이력과 원격의 관계를 이해한 뒤 내 계정과 첫 저장소를 준비한다. 소유자와 공개 범위를 확인하는 습관부터 시작한다.

저장소는 파일 묶음과 변경의 근거를 함께 보관한다

버전 관리는 파일을 여러 벌 복사하는 방법에서 출발해 생각할 수 있지만 Git의 구조를 이해하려면 상태와 참조를 구분해야 한다. 상태는 특정 시점의 파일 내용이다. 참조는 그 상태를 찾아가는 이름이다. 저장소에는 파일 상태를 표현하는 객체와 이들을 연결하는 이력 및 읽기 쉬운 이름이 존재한다. GitHub는 이 Git 저장소에 검토와 권한 및 자동화와 의사소통 기능을 더한다.

lesson-lab의 안내 문서를 고치는 사례를 보자. 이전 파일을 덮어쓴 뒤에도 과거 커밋을 통해 이전 상태를 읽을 수 있다. 다만 Git이 기록한 적 없는 미저장 편집이나 무시된 파일까지 보존해 주지는 않는다. 버전 관리가 보장하는 범위를 이해해야 백업과 협업의 책임을 정확히 나눌 수 있다.

Git의 분산성은 여러 저장소가 자체 이력을 가질 수 있다는 뜻이다. 로컬에서 커밋을 만드는 데 중앙 서버의 승인이 필요하지 않다. 그러나 어떤 커밋을 팀의 공식 결과로 인정할지는 조직의 절차와 권한 정책이 결정한다. 기술적으로 분산된 이력과 사회적으로 정한 기준 브랜치는 함께 존재한다. 분산 구조가 협업 규칙을 불필요하게 만드는 것은 아니다.

공개된 기록은 협업의 맥락이 된다

Dabbish 등의 연구는 GitHub 사용자를 인터뷰하고 활동을 관찰해 작업의 가시성이 협업과 학습에 어떤 역할을 하는지 살폈다. 변경 이유와 활동 이력이 드러나면 다른 사람이 작업을 이해하고 의존성을 파악하는 데 도움이 될 수 있다는 관점이다. 이는 초기 GitHub의 질적 연구이며 현재 모든 팀의 성과를 수치로 보장하는 결과는 아니다. [S12]

이 관점을 lesson-lab에 적용하면 커밋 메시지는 개인의 메모를 넘어 다음 작업자를 위한 설명이 된다. README 수정이라는 제목보다 새 사용자의 실행 경로를 명확히 했다는 설명이 검토의 목적을 보여 준다. 실제 차이는 코드에서 읽을 수 있지만 그 변경을 선택한 이유는 기록하지 않으면 사라질 수 있다.

공개성이 항상 필요한 것은 아니다. 협업에 필요한 가시성과 외부 공개는 구분한다. 비공개 저장소에서도 팀 내부의 변경 이력과 검토 과정은 공유할 수 있다. 공개 범위는 자료의 성격과 참여자 및 배포 목적을 기준으로 정하며 학습용 사례에는 실제 비밀이나 개인정보를 넣지 않는다.

저장소의 동일성을 세 가지 질문으로 나눈다

버전 관리에서 같다는 말은 파일 내용이 같다는 뜻일 수도 있고 같은 커밋을 가리킨다는 뜻일 수도 있다. 여기에 같은 저장소에서 관리한다는 조직적 의미가 더해진다. 파일의 내용과 커밋의 정체성과 저장소의 소유권은 서로 다른 층이다. 이 구분은 저장소를 복사하거나 이름을 바꾸거나 다른 조직으로 이전할 때 중요해진다.

Git 객체의 식별자는 객체 종류와 길이 및 내용을 포함하는 직렬화된 표현에서 계산된다. 파일의 경로는 blob 자체의 내용이 아니라 tree의 항목에 연결된다. 따라서 같은 바이트를 가진 두 파일이 다른 경로에서 같은 blob을 참조할 수 있다. 같은 tree를 가리키더라도 부모와 메시지 등 커밋의 다른 정보가 달라지면 커밋 식별자는 달라질 수 있다. 이 구조는 내용의 재사용과 변경 이력의 식별을 함께 가능하게 한다. [T01] [T38]

lesson-lab의 안내문을 복사해 별도 저장소에 넣었다고 하자. 안내문 바이트가 같다는 관찰은 가능하지만 원래의 리뷰와 배포 승인 및 조직 정책까지 옮겨졌다고 말할 수는 없다. 같은 코드라는 주장과 같은 관리 절차를 거쳤다는 주장을 별도로 확인해야 한다. 소스 파일을 전달할 때 커밋과 배포 기록을 함께 남기는 이유도 여기에 있다.

무결성 확인과 작성자 확인을 구분한다

해시는 예상한 바이트와 현재 바이트를 비교하는 데 유용하다. 그러나 기대하는 해시를 공격자가 함께 바꾸었다면 두 값이 일치한다는 사실만으로 신뢰할 수 없다. 해시를 어디에서 받았는지와 누가 그 값을 보증하는지가 추가로 필요하다. 암호학적 해시와 전자서명이 해결하는 질문이 다른 이유다.

커밋을 식별할 수 있다는 사실은 코드가 올바르거나 안전하다는 뜻도 아니다. 의도적으로 잘못 만든 프로그램도 정확한 식별자를 가진다. 실무에서는 대상 식별과 출처 확인 및 기능 검증을 각각 수행한다. 이 세 판단을 분리하면 서명이 있으니 테스트를 생략해도 된다는 식의 잘못된 결론을 피할 수 있다.

GitHub 저장소의 이름은 사용자가 찾기 쉬운 주소다. 자동화의 중요한 권한 판단에서는 이름이 바뀌거나 재사용되는 상황도 고려한다. 사람이 읽는 이름과 시스템이 유지하는 식별자를 함께 이해하면 저장소 이전 뒤 인증이 실패하는 원인을 더 정확히 설명할 수 있다. 구체적인 OIDC의 식별 규칙은 배포 권한을 다루는 장에서 이어서 살펴본다.

# 수업 도구 연습실

## 이 저장소의 목적
GitHub의 변경 기록과 협업을 연습한다.

## 현재 기능
- 안내 문서
- 수업용 HTML 예제

## 실행 방법
index.html을 브라우저로 연다.

2장 웹에서 문서와 변경 제안

브라우저에서 작은 변경을 제안하고 읽기 쉬운 문서를 만든다. 실제 화면에서 편집 위치를 찾고 검토한 버전의 링크를 공유한다.

문서는 실행 경로를 안내하는 인터페이스다

README는 프로젝트를 홍보하는 표지에 그치지 않는다. 사용자가 무엇을 준비하고 어느 명령을 실행하며 어떤 결과를 기대해야 하는지 알려 주는 인터페이스다. 실행 안내가 실제 코드와 어긋나면 소프트웨어의 사용 가능성이 낮아진다. 따라서 README 변경도 코드 변경과 같은 방식으로 검토하고 확인할 수 있다.

lesson-lab에서 실행 명령을 바꾸는 PR이라면 문서와 설정 파일이 함께 바뀌어야 할 수 있다. 문서만 수정해 존재하지 않는 명령을 안내하거나 설정만 바꾸고 기존 안내를 남기면 계약이 깨진다. 검토자는 문장의 자연스러움뿐 아니라 실제 실행 가능성을 확인한다. 이 원리는 API 문서와 환경 변수 설명 및 배포 안내에도 적용된다.

PR은 두 브랜치 사이의 제안이며 커밋 자체가 아니다

Pull request는 어떤 변경을 어느 기준에 통합할지 논의하는 객체다. Base는 변경을 받을 기준이며 Head는 제안된 작업의 끝이다. PR에는 커밋과 차이 및 대화와 검사 결과가 연결된다. 브랜치를 이동시키면 PR의 내용도 달라질 수 있으므로 검토한 시점의 커밋을 알아야 한다.

GitHub의 PR 차이와 로컬에서 두 커밋을 직접 비교한 차이는 비교 기준이 달라 보일 수 있다. 공통 조상에서 제안 브랜치까지의 변화와 두 최신 스냅샷 사이의 차이는 같은 질문이 아니다. 기능 브랜치가 기준 브랜치보다 뒤처져 있을 때 이 차이가 중요해진다. 차이를 해석하기 전에 무엇과 무엇을 비교했는지 확인한다. [T03]

PR 본문은 문제와 변경 및 검증을 연결한다. 검색 결과 수가 갱신되지 않는 문제를 고쳤다면 실패 조건과 수정 지점 및 재현 결과를 함께 적는다. 검토자가 구현자의 전체 작업 과정을 추측하지 않고 핵심 판단을 확인할 수 있게 하는 것이 목적이다. 긴 템플릿을 채우는 것보다 주장과 증거가 일치하는지가 중요하다.

비교 화면의 기준점이 검토 대상을 결정한다

변경 제안은 항상 무엇과 무엇을 비교하는지에 의존한다. 기능 브랜치의 끝과 현재 main의 끝을 직접 비교하는 것과 두 브랜치가 갈라진 공통 조상부터 기능 브랜치의 끝을 비교하는 것은 다른 질문이다. 전자는 현재 두 결과물의 차이에 가깝고 후자는 기능 브랜치 쪽에서 도입한 변경을 이해하는 데 유용하다.

커밋 집합을 읽는 명령에서는 A..B가 B에서 도달할 수 있지만 A에서는 도달할 수 없는 커밋을 뜻한다. A...B는 두 쪽 중 한쪽에서만 도달할 수 있는 커밋의 집합이다. 반면 git diff A...B는 공통 조상과 B의 결과를 비교하는 용법이다. 점의 개수만 외우면 같은 표기를 모든 명령에서 같은 의미로 해석하기 쉽다. 명령이 이력 집합을 다루는지 파일 상태를 비교하는지 먼저 구분한다. [T19] [T03]

main에 문서 개편이 먼저 들어간 상태에서 feature는 검색 기능만 추가했다고 하자. 두 끝점을 비교하면 main의 문서 변경을 feature가 되돌리는 것처럼 보이는 부분이 생길 수 있다. 이때 비교 화면의 기준점을 알면 실제 의도와 화면의 차이를 구분할 수 있다. 검토자가 먼저 확인할 것은 변경 줄의 수보다 비교의 출발점이다.

문서와 구현을 같은 변경 계약에 묶는다

README의 실행 명령이 코드의 실제 시작점과 다르면 문서가 존재해도 재현은 실패한다. 문서의 예시는 실행 가능한 계약의 한 표현으로 볼 수 있다. 필요한 환경과 입력 및 기대 결과를 포함한 예시는 처음 읽는 사람이 성공 여부를 판정하게 한다. 설치 명령이 있다는 사실과 그 명령이 현재 판본에서 작동한다는 사실은 구분해야 한다.

PR에서 함수의 입력 이름을 바꾸었다면 호출 코드와 예시 및 오류 메시지에도 영향이 있는지 확인한다. 문서 수정과 코드 수정을 별개의 완료 목록으로만 관리하면 변경의 연결이 끊어질 수 있다. 변경 이유 하나에 연결되는 자료를 함께 검토하는 편이 적은 수정으로도 계약의 일관성을 높인다.

## 바꾼 내용
README에 사용 대상과 실행 방법을 보강했다.

## 바꾼 이유
처음 방문한 교사가 시작 위치를 알기 어렵다.

## 확인 방법
- README 화면에서 안내를 읽었다.
- main과 작업 브랜치의 차이를 비교했다.

## 빠른 시작
1. Code 메뉴에서 Download ZIP을 선택한다.
2. 압축을 푼다.
3. index.html을 연다.

## 사용 안내
[자세한 설명](docs/guide.md)

## 알려진 한계
인터넷 없이도 열리지만 외부 링크는 연결이 필요하다.

repo:YOUR-ID/lesson-lab path:README.md
repo:YOUR-ID/lesson-lab path:.github/ language:YAML
repo:YOUR-ID/lesson-lab content:answer

3장 내 컴퓨터의 작업 환경

Desktop과 편집기와 터미널의 역할을 연결한다. Clone한 실제 폴더에서 작업하고 로컬 기록이 원격에 도착했는지 확인한다.

화면이 달라도 같은 저장소 상태를 다룬다

GitHub Desktop과 VS Code 및 터미널은 서로 다른 인터페이스다. 같은 로컬 저장소를 열고 있다면 공통된 Git 객체와 Index 및 작업 트리를 다룬다. 한 도구에서 스테이징한 변경은 다른 도구에서도 관찰할 수 있다. 다만 갱신 시점과 표시 방식이 다를 수 있으므로 상태가 의심스러우면 현재 경로와 브랜치를 먼저 확인한다.

초보자가 자주 겪는 문제는 명령 자체보다 작업 위치다. 같은 이름의 lesson-lab 폴더를 두 곳에 만들면 편집기와 터미널이 서로 다른 저장소를 보고 있을 수 있다. git rev-parse --show-toplevel로 저장소 루트를 확인하면 비교 기준을 잡을 수 있다. 경로 확인은 사소한 준비가 아니라 재현 가능한 작업의 일부다.

구성 값에는 범위가 있다

Git 설정에는 시스템과 사용자 및 저장소 범위가 있다. 특정 저장소의 설정이 사용자 기본값을 덮어쓸 수 있다. 회사 프로젝트와 개인 프로젝트에서 작성자 이메일이 다른 경우 저장소 단위 설정을 사용하는 이유다. git config --show-origin --get user.email처럼 값과 출처를 함께 확인하면 예상과 다른 설정의 원인을 좁힐 수 있다.

커밋의 author와 committer는 다른 역할이다. 원래 변경을 작성한 사람과 현재 커밋 객체를 만든 사람이 다를 수 있다. 작성자 이름을 지정하는 것은 신원 인증과 동일하지 않다. 나중에 서명을 배우더라도 서명이 코드의 품질을 보증하는 것은 아니라는 점을 기억해야 한다.

재현 가능한 개발 환경에는 런타임과 의존성 및 실행 명령이 포함된다. 저장소를 Clone했다는 사실만으로 모든 실행 환경이 준비되는 것은 아니다. README에는 설치와 검사 및 실행의 순서를 적고 필요한 환경 변수의 이름을 설명한다. 실제 비밀값은 저장소 밖에서 관리한다.

줄바꿈 차이는 실제 내용 차이로 기록될 수 있다

화면에서 같은 문장으로 보여도 파일의 바이트는 다를 수 있다. 운영체제와 편집기가 사용하는 줄바꿈이 다르면 거의 모든 줄이 바뀐 것처럼 나타나기도 한다. .gitattributes는 경로별 텍스트 처리와 줄바꿈 같은 저장소 정책을 표현한다. text와 eol 설정은 작업 트리의 표현과 저장되는 표현을 연결하는 규칙이다. [T21]

* text=auto
*.sh text eol=lf
*.png -text
*.pdf -text

이 예시는 텍스트를 자동 판별하고 셸 스크립트의 줄바꿈을 LF로 두며 이미지와 PDF를 텍스트 정규화에서 제외한다. 기존 저장소에 도입할 때는 기능 수정과 한 번의 정규화 변경을 나누는 편이 검토하기 쉽다. 대규모 줄바꿈 변화와 실제 로직 수정을 한 PR에 섞으면 중요한 차이를 찾기 어려워진다.

정규화는 모든 파일을 같은 방식으로 바꾸는 작업이 아니다. 바이너리 파일에 텍스트 처리를 적용하면 의미 없는 변형을 만들 수 있다. 팀의 편집기 설정과 Git의 경로별 정책이 충돌하지 않는지도 확인한다. 문제가 생기면 파일을 계속 다시 저장하기보다 어떤 단계에서 바이트가 바뀌는지 살핀다.

실행 환경은 의존성 목록보다 넓다

같은 소스와 같은 패키지 목록을 사용해도 운영체제와 CPU 구조 및 시스템 라이브러리가 다르면 결과가 달라질 수 있다. 시간대와 locale 및 기본 문자 인코딩도 출력에 영향을 준다. 정렬된 이름 목록이 다른 순서로 보이거나 날짜가 하루 어긋나는 현상은 로직보다 환경 차이에서 시작될 수 있다.

재현 기록에는 영향을 줄 수 있는 변수만 우선 포함한다. 모든 환경 변수를 덤프하면 비밀을 노출할 수 있고 분석에 필요한 정보가 묻힌다. 런타임 버전과 패키지 잠금 파일 및 실행 명령과 입력 자료를 기본으로 남긴다. 문제가 특정 환경에서만 나타난다면 그 차이를 추가한다. 기록의 목적은 양을 늘리는 것이 아니라 실패를 다시 만들 수 있게 하는 것이다.

로컬에서 실행한 명령이 CI에서 실패하면 명령 자체뿐 아니라 작업 디렉터리와 파일의 대소문자 및 실행 권한을 비교한다. 로컬 파일 시스템이 허용한 경로 표기가 다른 환경에서는 실패할 수 있다. 개발 환경을 공유하는 것은 편집 화면을 같게 만드는 일보다 실행 전제를 명시하는 일에 가깝다.

git --version
gh --version
pwd

git config --global user.name 'YOUR-NAME'
git config --global user.email 'YOUR-COMMIT-EMAIL'
git config --global init.defaultBranch main
git config --global --get user.name
git config --global --get user.email

git version 2.x.x
bash: git: command not found
fatal: not a git repository

git rev-parse --show-toplevel
git status
git branch --show-current
git remote -v

git clone https://github.com/YOUR-ID/lesson-lab.git
cd lesson-lab
git status
git remote -v

git init -b main
git add README.md
git commit -m 'Add project introduction'
git remote add origin https://github.com/YOUR-ID/NEW-REPO.git
git push -u origin main

git rev-parse --show-toplevel
git remote -v
git branch --show-current
git log -1 --oneline

git clone https://github.com/YOUR-ID/lesson-lab.git lesson-lab-check
cd lesson-lab-check
git log -5 --oneline
git status

git remote set-url origin https://github.com/YOUR-ID/lesson-lab.git
git remote -v

4장 인증과 변경 기록과 원격 동기화

접속 권한을 확인하고 다음 커밋에 넣을 변경을 선택한다. VS Code의 화면과 Git 명령을 비교한 뒤 Fetch와 Pull과 Push를 구분한다.

add는 파일 이름을 예약하는 명령이 아니다

작업 트리는 편집 중인 파일 상태다. Index는 다음 커밋에 사용할 경로와 내용의 상태를 표현한다. git add는 실행 시점의 파일 내용을 Index에 반영한다. 그 뒤 파일을 다시 편집해도 Index가 자동으로 최신 상태가 되지는 않는다. 같은 파일이 스테이징된 변경과 스테이징되지 않은 변경에 동시에 나타날 수 있는 이유다.

lesson-lab의 README에 사용 대상 안내를 추가한 뒤 add를 실행하고 다시 실행 명령을 수정해 보자. git diff는 두 번째 수정만 보여 주고 git diff --staged는 첫 번째 수정을 보여 준다. 이 관찰을 통해 두 명령이 서로 다른 상태를 비교한다는 사실을 확인할 수 있다. 커밋 직전에는 다음 커밋에 실제로 들어갈 차이를 확인해야 한다.

스테이징은 커밋의 논리적 경계를 만드는 장치다. 한 파일에서 버그 수정과 표현 개선을 동시에 했더라도 git add -p로 변경 덩어리를 선택할 수 있다. 다만 선택한 조합이 독립적으로 실행 가능한지는 사람이 판단해야 한다. 기계적으로 작은 커밋을 많이 만드는 것과 설명 가능한 변경 단위를 만드는 것은 다르다.

커밋은 스냅샷과 부모 관계를 기록한다

Git의 blob은 파일 내용을 표현하고 tree는 이름과 모드 및 하위 객체의 관계를 표현한다. commit은 최상위 tree와 부모 커밋 및 작성 정보와 메시지를 연결한다. 파일 이름은 blob 자체에 들어 있지 않으므로 같은 내용이 여러 경로에서 재사용될 수 있다. 실제 저장소는 압축과 packfile 등을 사용하므로 논리적 객체 구조와 물리적 저장 방식을 구분한다. [T01]

객체 ID는 객체의 내용에 의존한다. 커밋 메시지나 부모가 바뀌면 같은 파일 스냅샷이라도 다른 커밋 ID가 생길 수 있다. rebase가 이력을 재작성한다고 말하는 이유가 여기에 있다. 해시가 존재한다는 사실은 내용 식별과 무결성 확인에 도움을 주지만 작성자의 정당성이나 코드의 안전성을 자동으로 증명하지는 않는다.

origin/main은 서버를 실시간으로 바라보는 창이 아니다

origin은 원격 저장소 주소에 붙인 로컬 별칭이다. origin/main은 마지막으로 가져온 원격 main의 위치를 기록하는 원격 추적 참조다. 다른 사람이 서버의 main을 바꾸어도 내 origin/main은 fetch하기 전까지 오래된 상태일 수 있다. 따라서 로컬 화면의 ahead와 behind 정보도 관찰한 원격 상태를 기준으로 해석한다.

fetch는 객체와 참조 정보를 가져오는 과정이며 현재 작업 브랜치에 통합하는 과정과 구분된다. pull은 가져오기와 통합을 함께 수행하며 통합 방식은 옵션과 설정에 따라 달라진다. 먼저 fetch한 뒤 차이를 읽으면 어떤 변경을 받아들일지 명시적으로 판단할 수 있다. [T02]

충돌 상태의 Index에는 여러 후보가 공존한다

일반적인 Index 항목은 다음 스냅샷에 들어갈 파일 상태를 표현한다. 병합 충돌 중에는 한 경로에 최대 세 단계의 항목이 존재할 수 있다. stage 1은 공통 기반이며 stage 2와 stage 3은 병합의 두 쪽이다. git ls-files --unmerged는 이 상태를 관찰하는 명령이다. 작업 트리에 보이는 충돌 표식과 Index에 보관된 후보는 서로 다른 표현이다. [T18]

충돌을 해결한다는 것은 표식 문자를 지우는 일에서 끝나지 않는다. 두 후보의 의도와 기반 상태를 읽고 최종 내용을 결정해야 한다. 최종 파일을 git add로 기록하면 다음 커밋의 후보를 확정하는 단계로 넘어간다. 아무 내용이나 저장해 표식만 없애도 Git의 텍스트 충돌은 사라질 수 있으므로 의미의 검증은 별도로 필요하다.

rebase 중에는 어떤 쪽을 ours와 theirs라고 부르는지 직관과 어긋날 수 있다. 현재의 기반 위에 커밋을 다시 적용하는 문맥이기 때문이다. 사람 이름이나 브랜치 이름을 추정해 한쪽 전체를 선택하기보다 각 단계의 실제 내용과 적용 중인 커밋을 확인한다. 충돌 도구의 버튼 이름만으로 판단하지 않는 습관이 중요하다.

참조를 갱신할 때도 읽은 상태가 바뀌었을 수 있다

자동화가 브랜치의 현재 값을 읽은 뒤 새 값으로 바꾸기까지 다른 작업이 같은 브랜치를 갱신할 수 있다. 이때 이전 관찰을 전제로 무조건 쓰면 타인의 변경을 덮어쓸 수 있다. git update-ref는 이전 객체 식별자를 함께 주어 현재 값이 예상과 같을 때만 갱신하는 방식을 지원한다. 이는 비교 후 갱신이라는 일반적인 동시성 제어의 한 사례다. [T20]

개념적으로 현재 값이 A일 때만 B로 바꾼다는 조건이다. 조건이 실패하면 다시 읽고 충돌을 해결해야 한다. 실패했다는 이유로 조건을 제거하면 보호 장치의 의미가 없어진다. 원격 Push의 lease 조건도 이런 사고방식으로 이해할 수 있다. 자동화의 편의를 위해 예상값 검사를 지우지 않는다.

이 원리를 이해했다고 모든 사용자가 저수준 명령으로 브랜치를 직접 조작할 필요는 없다. 일반적인 작업은 switch와 commit 및 merge로 수행한다. 내부 갱신의 계약을 알면 도구가 경쟁 상태를 거부했을 때 강제로 우회하기 전에 무엇을 다시 확인해야 하는지 알 수 있다.

관련 근거 [T11]

add 이후 다시 편집하면 무엇이 다른가

GIF 재생이전 상태다음 상태

마지막 상태

1. 처음에는 네 위치가 같은 내용을 가리킨다
2. 편집과 저장은 작업 트리를 바꾼다
3. git add는 현재 내용을 Index에 반영한다
4. 다시 편집해도 Index는 자동 갱신되지 않는다
5. git commit은 Index의 v2를 기록한다
6. git push 뒤에도 미커밋 v3는 로컬에 남는다

gh auth login
gh auth status
gh auth setup-git

git remote -v
git fetch origin
git branch --show-current

git status
git diff
git add README.md
git diff --staged
git commit -m 'Clarify lesson setup'

 M README.md
M  README.md
MM README.md

git diff --staged
git diff
git show --stat HEAD

git diff
git diff --staged
git add README.md
git diff --staged
git commit -m 'Add two setup notes'
git show --stat HEAD

git status
git diff --staged
git diff

git fetch origin
git log --oneline --left-right HEAD...origin/main
git status -sb

git switch main
git fetch origin
git log -5 --oneline origin/main
git pull --ff-only
git status -sb

git switch -c feature/fetch-note
# 편집기에서 README를 수정하고 저장
git add README.md
git commit -m 'Document fetch behavior'
git push -u origin feature/fetch-note
git branch -vv

5장 브랜치 통합과 충돌 해결

갈라진 작업을 통합하고 충돌한 요구를 함께 반영한다. Stash와 Rebase와 Cherry-pick의 목적을 구분하며 부모 관계로 이력을 읽는다.

브랜치는 가벼운 이름이며 이력은 방향 있는 그래프다

커밋은 부모를 가리킨다. 자식 커밋에서 부모를 따라가면 과거 이력을 읽을 수 있다. 이 관계는 순환하지 않는 방향 그래프를 이룬다. 브랜치는 그 그래프의 한 커밋을 가리키는 이동 가능한 참조다. 브랜치 생성은 폴더 전체를 복사하는 작업이 아니며 브랜치를 지웠다고 즉시 모든 관련 객체가 사라지는 것도 아니다.

한 브랜치의 끝이 다른 브랜치 끝의 조상이라면 fast-forward가 가능하다. 기준 참조를 앞으로 이동시키면 되기 때문이다. 양쪽에서 독립적인 커밋이 생겼다면 서로 다른 계보를 통합해야 한다. 일반적인 merge commit은 두 부모를 기록해 두 작업 흐름이 만났음을 보존한다.

충돌은 텍스트 통합의 실패이며 의미 통합의 전부가 아니다

세 방향 병합은 공통 조상과 양쪽 변경을 비교한다. 같은 줄 근처를 다르게 바꾸면 도구가 자동 선택하지 못해 충돌을 표시할 수 있다. 하지만 충돌 표시가 없다고 기능이 올바르게 결합된다는 뜻은 아니다. 한 브랜치가 함수 이름을 바꾸고 다른 브랜치가 다른 파일에서 이전 이름을 호출하면 텍스트 병합은 성공해도 실행은 실패할 수 있다.

lesson-lab에서 한 사람은 자료 필드명을 subject에서 category로 바꾸고 다른 사람은 subject를 사용하는 필터를 추가했다고 하자. 파일이 다르면 Git이 병합 충돌을 표시하지 않을 수 있다. 병합 후 테스트가 필요한 이유는 Git이 파일 차이를 통합하는 도구이지 모든 업무 의미를 이해하는 검증기가 아니기 때문이다.

충돌을 해결할 때는 어느 쪽을 남길지보다 최종 프로그램이 어떤 규칙을 만족해야 하는지 먼저 정한다. 충돌 표식을 지우는 것은 문법적 정리일 뿐이다. 관련 함수와 테스트 및 문서를 함께 읽고 결과를 실행한다. 병합 중단 경로를 알고 시작하면 잘못된 상태에서 억지로 마무리할 필요가 줄어든다.

rebase는 과거 객체를 움직이는 대신 새 계보를 만든다

rebase는 선택한 커밋의 변경을 새로운 기준 위에 다시 적용해 새로운 커밋을 만든다. 부모 관계가 바뀌므로 ID도 달라진다. 이미 공유한 커밋을 재작성하면 다른 사람의 참조와 어긋날 수 있다. 따라서 개인 작업 이력을 정리하는 경우와 팀이 이미 사용하는 이력을 바꾸는 경우를 구분한다.

merge와 rebase 중 하나가 언제나 더 전문적인 방식은 아니다. 병합 관계를 보존하는 가치와 선형 이력의 읽기 쉬움 및 팀의 복구 절차를 비교해야 한다. Squash도 여러 변경을 하나의 새 커밋으로 묶는 정책이며 원래 커밋의 세부 경계가 기준 브랜치에서 달라진다. 선택한 정책이 리뷰와 원인 조사에 어떤 영향을 주는지 함께 판단한다.

텍스트 충돌이 없다는 사실은 통합 성공의 일부다

두 수정이 다른 줄을 바꾸면 Git은 자동으로 합칠 수 있다. 그러나 한쪽이 함수의 단위를 초에서 밀리초로 바꾸고 다른 쪽이 그 값을 표시하는 계산을 추가했다면 문법적으로 합쳐져도 의미가 틀릴 수 있다. 텍스트의 겹침과 프로그램의 동작 및 업무 규칙의 충돌은 서로 다른 층이다.

자료 탐색기에서 한 PR은 삭제한 자료의 즐겨찾기를 유지하고 다른 PR은 삭제 즉시 즐겨찾기도 정리한다고 가정하자. 둘 다 독립적으로는 합리적인 정책일 수 있다. 통합 전에 삭제의 의미를 합의하지 않으면 테스트를 더 추가해도 서로 다른 기대를 검증하게 된다. 기술적 병합에 앞서 업무 규칙의 일치를 확인해야 한다.

병합 결과를 재현 가능한 입력으로 검증한다

병합 전 각 브랜치에서 통과했던 입력을 통합 결과에서도 실행한다. 여기에 두 변경이 동시에 작용하는 입력을 추가한다. 각각의 기능을 따로 시험하는 것만으로는 상호작용을 확인할 수 없다. 검색과 즐겨찾기를 동시에 바꾼 경우에는 즐겨찾기 필터를 켠 상태에서 검색어를 변경하는 경로가 중요하다.

리뷰 기록에는 충돌 파일의 목록보다 해결한 규칙을 적는 편이 유용하다. 한쪽을 선택했다는 말보다 저장 형식은 새 버전을 따르고 이전 자료는 읽을 때 변환하도록 했다고 설명한다. 이후 오류가 발견되면 어떤 판단을 되돌리거나 수정해야 하는지 찾을 수 있다.

장기 브랜치는 한 번에 통합해야 하는 가정의 수를 늘릴 수 있다. 변경을 작게 나누고 자주 기준 브랜치와 관계를 확인하면 충돌의 원인을 좁히기 쉽다. 다만 통합 빈도 자체를 목표로 삼아 미완성 동작을 무조건 공개해서는 안 된다. 기능 노출과 코드 통합을 분리할 수 있는 구조가 필요할 수 있다.

병합은 두 이력을 한 결과로 연결한다

GIF 재생이전 상태다음 상태

마지막 상태

1. 두 브랜치가 A에서 출발한다
2. main에 B가 추가된다
3. feature에 C가 추가되어 이력이 갈라진다
4. 공통 조상과 양쪽 변경으로 결과를 계산한다
5. M은 양쪽 부모 관계를 보존한다

<<<<<<< HEAD
현재 브랜치의 문장
=======
합쳐 오는 브랜치의 문장
>>>>>>> feature/topic

mkdir conflict-practice
cd conflict-practice
git init -b main
printf '시작 문장\n' > note.txt
git add note.txt
git commit -m 'Start note'
git switch -c branch-a
printf 'A의 설명\n' > note.txt
git commit -am 'Write A explanation'
git switch main
printf 'B의 설명\n' > note.txt
git commit -am 'Write B explanation'
git merge branch-a

git add note.txt
git diff --check
git commit -m 'Combine both explanations'
git log --graph --oneline --all

git stash push -u -m 'WIP lesson note'
git stash list
git stash apply
# 확인 후 필요한 항목만 삭제
git stash drop 'stash@{0}'

git stash list
git stash show --stat 'stash@{0}'
git stash apply 'stash@{0}'

git switch feature/fetch-note
git status
git branch backup/before-rebase
git fetch origin
git rebase origin/main

git show COMMIT-ID
git cherry-pick COMMIT-ID
# 충돌 해결 후
git add CHANGED-FILE
git cherry-pick --continue
# 전체 적용을 취소하려면
# git cherry-pick --abort

commit SAMPLE-ID
parent FIRST-PARENT-ID
parent SECOND-PARENT-ID

git log --graph --oneline --all
git show --no-patch --pretty=raw HEAD

6장 복구와 파일 관리와 이력 읽기

되돌릴 대상과 보존할 변경을 먼저 정한다. 무시 규칙과 줄바꿈과 큰 파일을 관리하고 로그와 Diff로 변경 이유를 조사한다.

되돌린다는 말에는 여러 작업이 들어 있다

파일 내용을 이전 상태로 복원하는 일과 브랜치 참조를 과거로 이동시키는 일 및 반대 변경을 새 커밋으로 기록하는 일은 서로 다르다. restore는 주로 경로의 내용을 다루고 reset은 모드에 따라 참조와 Index 및 작업 트리를 바꾸며 revert는 기존 변경을 상쇄하는 새 커밋을 만든다. 명령 이름보다 무엇이 바뀌는지 먼저 판단해야 한다. [T04]

reset --soft는 참조를 이동시키면서 Index와 작업 트리를 유지한다. 기본 mixed 모드는 Index도 목표 상태로 맞춘다. hard 모드는 작업 트리까지 바꾸므로 보존하지 않은 변경을 잃을 수 있다. 경로를 지정한 reset은 커밋을 이동시키는 형태와 동작이 다르다. 이 구분을 무시하고 모든 reset을 같은 복구 명령으로 이해하면 위험하다.

공유된 이력의 문제라면 revert가 협업에 유리할 수 있다. 과거 커밋을 지우지 않고 반대 변경을 기록하기 때문이다. 그러나 merge commit을 revert할 때는 주 부모를 선택하는 의미와 이후 재병합의 영향까지 이해해야 한다. 단순한 파일 복구와 같은 수준의 명령으로 취급하지 않는다.

reflog는 중요한 단서지만 영구 백업은 아니다

reflog는 로컬 참조가 이동한 기록이다. 잘못된 reset 뒤 이전 커밋을 찾거나 detached HEAD에서 만든 커밋을 다시 이름 붙이는 데 도움이 된다. 기록은 저장소와 설정 및 보존 기간에 영향을 받으며 다른 사람의 서버 이력을 완전하게 대신하지 않는다. 참조되지 않는 객체는 정리될 수 있으므로 발견한 커밋은 필요한 브랜치나 태그로 보존한다. [T05]

복구 전에는 현재 상태를 먼저 기록한다. 작업 파일과 Index 및 커밋된 이력이 어디까지 보존되어 있는지 확인한다. 무시된 파일과 추적되지 않는 파일은 별도 사본이 필요할 수 있다. 문제를 고치려는 명령이 추가로 정보를 없애지 않도록 하는 것이 복구의 첫 원칙이다.

저장할 자료의 성격에 맞는 도구를 선택한다

Git은 텍스트 차이를 검토하는 데 강점이 있다. 대형 바이너리 파일은 작은 수정에도 큰 데이터가 추가될 수 있고 사람이 차이를 읽기 어렵다. LFS는 큰 파일 내용을 별도 저장소에 두고 Git에는 포인터를 저장하는 방식이다. 일반 Git 이력만 복사했다고 LFS 실제 객체까지 모두 백업된다고 가정하지 않는다.

줄바꿈과 인코딩은 내용이 같아 보여도 큰 차이를 만들 수 있다. .gitattributes로 저장소 차원의 정책을 남기면 개인 설정 차이로 발생하는 불필요한 변경을 줄일 수 있다. 정책을 바꿀 때 기존 파일 전체가 재정규화될 수 있으므로 기능 수정과 분리해 검토한다. 차이를 읽기 쉽게 만드는 것은 협업 비용을 줄이는 설계다.

파일이 안 보이는 것과 객체가 없는 것은 다르다

브랜치 이름을 삭제해도 그 이름이 가리키던 객체가 즉시 사라진다고 단정할 수 없다. 다른 참조가 도달하거나 reflog 등 보존 단서가 남아 있을 수 있다. 반대로 시간이 지나 정리 작업의 대상이 되면 복구에 사용할 객체가 없어질 수 있다. 현재 작업 트리에 없다는 사실과 객체 저장소에 없다는 사실을 나누어 생각한다. [T39]

복구할 가능성이 있는 커밋을 찾았다면 내용을 확인한 뒤 보존할 참조를 만드는 방법을 검토한다. 객체 식별자를 메모에만 적는 것과 저장소가 그 객체에 도달할 수 있는 참조를 유지하는 것은 다르다. 중요한 작업을 임시 기록의 우연한 보존에 의존시키지 않는다.

Git이 추적하지 않은 새 파일은 커밋 이력에서 복원할 수 없다. stash를 사용했더라도 어떤 범위가 포함되었는지 확인해야 한다. 복구 명령을 고르기 전에는 손실 대상이 커밋된 파일인지 미커밋 수정인지 추적되지 않은 자료인지부터 분류한다. 같은 실수처럼 보여도 복구 근거는 다르다.

정리 작업과 증거 보존의 목적을 혼동하지 않는다

저장소가 커졌다는 이유로 정리 명령을 반복하기 전에 조사 중인 객체가 있는지 확인한다. 저장 공간을 줄이는 목적과 과거 상태를 복원하는 목적은 충돌할 수 있다. 사고 조사 중에는 별도 사본을 확보하고 필요한 객체와 참조를 먼저 확인하는 편이 안전하다.

git fsck 같은 무결성 검사는 객체와 연결의 문제를 조사하는 데 도움이 된다. 그러나 저장소 구조가 정상이라는 결과는 소스의 기능이 정상이라는 뜻이 아니다. 데이터 구조의 건강과 프로그램의 정확성은 다른 검사 범위다. 보고서에서도 어떤 층을 확인했는지 적어야 결과를 과장하지 않게 된다.

git status
git log -5 --oneline
git branch backup/before-revert
git revert HEAD
git log -3 --oneline
git show HEAD

git reflog --date=local
git show CANDIDATE-ID
git branch rescue/found CANDIDATE-ID

# .gitignore
.env
.env.*
!.env.example
node_modules/
dist/
*.log
.DS_Store

git ls-files .env
git check-ignore -v .env

git check-ignore -v .env
git ls-files .env

# .gitattributes
* text=auto
*.sh text eol=lf
*.yml text eol=lf
*.png binary
*.pdf binary

git lfs install
git lfs track '*.psd'
git add .gitattributes
git lfs ls-files

git log --graph --oneline --decorate --all
git log -p -- README.md
git show HEAD

git log --graph --oneline --decorate --all -20
git log -p -- README.md
git blame README.md
git show HEAD:README.md
git cat-file -t HEAD
git cat-file -p HEAD

git switch --detach HEAD~1
# 과거 파일을 읽는다
git switch -c experiment/from-past
# 또는 원래 브랜치로 돌아간다
# git switch main

7장 이슈 설계와 코드 리뷰

관찰 가능한 완료 조건을 정하고 재현 정보를 양식으로 받는다. 요구와 구현과 검증 근거를 연결해 PR을 검토한다.

좋은 이슈는 원인 단정보다 재현 조건을 제공한다

이슈의 목적은 작성자의 확신을 전달하는 것이 아니라 다른 사람이 같은 문제를 관찰할 수 있게 하는 것이다. 실행 환경과 입력 및 기대 결과와 실제 결과를 분리한다. 원인에 대한 추측은 별도로 적는다. 검색 라이브러리가 잘못되었다는 제목보다 과목을 바꾼 뒤 결과 수가 갱신되지 않는다는 설명이 조사에 더 직접적일 수 있다.

Issue Forms는 필요한 정보의 누락을 줄이는 장치다. 모든 항목을 필수로 만들면 보고 비용이 커져 사용자가 문제를 남기지 않을 수 있다. 재현에 꼭 필요한 정보와 선택적인 진단 자료를 구분한다. 비밀과 개인정보가 포함된 로그를 올리지 않도록 안내하는 것도 양식 설계의 일부다.

리뷰의 목적에는 이해와 대안 탐색이 포함된다

Bacchelli와 Bird의 연구는 Microsoft의 여러 팀을 관찰하고 인터뷰 및 설문과 리뷰 댓글 분석을 수행했다. 연구는 결함 탐지 외에도 지식 전달과 팀의 상황 이해 및 대안 탐색이 리뷰의 중요한 결과임을 설명한다. 이는 특정 조직의 경험적 연구이며 모든 리뷰 절차의 효과를 동일하게 보장하지는 않는다. [S13]

lesson-lab의 필터 PR에서 검토자는 조건식의 오류뿐 아니라 과목 이름이 어디에서 정의되는지와 새 과목을 추가할 때 무엇을 바꿔야 하는지도 물을 수 있다. 이런 질문은 작성자를 평가하기 위한 심문이 아니라 유지보수에 필요한 지식을 공유하는 과정이다. 설명이 코드와 다르면 둘 중 어느 쪽을 수정해야 하는지 함께 판단한다.

리뷰 댓글은 결함과 제안 및 질문을 구분하면 처리하기 쉽다. 반드시 수정해야 하는 동작 오류와 개인적인 표현 선호를 같은 강도로 전달하면 우선순위가 흐려진다. 근거와 영향을 설명하고 가능한 대안을 제시한다. 작성자는 수정 여부뿐 아니라 수용하지 않은 이유도 기록해 다음 검토자가 같은 논의를 반복하지 않게 한다.

리뷰 단위는 사람이 이해할 수 있는 변화다

PR 크기는 파일 수나 줄 수만으로 판단하기 어렵다. 자동 생성 파일 수천 줄보다 권한 조건 한 줄이 더 위험할 수 있다. 변경의 목적 수와 의존성 및 검증 난이도를 함께 본다. 여러 목적이 섞인 PR은 분리하고 하나의 목적을 구현하는 데 필요한 변경은 함께 보여 준다.

검토가 끝난 뒤 새로운 커밋이 추가되면 이전 승인과 현재 코드 사이의 관계를 확인해야 한다. 필수 검사와 승인 무효화 정책은 이 문제를 도구로 보완한다. 그러나 설정이 있다는 이유만으로 리뷰 내용의 질이 보장되지는 않는다. 정책은 사람이 판단할 시점을 제공하고 실제 판단은 변화의 의미를 읽는 과정에서 이루어진다.

변경 줄 수와 검토 난이도는 비례하지 않는다

설정 한 줄이 운영 계정의 권한을 확대할 수 있고 수백 줄의 생성 파일 변경은 원본 규칙 한 개에서 비롯될 수 있다. 변경량은 검토의 입력이지만 위험의 직접적인 척도는 아니다. 외부 입력과 권한 및 데이터 형식과 동시성 경계를 건드리는지 함께 살핀다.

검토 자원을 배정할 때 변경의 되돌림 가능성도 고려한다. 정적 문구는 이전 파일로 되돌리기 쉽지만 데이터 마이그레이션은 소스만 되돌려 해결되지 않을 수 있다. 같은 규모의 PR이라도 실패가 지속되는 방식에 따라 필요한 증거가 달라진다. 위험도에 비례해 검토 깊이를 정하면 모든 변경에 같은 긴 목록을 적용하는 것보다 실용적이다.

리뷰어가 코드를 읽는 순서도 중요하다. 목적과 제약 및 검사 결과를 먼저 이해한 뒤 구현을 읽으면 요구와 무관한 세부에 시간을 덜 쓸 수 있다. 작성자는 변경 이유와 대안 및 남은 한계를 짧게 제공한다. 설명이 구현과 어긋나는 경우에는 설명의 자연스러움보다 실제 diff와 실행 결과를 우선한다.

댓글이 해결되었다는 상태와 문제 해결을 구분한다

검토 대화의 해결 표시는 논의의 상태다. 제기한 문제가 수정되었거나 합의된 대안으로 처리되었다는 증거를 함께 봐야 한다. 권한 거부 시험을 요청한 댓글이 닫혔는데 실제 시험 기록이 없다면 검토의 목적은 충족되지 않았다. 화면의 완료 상태가 판단을 대신하지 않게 한다.

리뷰 대기 시간을 줄이려면 재촉만 하기보다 변경의 크기와 담당 범위 및 필요한 전문성을 조정한다. 요청판의 권한 변경을 화면 배치 수정과 함께 묶으면 적절한 리뷰어를 찾기 어렵다. 하나의 목적과 하나의 검증 질문에 집중된 변경은 검토자의 인지 부담을 줄인다.

팀의 성과를 리뷰 댓글 수로 평가하면 불필요한 지적이 늘 수 있다. 반대로 댓글이 적다는 이유로 검토가 부실했다고 단정할 수도 없다. 리뷰 후 재작업과 결함 및 이해의 전달을 함께 본다. 숫자는 활동의 흔적이며 그 활동이 해결한 문제를 대신하지 않는다.

검토는 특정 변경과 검사 결과를 연결한다

GIF 재생이전 상태다음 상태

마지막 상태

1. 초안을 열어 변경 목적을 설명한다
2. 코드 차이와 검사 결과를 함께 본다
3. 새 커밋이 추가되면 검토 대상이 바뀐다
4. 현재 커밋에 대한 조건 충족을 확인한다
5. 병합 방식에 따른 기준 브랜치 결과를 확인한다

## 상황
휴대전화에서 정답 버튼을 찾기 어렵다.

## 기대 결과
작은 화면에서도 답 확인 동작이 드러난다.

## 완료 조건
- 360px 너비에서 버튼이 보인다.
- 키보드로 버튼에 접근할 수 있다.
- 정답을 열어도 풀이 영역이 잘리지 않는다.

# .github/ISSUE_TEMPLATE/bug.yml
name: 오류 보고
description: 재현할 수 있는 오류를 알려 주세요.
title: '[오류] '
body:
  - type: input
    id: environment
    attributes:
      label: 실행 환경
      description: 운영체제와 브라우저 버전을 적어 주세요.
    validations:
      required: true
  - type: textarea
    id: reproduce
    attributes:
      label: 재현 절차
      description: 한 단계씩 적어 주세요.
    validations:
      required: true

  - type: textarea
    id: expected
    attributes:
      label: 기대 결과와 실제 결과
    validations:
      required: true
  - type: checkboxes
    id: privacy
    attributes:
      label: 공개 전 확인
      options:
        - label: 비밀 키와 개인정보를 넣지 않았습니다.
          required: true

## 문제와 결과
작은 화면에서 정답 버튼을 찾기 어려웠다.
버튼을 문제 바로 아래 배치했다.

## 검증
- 360px와 1280px 화면에서 확인했다.
- Tab과 Enter로 열 수 있었다.
- 정답을 두 번 열고 닫아도 내용이 유지됐다.

## 관련 작업
Closes #12

8장 오픈소스 기여와 팀 권한

Fork의 원본과 내 작업을 구분하고 조직의 역할을 설계한다. Rulesets와 CODEOWNERS가 실제 검토 흐름에서 작동하는지 시험한다.

Fork는 별도 저장소이며 권한도 별도로 존재한다

Fork는 원본과 관계를 가진 다른 저장소다. 로컬 Clone은 저장소를 내 컴퓨터로 가져오는 행동이다. 두 개념을 혼동하면 어느 원격에 Push할지와 어느 저장소에서 PR을 만들지 헷갈리기 쉽다. 자신의 Fork를 origin으로 두고 원본을 upstream으로 추가하는 관례는 이름을 통해 역할을 구분하는 방법이다. 이름 자체가 권한을 부여하지는 않는다.

오픈소스 기여에서는 코드를 작성하기 전에 프로젝트의 기여 지침과 이슈 상태를 읽는다. 유지관리자가 원하지 않는 큰 변경을 먼저 완성하면 서로의 검토 비용이 커진다. 작은 문제의 범위와 수용 조건을 합의한 뒤 변경을 제안하는 과정은 기술적 능력만큼 중요하다.

권한은 사람과 자원 및 행동의 관계다

조직의 팀은 사람을 묶는 단위이며 저장소 역할은 허용된 행동의 범위를 정한다. CODEOWNERS는 특정 경로의 검토 책임자를 표현한다. 그러나 소유자 파일이 있다는 사실만으로 필수 승인이 자동으로 강제되는 것은 아니다. 적용되는 브랜치 정책과 승인 요구를 함께 확인해야 한다.

Ruleset은 어떤 참조에 어떤 조건을 적용할지 정하는 정책이다. 적용 대상과 예외 및 우회 권한이 함께 중요하다. 규칙의 이름이 엄격하더라도 실제 기본 브랜치가 대상에서 빠져 있으면 기대한 통제가 작동하지 않는다. 관리자가 우회할 수 있는 경로와 서비스 계정의 권한도 검토 범위에 포함한다.

최소 권한은 사람을 믿지 않는다는 선언이 아니다. 계정 탈취와 실수 및 자동화 오류가 발생했을 때 영향을 제한하는 구조다. 검토만 하는 사람에게 관리 권한까지 줄 필요는 없다. 자동화는 필요한 저장소와 작업 및 유효 기간에 맞는 자격 증명을 사용한다.

운영 규칙은 도구 설정과 문서가 일치해야 한다

문서에는 두 명의 승인이 필요하다고 적었지만 실제 규칙은 한 명만 요구한다면 팀의 계약이 두 개로 갈라진다. 반대로 도구가 필수 검사를 요구하는데 해당 검사가 더 이상 실행되지 않으면 병합이 막힐 수 있다. 정책 변경에는 문서와 설정 및 테스트 PR을 함께 검토한다.

거버넌스는 작은 팀에도 필요하다. 누가 릴리스를 결정하고 누가 비밀을 교체하며 누가 장애 때 연락받는지 정한다. 모든 권한을 한 사람에게 모으면 평소에는 편리할 수 있지만 부재와 계정 문제에 취약해진다. 역할의 분리와 대체 경로를 프로젝트 규모에 맞게 설계한다.

정책이 있다고 해서 모든 경로에 적용되는 것은 아니다

브랜치 정책은 대상 패턴과 실행 주체 및 예외 설정에 따라 효력이 달라진다. main에 적용한 규칙이 release 브랜치에도 적용되는지와 관리자나 자동화 계정이 우회할 수 있는지를 확인해야 한다. 조직의 ruleset과 저장소의 규칙이 함께 작동할 때도 실제 적용 범위를 살핀다. 정책 문서의 표현과 서비스의 설정을 대조하는 작업이 필요하다. [T40]

규칙을 강화한 뒤 정상 작업이 막힌다고 모든 예외를 열어 주면 정책의 목적이 사라진다. 막힌 경로가 설계된 예외인지 기존 자동화의 잘못된 가정인지 구분한다. 배포 봇이 직접 main에 쓰는 관행을 바꾸어 PR과 검사 경로로 이동하는 것이 더 적절할 수 있다. 예외는 문제를 해결하는 여러 선택지 중 하나다.

긴급 변경도 사후 재현이 가능해야 한다

장애를 복구하기 위해 긴급 권한이 필요할 수 있다. 이 경우 권한을 받은 사람과 대상 변경 및 사용 기간과 결과를 남긴다. 긴급 상황이 끝났는데 예외가 영구적으로 유지되면 이후의 위험이 커진다. 비상 경로는 평상시의 편의 경로와 구분해 관리한다.

이 원칙은 사람을 불신하기 위한 장치가 아니다. 당시의 제한된 정보와 시간 압박 속에서 내린 결정을 나중에 이해할 수 있게 한다. 복구가 끝난 뒤 정상 검사 경로에 해당 변경을 반영하고 누락된 검증을 수행한다. 긴급 조치의 성공과 정상 운영 상태의 회복은 별도의 완료 조건이다.

git clone https://github.com/YOUR-ID/PROJECT.git
cd PROJECT
git remote add upstream https://github.com/ORIGINAL-OWNER/PROJECT.git
git remote -v
git fetch upstream
git switch main
git merge --ff-only upstream/main
git push origin main
git switch -c docs/fix-start-guide

# .github/CODEOWNERS
* @YOUR-ID
/docs/ @YOUR-ORG/content-team
/.github/ @YOUR-ORG/maintainers

* @YOUR-ID
/docs/ @YOUR-ORG/content-team
/.github/ @YOUR-ORG/maintainers

## 문제와 결과

## 확인한 내용
- [ ] 바뀐 기능을 직접 실행했다.
- [ ] 필요한 문서를 수정했다.
- [ ] 비밀과 개인정보가 없는지 확인했다.

## 검증 방법과 결과

## 관련 Issue

## 배포 시 확인할 점

9장 큰 저장소와 병합 운영

저장소 구조와 체크아웃 범위를 목적에 맞게 선택한다. 병합 전략과 Merge queue로 여러 변경이 합쳐질 때의 검증을 관리한다.

큰 저장소의 비용은 파일 크기 하나로 설명되지 않는다

저장소의 무게에는 객체 수와 이력 길이 및 큰 파일과 참조 수가 영향을 준다. Clone 속도와 작업 트리 크기 및 검색 시간은 서로 다른 비용이다. shallow clone은 이력의 깊이를 줄이고 partial clone은 필요한 객체의 전송을 지연하며 sparse checkout은 작업 트리에 펼칠 경로를 제한한다. 이 기법들은 같은 문제를 해결하지 않는다.

lesson-lab이 여러 수업 도구를 포함하는 Monorepo로 커졌다고 하자. 한 팀은 공통 라이브러리 변경을 한 번에 검토하기 쉬워질 수 있지만 작은 앱 하나를 수정할 때도 큰 CI가 실행될 수 있다. 저장소 통합의 이익과 빌드 및 권한과 소유권의 비용을 함께 평가한다. 폴더를 합치는 것만으로 의존성 관리가 해결되지는 않는다.

Submodule은 다른 저장소의 특정 커밋을 상위 저장소에서 참조하는 방식이다. 하위 프로젝트의 최신 브랜치를 자동으로 따라간다고 생각하면 재현성이 깨진다. 상위 커밋이 가리키는 하위 커밋을 명시적으로 확인하고 초기화와 갱신 절차를 문서화한다. 별도 권한과 외부 저장소의 가용성도 의존성의 일부다.

병합 대기열은 조합의 검증 문제를 다룬다

PR A와 PR B가 각각 현재 main에서 통과해도 둘을 함께 넣은 결과가 통과한다는 보장은 없다. A가 라이브러리를 갱신하고 B가 이전 동작을 전제로 코드를 추가할 수 있기 때문이다. 병합 대기열은 기준 브랜치와 대기 중인 변경을 조합해 검사하는 절차를 제공한다. 필요한 워크플로가 대기열의 이벤트에서도 실행되는지 확인해야 한다.

통합 비용을 줄이려면 대기 시간을 관찰한다. 개발이 끝난 뒤 검토를 기다리는 시간과 CI 대기 및 재작업 시간을 구분한다. 커밋 작성 속도가 빨라져도 검토 병목이 그대로라면 전체 전달 시간은 줄지 않을 수 있다. 병렬 작업을 늘리는 결정은 통합 능력과 함께 평가해야 한다.

장기 브랜치는 큰 변경을 격리할 수 있지만 기준 브랜치와의 차이가 누적된다. 짧은 브랜치와 기능 플래그는 통합을 자주 하면서 공개 시점을 조절하는 다른 전략이다. 어떤 전략이 적합한지는 배포 구조와 테스트 수준 및 팀의 운영 능력에 달려 있다. 전략의 이름보다 통합 실패를 어떻게 발견하고 복구할지 설명할 수 있어야 한다.

이력과 객체와 작업 트리는 서로 다른 축이다

shallow clone은 가져오는 커밋 이력의 깊이를 제한한다. partial clone은 필요한 객체 일부를 나중에 가져오도록 제한할 수 있다. sparse checkout은 작업 트리에 펼칠 경로를 줄인다. 세 기능은 줄이는 대상이 다르므로 같은 최적화로 취급하지 않는다. blob:none 필터를 사용해도 checkout에 필요한 파일 내용은 결국 내려받을 수 있다. [T22]

문서 사이트만 수정하는 작업과 과거 결함을 bisect로 조사하는 작업은 필요한 자료가 다르다. 전자는 일부 경로만 펼쳐도 충분할 수 있지만 후자는 긴 이력이 필요하다. 저장소를 작게 만드는 방법은 작업 목적에서 선택해야 한다. 처음의 다운로드 속도만으로 모든 상황에 같은 옵션을 적용하지 않는다.

최적화의 비용이 뒤로 이동할 수 있다

partial clone의 초기 다운로드가 빠르더라도 과거 파일을 자주 읽으면 이후 요청이 늘 수 있다. 오프라인 조사가 필요한 사람에게는 필요한 객체를 미리 확보하는 과정이 중요하다. 지금 사용하지 않는 자료를 나중에 가져오는 설계는 자료가 필요할 때 서버에 접근할 수 있다는 전제를 가진다.

CI의 짧은 작업에서는 제한된 이력이 합리적일 수 있다. 그러나 릴리스 버전을 태그에서 계산하거나 변경된 경로를 공통 조상과 비교한다면 부족한 이력이 잘못된 결과를 만들 수 있다. 실패하면 무조건 전체 clone으로 바꾸기보다 어떤 계산이 어떤 정보에 의존하는지 확인한다. 필요한 범위를 정확히 가져오면 속도와 정확성을 함께 관리할 수 있다.

관련 근거 [T10]

git clone --filter=blob:none --sparse https://github.com/YOUR-ID/lesson-lab.git lesson-sparse
cd lesson-sparse
git sparse-checkout set docs .github
git sparse-checkout list
git log -5 --oneline

git clone --recurse-submodules https://github.com/OWNER/PARENT.git
# 이미 Clone했다면
git submodule update --init --recursive
git submodule status

on:
  pull_request:
  push:
    branches: [main]
  merge_group:
    types: [checks_requested]

10장 웹 공개와 릴리스 관리

Pages의 경로와 배포 결과를 확인한다. 배포 Workflow를 구성하고 태그와 Release와 실행 중인 판본을 연결한다.

같은 판본이라는 말을 검증할 수 있어야 한다

커밋은 소스 상태를 식별한다. 태그는 특정 객체에 붙이는 이름이다. Release는 사용자에게 배포판을 설명하고 파일을 제공하는 GitHub의 객체다. Deployment는 실제 실행 환경에 결과를 배치한 기록이나 과정이다. 이들을 모두 버전이라고 부르면 어떤 대상을 비교하는지 모호해진다.

lesson-lab의 v1.0.0 태그가 커밋 A를 가리킨다고 하자. 그 소스로 만든 배포 파일과 현재 Pages 사이트가 반드시 같은 판본인지는 별도로 확인해야 한다. 태그 이름을 이동시키거나 빌드 설정이 달라지면 이름은 같아도 결과가 달라질 수 있다. 릴리스 정책에서는 공개한 이름의 변경 가능성과 아티팩트의 식별 방법을 명확히 한다.

배포 메타데이터에 소스 커밋과 빌드 실행 번호를 남기면 장애 때 현재 결과의 출처를 찾기 쉽다. 사용자가 보고한 화면이 어느 판본인지 모르면 이미 수정된 오류를 다시 조사하거나 다른 환경을 비교할 수 있다. 출처 기록은 대규모 서비스만의 관행이 아니라 작은 정적 사이트에도 유용하다.

정적 호스팅의 경계를 이해한다

GitHub Pages는 정적 사이트를 게시하는 용도로 사용한다. 브라우저에 전달된 JavaScript와 설정 값은 사용자가 읽을 수 있다. 따라서 비밀 API 키를 숨겨 두는 서버 역할로 사용해서는 안 된다. 클라이언트에서 외부 API를 부를 때는 공개해도 되는 정보와 서버를 거쳐야 하는 정보를 구분한다.

프로젝트 사이트의 경로 접두사는 자원 경로 문제를 만들 수 있다. 로컬에서는 /style.css가 작동하더라도 저장소 이름이 포함된 하위 경로에 배포하면 다른 위치를 가리킬 수 있다. 상대 경로와 빌드의 base 설정을 확인하고 실제 배포 주소에서 링크와 새로고침을 검사한다. 로컬 성공을 배포 성공으로 곧바로 해석하지 않는다.

롤백은 이전 결과를 다시 제공하는 절차다. 정적 사이트에서는 비교적 단순해 보이지만 외부 API 계약과 저장된 브라우저 데이터가 바뀌었다면 이전 코드와 호환되지 않을 수 있다. 소스만 되돌리는 절차와 사용자 데이터의 호환성을 함께 검토한다.

재빌드와 재현 가능한 빌드는 다른 수준이다

소스를 다시 실행해 비슷한 결과를 얻는 것과 같은 입력 조건에서 같은 바이트를 생성하는 것은 다르다. reproducible build는 명시된 소스와 환경 및 절차를 바탕으로 결과를 재현하는 관점에서 다뤄진다. 빌드 시각과 파일 순서 및 무작위 값이 산출물에 들어가면 코드가 같아도 해시가 달라질 수 있다. [T42]

교육용 PDF를 빌드한다고 하자. 내용이 같아도 메타데이터의 생성 시각이나 글꼴 버전이 달라지면 파일 바이트가 달라질 수 있다. 기능적으로 같은 결과인지와 바이트가 같은 결과인지 평가 목적을 먼저 정한다. 배포한 파일을 정확히 식별하려면 실제 산출물의 해시와 소스 커밋을 함께 기록한다.

소스 커밋만으로 배포 결과를 모두 설명할 수 없는 경우도 있다. 빌드 환경의 설정과 외부 자료 및 의존성 버전이 결과를 바꿀 수 있기 때문이다. 릴리스 기록에는 이 입력들을 연결한다. 어떤 파일을 배포했는지 모르면 소스가 정상이어도 사용자가 받은 결과를 조사하기 어렵다.

배포와 공개를 나누면 되돌림의 범위가 보인다

새 파일을 서버에 올리는 배포와 사용자에게 기능을 노출하는 공개는 분리할 수 있다. 예를 들어 새 검색 계산을 배포해도 일부 사용자에게만 활성화할 수 있다. 문제가 생겼을 때 기능 노출을 끄는 방식은 파일 전체를 다시 배포하는 방식과 다른 복구 경로다. 어느 방법이 필요한지는 변경의 성격과 운영 구조에 달려 있다.

데이터 형식을 함께 바꾼 배포에서는 이전 코드가 새 자료를 읽을 수 있는지 확인한다. 코드만 이전 판본으로 되돌리면 오히려 실패할 수 있다. 릴리스의 단위가 소스와 설정 및 자료 중 어디까지 포함되는지 정해야 한다. 되돌릴 수 있다는 주장은 실제로 호환되는 상태로 돌아갈 수 있을 때 성립한다.

<!doctype html>
<html lang='ko'>
<meta charset='utf-8'>
<meta name='viewport' content='width=device-width'>
<title>수업 실험실</title>
<h1>수업 실험실</h1>
<p>GitHub Pages 배포 연습</p>
<button id='answer'>정답 보기</button>
<p id='result' hidden>연습 정답은 42다.</p>
<script>
document.getElementById('answer').onclick = () => {
  document.getElementById('result').hidden = false;
};
</script>
</html>

# .github/workflows/pages.yml의 앞부분
name: Publish lesson page
on:
  push:
    branches: [main]
  workflow_dispatch:
permissions:
  contents: read
concurrency:
  group: lesson-pages
  cancel-in-progress: false
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: |
          mkdir -p _site
          cp index.html _site/index.html
      - uses: actions/upload-pages-artifact@v4
        with:
          path: _site

  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4

git status
git log -1 --oneline
git show --no-patch v0.1.0

git switch main
git pull --ff-only
git status
git tag -a v0.1.0 -m 'First learning release'
git push origin v0.1.0

gh release create v0.1.0 --verify-tag --title '첫 연습 배포판' --notes-file RELEASE_NOTES.md

11장 클라우드 개발과 컨테이너 활용

브라우저 편집과 실행 환경의 차이를 이해하고 AI의 변경을 검토한다. 컨테이너 이미지와 패키지 공개를 실제 실행 환경과 연결한다.

편집 환경과 실행 환경을 구분한다

github.dev는 브라우저에서 저장소를 편집하는 경험을 제공하지만 완전한 원격 실행 환경과 동일하지 않다. Codespaces는 실행 자원과 개발 환경을 제공한다. 어느 도구에서 코드를 읽고 어느 환경에서 테스트를 실행했는지 구분해야 한다. 파일이 열렸다는 사실은 의존성 설치와 실행 검증이 끝났다는 뜻이 아니다.

개발 컨테이너 설정은 팀이 필요한 도구와 환경을 문서화하는 방법이다. 같은 설정을 사용하면 초기 준비의 차이를 줄일 수 있다. 그러나 외부 서비스와 비밀 및 하드웨어와 네트워크까지 동일하게 만드는 것은 아니다. 환경을 코드로 표현하는 목적은 재현성을 높이고 차이를 설명하기 쉽게 하는 데 있다.

컨테이너 이미지의 태그와 다이제스트를 구분한다

태그는 읽기 쉬운 이름이며 갱신될 수 있다. 다이제스트는 이미지 내용의 식별에 사용된다. latest라는 태그만 기록하면 나중에 같은 이름이 다른 이미지를 가리킬 수 있다. 배포와 조사에서 정확한 결과를 재현하려면 사용한 이미지의 식별자를 남긴다.

이미지 안에 비밀을 넣으면 나중에 파일을 삭제하는 단계가 있어도 이전 레이어에 남을 수 있다. 빌드 입력과 런타임 비밀을 분리하고 필요한 자격 증명을 제한된 방식으로 전달한다. 공개 저장소에 올리지 않았다는 사실만으로 이미지와 빌드 로그까지 안전하다고 판단하지 않는다.

AI 코딩 도구를 개발 환경에 연결할 때도 권한 경계를 확인한다. 읽기 권한과 파일 수정 및 명령 실행과 외부 전송은 서로 다른 능력이다. 저장소의 지시 문서와 검증 명령을 제공하되 외부 문서에 포함된 지시를 프로젝트 소유자의 승인처럼 해석하지 않도록 한다. 도구의 편의성과 실행 범위는 함께 설계해야 한다.

환경 선언은 실행될 프로그램의 일부다

개발 컨테이너 설정에는 이미지와 도구 및 생성 후 실행 명령 등이 포함될 수 있다. 저장소를 열 때 자동으로 수행되는 작업은 편리하지만 그 자체가 실행 코드다. 신뢰하지 않는 저장소에서 환경을 준비할 때는 설정 파일의 명령과 마운트 및 외부 네트워크 사용을 검토한다. 환경 파일은 단순한 설명문으로 취급할 수 없다. [T41]

컨테이너 안에서 실행한다는 사실만으로 호스트와 완전히 분리되었다고 가정하지 않는다. 작업 폴더와 자격 증명 및 소켓을 어떤 방식으로 연결했는지에 따라 접근 범위가 달라진다. 편의를 위해 넓은 마운트를 제공했다면 그 선택의 영향을 알아야 한다. 환경의 재현성과 실행의 격리는 서로 다른 품질 속성이다.

새 팀원이 환경을 열 수 있게 하려면 비밀 없이 재현되는 부분과 별도 발급이 필요한 부분을 구분한다. 개인의 인증 파일을 이미지에 넣으면 빠르게 시작할 수 있어 보여도 소유권과 만료 및 유출 대응이 어려워진다. 공통 도구는 선언하고 개인 권한은 실행 시점의 승인된 경로로 연결하는 편이 관리하기 쉽다.

잠금 파일은 공급망 전체의 스냅샷이 아니다

패키지 잠금 파일은 의존성 해결 결과를 고정하는 데 도움이 된다. 그러나 설치 스크립트가 외부 자료를 받거나 시스템 패키지가 바뀌거나 기본 이미지가 이동하면 결과가 달라질 수 있다. 어느 층을 고정했는지 확인해야 재현 실패의 원인을 좁힐 수 있다.

문제가 생기면 소스 변경과 잠금 파일 및 이미지 다이제스트와 실행 로그를 함께 비교한다. 한 층의 버전만 확인하고 동일한 환경이라고 결론 내리지 않는다. 완벽한 고정을 무조건 추구하기보다 현재 프로젝트에서 중요한 재현 수준과 갱신 주기를 정한다. 보안 수정과 재현성 사이의 운영 정책도 필요하다.

목표
index.html의 정답 버튼을 키보드로 사용할 수 있게 해라.

범위
정답 열기와 닫기 동작과 접근성 이름을 확인해라.
데이터 수집 기능은 추가하지 마라.

완료 조건
Tab으로 버튼에 도달한다.
Enter와 Space로 동작한다.
360px 화면에서 내용이 잘리지 않는다.

제출 내용
변경 이유와 diff와 실제 검증 결과를 제시해라.
실행하지 못한 검사는 그렇게 표시해라.

# Dockerfile
FROM python:3.13-slim
WORKDIR /app
COPY index.html /app/index.html
USER 10001
EXPOSE 8080
CMD ["python", "-m", "http.server", "8080", "--bind", "0.0.0.0"]

docker build -t lesson-page:local .
docker run --rm -p 127.0.0.1:8080:8080 lesson-page:local

# .github/workflows/container.yml
name: Publish container
on:
  push:
    branches: [main]
permissions:
  contents: read
  packages: write
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Build and publish
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          image="ghcr.io/${GITHUB_REPOSITORY,,}"
          printf '%s' "$GH_TOKEN" | docker login ghcr.io \
            -u "$GITHUB_ACTOR" --password-stdin
          docker build -t "$image:$GITHUB_SHA" .
          docker push "$image:$GITHUB_SHA"

12장 자동 검사와 재사용 Workflow

첫 검사를 구성하고 실행 로그에서 실패 지점을 찾는다. Matrix와 결과물 보관을 익힌 뒤 공통 검사를 재사용 Workflow로 분리한다.

자동 실행과 지속적 통합은 같은 말이 아니다

자동화는 반복 작업을 도구가 수행하는 것이다. 지속적 통합은 변경을 공유 기준에 자주 통합하고 통합 결과를 검사하는 개발 관행이다. 매주 한 번 실행되는 긴 워크플로도 자동화지만 짧은 피드백을 제공하는 통합 과정과는 다를 수 있다. CI의 가치는 YAML 파일의 존재보다 실패를 발견하는 시점과 대응 방식에 있다.

Vasilescu 등의 연구는 GitHub에서 기여 방식과 프로젝트 특성이 자동 빌드 성공과 어떤 관련을 갖는지 분석했다. 인용한 자료는 수정 사항을 반영한 2015년 판본이다. 관찰된 관련성을 CI 도입의 보편적인 인과 효과로 확대하지 않고 개발 맥락을 고려해야 한다는 근거로 읽는다. [S15]

lesson-lab의 CI는 먼저 설치와 정적 검사 및 핵심 테스트를 실행할 수 있다. 검사마다 무엇을 확인하는지 문서화한다. 린터는 일부 코드 규칙을 확인하지만 업무 요구의 정확성을 증명하지 않는다. 테스트도 작성한 사례의 범위를 넘어서 모든 입력에 대한 보증을 제공하지 않는다.

실행 그래프와 실패 의미를 설계한다

워크플로의 job은 의존 관계를 통해 실행 그래프를 이룬다. 독립적인 검사는 병렬로 실행할 수 있지만 배포는 필요한 검사 결과를 기다려야 한다. 순서를 무조건 직렬로 만들면 피드백이 느려지고 필요한 의존성을 빼면 검증되지 않은 결과가 배포될 수 있다.

Matrix는 여러 런타임과 운영체제 조합을 검사하는 도구다. 조합이 늘수록 비용과 대기 시간이 증가한다. 실제 지원 범위와 실패 가능성이 높은 경계를 기준으로 조합을 선택한다. 모든 가능한 조합을 실행하는 것과 필요한 위험을 충분히 확인하는 것은 다른 목표다.

캐시는 다시 만들 수 있는 자료의 재사용에 적합하다. 아티팩트는 특정 실행의 결과를 전달하고 보관하는 데 사용한다. 캐시를 배포 결과의 유일한 근거로 삼으면 오래된 자료와 키 충돌 때문에 재현성이 약해질 수 있다. 무엇을 재사용하고 무엇을 판본별로 보관할지 구분한다.

재사용은 계약을 만드는 일이다

재사용 워크플로는 입력과 출력 및 필요한 권한을 공개 인터페이스처럼 다룬다. 호출하는 저장소가 어떤 파일과 비밀을 제공해야 하는지 명확히 한다. 공통 워크플로를 바꾸면 여러 프로젝트가 영향을 받을 수 있으므로 변경 이력과 호환성 정책이 필요하다.

워크플로 실패를 조사할 때는 마지막 빨간 줄만 보지 않는다. 최초의 의미 있는 실패와 그 결과로 생긴 후속 실패를 구분한다. 의존성 다운로드 실패 뒤 테스트 파일이 없다는 오류가 났다면 테스트 자체가 원인이 아닐 수 있다. 같은 입력으로 다시 실행한 결과와 일시적인 외부 실패 여부도 함께 기록한다.

캐시는 속도를 위한 입력이며 검증 결과가 아니다

캐시는 이전 실행의 일부 데이터를 재사용해 비용을 줄인다. 캐시 키가 같다는 이유로 현재 코드의 정확성이 확인되는 것은 아니다. 운영체제와 런타임 및 의존성 잠금 파일처럼 결과에 영향을 주는 요소를 키에 반영하고 캐시가 없는 실행에서도 빌드가 성립하는지 확인한다. 부분 일치 복원이 사용될 때는 정확히 같은 입력이 복원된다고 가정하지 않는다. [T26]

캐시와 배포 산출물은 목적이 다르다. 캐시는 다시 계산할 수 있는 중간 자료이고 산출물은 특정 실행의 결과로 식별해야 하는 파일이다. 배포할 파일을 넓은 복원 조건의 캐시에서 가져오면 어느 코드에서 만들어졌는지 모호해질 수 있다. 검사한 산출물과 배포한 산출물을 연결하는 흐름이 필요하다.

신뢰 수준이 낮은 실행이 만든 데이터를 높은 권한의 실행에서 사용하면 캐시도 신뢰 경계를 넘는다. 플랫폼의 현재 접근 제어와 별개로 어떤 실행이 쓰고 어떤 실행이 읽는지 확인한다. 캐시에 비밀을 저장하지 않으며 복원한 실행 파일을 무조건 신뢰하지 않는다. 이 원칙은 패키지 캐시와 생성 코드 및 테스트 도구에도 적용된다.

실패를 통과로 바꾸는 설정은 의미를 바꾼다

실험적인 검사를 계속 진행하도록 설정할 수는 있지만 그 결과를 필수 검사 통과와 같은 의미로 사용하면 안 된다. 작업을 계속 실행하는 것과 변경을 승인하는 것은 다른 판단이다. 최종 판정은 어떤 작업이 필수이며 실패와 취소 및 건너뜀을 어떻게 처리하는지 명시해야 한다.

테스트가 불안정하게 실패하면 성공할 때까지 재실행하는 관행이 생기기 쉽다. 그러나 반복 실행은 오류의 원인을 숨길 수 있다. 입력과 시간 및 외부 서비스 의존성을 기록하고 재현 조건을 찾는다. 재시도를 허용한다면 횟수와 이유를 남겨 최초 실패율과 최종 성공률을 구분한다. 지표의 정의가 바뀌면 품질 판단도 달라진다.

CI 실행 시간은 작업 시간의 단순 합보다 의존성 경로에 영향을 받는다. 서로 독립적인 검사는 병렬화할 수 있지만 배포가 필수 검사를 기다리는 관계는 유지해야 한다. 빠른 실행을 위해 필요한 의존성을 제거하면 검증 전에 공개되는 경로가 생길 수 있다. 성능 개선도 판정의 의미를 보존하며 수행한다.

CI는 단계별 주장을 확인한다

GIF 재생이전 상태다음 상태

마지막 상태

1. 검사할 소스 판본을 고정한다
2. 의존성을 준비하고 검사를 실행한다
3. 실패하면 같은 결과를 운영으로 보내지 않는다
4. 수정한 새 판본을 다시 검사한다
5. 검사한 판본과 배포한 판본을 연결한다

# scripts/check.py
from pathlib import Path

page = Path('index.html').read_text(encoding='utf-8')
assert '<title>' in page
assert "lang='ko'" in page
assert "id='answer'" in page
print('HTML baseline checks passed')

# .github/workflows/ci.yml
name: Lesson CI
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  validate:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: '3.13'
      - run: python scripts/check.py

jobs:
  validate:
    strategy:
      fail-fast: false
      matrix:
        python: ['3.12', '3.13']
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: ${{ matrix.python }}
      - run: python scripts/check.py

# .github/workflows/reusable-check.yml
name: Reusable lesson check
on:
  workflow_call:
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: '3.13'
      - run: python scripts/check.py

# .github/workflows/ci.yml
name: Lesson CI
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  validate:
    uses: ./.github/workflows/reusable-check.yml

13장 비밀과 배포 권한과 사고 대응

외부 입력과 실행 권한의 경계를 검토한다. OIDC와 배포 환경을 통제하고 비밀 유출 시 차단과 조사와 복구를 순서대로 수행한다.

실행할 코드의 출처와 사용할 권한을 함께 본다

자동화의 위험은 코드가 실행되는 위치와 사용할 수 있는 권한이 결합될 때 생긴다. 외부 PR의 코드를 검사하는 작업과 운영 비밀을 사용하는 배포 작업은 신뢰 수준이 다르다. 두 작업을 한 job에 섞으면 검증되지 않은 코드가 민감한 자원에 접근할 수 있다.

GitHub 공식 문서는 pull_request_target의 워크플로가 높은 신뢰 맥락에서 실행된다는 점과 외부 PR 코드를 가져와 실행하는 패턴의 위험을 설명한다. 현재 문서에는 공개 저장소에 대한 기본 정책의 평가 모드와 향후 적용 일정도 안내되어 있다. 정책의 현재 상태를 확인하되 설계 자체에서 신뢰되지 않은 코드와 비밀을 분리한다. [T06]

PR 제목과 이슈 본문도 신뢰되지 않은 입력이다. 이를 셸 스크립트에 직접 삽입하면 문장이 명령으로 해석될 수 있다. 환경 변수나 안전한 인수 전달 방식을 사용하고 해당 셸의 인용 규칙을 지킨다. 값이 GitHub에서 왔다는 사실과 프로젝트 관리자가 작성했다는 사실은 다르다.

짧은 자격 증명도 조건이 넓으면 위험하다

OIDC를 이용하면 장기 비밀을 저장하는 대신 실행 맥락을 바탕으로 짧은 자격 증명을 받을 수 있다. 그러나 신뢰 정책이 모든 저장소와 브랜치를 허용하면 짧은 유효 기간만으로 충분한 통제가 되지 않는다. 발급 주체와 대상 및 저장소와 참조 또는 환경 조건을 적절히 제한해야 한다.

Environment의 승인과 배포 제한은 운영 자원에 접근할 시점을 통제한다. 승인자가 어떤 커밋과 검사 결과를 승인하는지 알 수 있어야 의미가 있다. 사람이 버튼을 눌렀다는 사실만 남고 검토 대상이 불분명하면 통제의 실질적인 가치가 낮아진다.

비밀 유출의 우선순위는 자격 증명의 무효화다

비밀이 커밋되었다면 먼저 노출된 자격 증명을 폐기하거나 교체한다. 파일을 삭제하거나 이력을 재작성해도 이미 복제된 값까지 회수할 수는 없다. 이후 영향 범위를 조사하고 필요한 이력 정리와 캐시 및 아티팩트 확인을 수행한다. 처리 순서는 비밀의 악용 가능성을 줄이는 목적에 맞춰 정한다.

사고 기록에는 발견 시점과 노출 범위 및 수행한 조치와 확인 결과를 남긴다. 개인을 비난하는 문서보다 재발 조건을 설명하는 문서가 유용하다. 어떤 권한과 검토 경계가 실패했는지 알아야 도구 설정과 작업 절차를 개선할 수 있다.

토큰을 받을 수 있다는 사실과 배포할 수 있다는 사실은 다르다

OIDC에서 GitHub Actions는 실행의 주체와 문맥을 주장하는 토큰을 제공한다. 클라우드 제공자는 발급자와 대상 및 주체 등의 조건을 확인해 자신의 권한으로 교환할지를 판단한다. id-token 권한은 토큰 요청을 허용하는 조건이며 그 자체가 모든 클라우드 자원에 대한 권한을 뜻하지 않는다. 양쪽의 정책이 연결되어야 한다. [T25]

신뢰 조건을 저장소 이름 하나로만 넓게 정하면 의도하지 않은 브랜치나 실행 문맥에서도 권한을 받을 수 있다. 배포 대상과 브랜치 및 환경을 어떻게 제한할지 검토한다. 짧은 수명의 토큰도 허용 범위가 넓으면 그 시간 동안 큰 영향을 줄 수 있다. 만료 시간과 권한 범위는 각각의 통제 수단이다.

2026년 10월 확인한 문서에는 2026년 7월 15일 이후 생성된 저장소와 이후의 이름 변경 및 이전에 대해 소유자와 저장소의 불변 ID를 포함하는 주체 형식이 설명되어 있다. 이전 저장소에는 기존 형식이 남을 수 있으며 GitHub Enterprise Server에는 같은 전제를 적용하지 않는다. 예제 문자열을 그대로 복사하기보다 대상 저장소의 실제 주체 형식을 확인해 클라우드 정책과 맞춘다. [T25]

인증 실패를 해결할 때 조건을 하나씩 대조한다

배포 인증이 실패하면 토큰 발급과 교환 및 자원 접근을 나누어 조사한다. 토큰을 받지 못한 문제와 클라우드가 주체 조건을 거부한 문제 및 교환 후 자원 권한이 부족한 문제는 조치가 다르다. 모든 권한을 넓히는 방식은 원인을 확인하기 어렵게 만들고 불필요한 접근을 허용할 수 있다.

로그에는 판정에 필요한 비밀이 아닌 식별 정보와 단계별 오류를 남긴다. 토큰 원문을 복사해 공유할 필요는 없다. 저장소 이전 직후 실패했다면 변경된 주체와 기존 신뢰 조건을 대조한다. 원인을 설명할 수 있는 최소 변경을 적용하고 필요한 작업만 허용되는지 다시 확인한다.

외부 PR 코드와 배포 권한을 분리한다

GIF 재생이전 상태다음 상태

마지막 상태

1. 외부 기여 코드는 신뢰되지 않은 입력이다
2. 검사 결과가 권한 상승을 자동 허용하지 않는다
3. 신뢰된 소스와 빌드 조건을 확인한다
4. 운영 비밀은 필요한 단계에만 전달한다

- name: Show title safely
  env:
    PR_TITLE: ${{ github.event.pull_request.title }}
  run: printf '%s\n' "$PR_TITLE"

deploy:
  needs: validate
  if: github.ref == 'refs/heads/main'
  runs-on: ubuntu-latest
  environment: production
  concurrency:
    group: production-deploy
    cancel-in-progress: false
  permissions:
    contents: read
    id-token: write
  steps:
    - uses: actions/checkout@v7
    # 여기에 공급자 공식 OIDC 로그인 추가
    # 검증된 산출물 배포와 상태 확인 추가

## 발생과 발견
발견 시각:
영향 저장소와 커밋:

## 차단
회수한 자격 증명의 이름:
회수 완료 시각:

## 영향과 복구
확인한 사용 기록:
복구 검증:

## 재발 방지
원인과 후속 작업:

14장 보안 검사와 출처 검증

보안 알림의 실제 영향과 수정 우선순위를 판단한다. 서명과 해시와 출처 증거가 각각 무엇을 확인하는지 구분한다.

의존성은 외부 코드를 실행하는 관계다

라이브러리와 Action 및 컨테이너 이미지는 모두 외부에서 들어오는 실행 요소다. 프로젝트가 직접 작성하지 않았다는 이유로 검토 책임이 사라지지 않는다. 버전 선택과 갱신 주기 및 취약점 대응과 출처 확인을 운영 과정에 포함한다.

Action을 전체 커밋 SHA로 고정하면 이동 가능한 태그가 바뀌는 위험을 줄일 수 있다. 선택한 SHA가 공식 저장소의 의도한 판본인지 확인해야 하며 고정 이후에도 보안 갱신이 필요하다. 고정은 영원히 바꾸지 않는 정책이 아니라 변경을 명시적으로 검토하는 정책이다. [T07]

Dependabot이나 코드 스캐닝의 결과는 검토할 신호다. 경고가 없다는 사실은 알려지지 않은 취약점과 업무 권한 오류가 없다는 증명이 아니다. 반대로 경고가 있다는 사실만으로 현재 실행 경로가 반드시 취약하다고 단정할 수도 없다. 도달 가능성과 영향 및 수정 비용을 검토하고 판단 근거를 남긴다.

서명과 증명은 무엇을 주장하는지부터 읽는다

커밋 서명은 특정 키가 해당 객체에 서명했다는 검증에 사용된다. 키와 사람 또는 자동화 주체의 연결을 신뢰할 수 있는지도 별도 문제다. 서명이 유효해도 코드에 결함이 있을 수 있다. 출처 증명은 어떤 입력과 빌드 과정으로 결과가 만들어졌는지를 확인하는 데 도움을 주지만 그 결과가 모든 요구를 만족한다는 보증은 아니다.

SLSA는 소프트웨어 공급망의 무결성을 다루는 요구와 용어를 제공한다. 적용할 때는 실제 빌더와 증명 자료 및 검증 정책이 어떤 수준을 충족하는지 확인해야 한다. 도구를 하나 설치했다고 조직 전체가 특정 보증 수준을 달성했다고 표현하지 않는다. [T08]

검사 도구의 차이도 연구 대상이다

Fares 등의 2026년 프리프린트는 GitHub Actions 보안 스캐너 9개를 비교하고 596개 워크플로에서 탐지 범위와 결과의 차이를 분석했다. 프리프린트라는 출판 상태와 연구가 정한 표본 및 분류 체계를 함께 읽어야 한다. 이 책은 특정 도구의 순위를 제시하는 대신 검사 도구의 적용 범위를 확인해야 한다는 문제에 연결한다. [S16]

lesson-lab의 공급망 점검에서도 외부 Action의 출처와 권한 및 입력을 직접 읽는다. 스캐너가 탐지하기 어려운 업무 맥락은 사람이 판단해야 한다. 여러 도구의 결과를 합쳤다는 사실보다 각각 어떤 실패를 탐지하고 어떤 실패를 놓칠 수 있는지 설명하는 편이 전문적인 검토에 가깝다.

증명이 존재하는 것과 기대한 증명인 것은 다르다

artifact attestation은 어떤 워크플로와 소스 문맥에서 산출물이 만들어졌는지 확인하는 데 사용된다. 검증자는 서명 자체뿐 아니라 산출물의 다이제스트와 허용한 저장소 및 워크플로 같은 정책 조건을 확인해야 한다. 예상하지 않은 제작자가 만든 유효한 증명을 받아들이면 검증의 목적을 달성하지 못한다. [T27]

같은 파일 이름의 두 PDF가 있다고 하자. 이름이 같아도 바이트가 다르면 서로 다른 산출물이다. 증명이 가리키는 다이제스트와 사용자가 받은 파일의 다이제스트를 연결해야 한다. 소스 저장소의 이름만 확인하고 실제 파일을 대조하지 않으면 중간 교체를 놓칠 수 있다.

증명은 빌드의 출처를 설명하며 프로그램의 모든 성질을 증명하지 않는다. 신뢰한 워크플로가 취약한 의존성을 포함할 수도 있다. 출처 검증과 의존성 분석 및 기능 시험을 결합해야 한다. 각각의 도구가 어떤 주장을 뒷받침하는지 표로 정리하면 보안 기능을 켰다는 포괄적인 표현보다 정확하다.

SBOM은 성분 목록과 실제 영향 분석 사이에 놓인다

소프트웨어 자재 명세서는 포함된 구성 요소를 파악하는 데 도움이 된다. 어떤 패키지가 있다는 사실은 취약한 코드 경로가 실제로 실행된다는 사실과 같지 않다. 반대로 직접 선언한 패키지 목록만으로 전이 의존성을 모두 파악했다고 할 수도 없다. 구성 목록과 실행 경로 및 배포 환경을 함께 확인해야 영향을 평가할 수 있다.

새 취약점이 알려졌을 때는 영향받는 버전과 산출물을 식별하고 수정 후 검증 범위를 정한다. 이름이 비슷한 패키지나 다른 환경의 결과를 혼동하지 않는다. 업데이트를 적용했다는 기록에는 실제 배포 판본과 남은 예외도 연결한다. 보안 작업의 완료는 알림을 닫는 행위보다 실행 중인 시스템의 상태로 판단한다.

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
    open-pull-requests-limit: 5

git config --local gpg.format ssh
git config --local user.signingkey /PATH/TO/SIGNING-KEY.pub
git config --local commit.gpgsign true
git config --local --get user.signingkey

15장 백업과 비용과 운영 인수인계

운영 자원과 담당 역할과 비용을 기록한다. Bundle의 포함 범위를 이해하고 새 환경에서 복원해 백업이 실제로 쓸 수 있는지 확인한다.

Git 이력만으로 GitHub 프로젝트 전체가 복원되지는 않는다

Git 저장소에는 커밋과 tree 및 blob과 참조가 들어 있다. GitHub의 이슈와 PR 대화 및 조직 권한과 환경 설정은 별도의 서비스 데이터다. 따라서 저장소를 mirror clone하거나 bundle로 보관하는 작업은 중요하지만 프로젝트 운영 상태 전체의 백업과 같지는 않다.

lesson-lab에 LFS 파일과 Release 첨부 파일 및 Pages 설정이 있다면 각각의 보존 방법을 확인해야 한다. 복원 목표를 먼저 정한 뒤 필요한 자산 목록을 만든다. 소스 이력만 되살리면 되는 학습 저장소와 사용자에게 같은 서비스를 다시 제공해야 하는 운영 저장소는 요구가 다르다.

복원 시험은 사본의 품질을 측정한다

bundle verify는 번들의 구조와 필요한 전제 등을 확인하는 데 도움이 된다. 그러나 애플리케이션이 실제로 실행되는지는 별도의 검사다. 분리된 폴더에서 복원하고 필요한 참조와 파일 및 테스트를 확인한다. 외부 의존성과 비밀 설정이 빠졌다면 소스 복원에는 성공해도 서비스 복구에는 실패할 수 있다.

백업 주기와 보존 기간은 변경 빈도와 허용 손실 및 복구 비용에 따라 정한다. 자동 백업 작업의 성공 여부를 감시하고 정기적으로 복원해 본다. 오래된 사본이 계속 쌓이는 것과 복구 가능한 사본이 유지되는 것은 다르다.

비용은 자원 사용과 정책의 결과다

Actions 실행 시간과 저장 공간 및 개발 환경의 사용량은 프로젝트 구조에 영향을 받는다. 불필요한 Matrix 조합과 중복 실행 및 오래된 아티팩트를 줄일 수 있다. 그러나 검사를 줄이는 결정은 어떤 위험이 증가하는지 함께 평가해야 한다. 비용 절감과 검증 범위를 별개의 문제로 취급하지 않는다.

인수인계에는 소유자와 결제 및 자격 증명과 복구 담당자를 포함한다. 한 사람의 개인 계정에만 중요한 권한이 남아 있으면 기술 문서가 완벽해도 운영이 중단될 수 있다. 조직의 지속 가능성은 코드와 사람 및 권한 구조가 함께 결정한다.

bundle의 범위와 전제 객체를 이해한다

git bundle은 참조와 관련 객체를 파일로 전달하는 방법이다. 모든 필요한 객체를 포함한 bundle과 이전 객체를 전제로 하는 증분 bundle은 복원 조건이 다르다. old..new 같은 범위로 만들었다면 수신 쪽에 old와 필요한 이력이 있어야 할 수 있다. bundle verify는 이런 조건을 확인하는 데 사용한다. [T24]

git bundle create lesson-lab.bundle --all
git bundle verify lesson-lab.bundle
git clone lesson-lab.bundle recovered-lab

이 예시는 Git 참조에서 도달하는 이력을 파일로 보존하고 별도 폴더에 복원하는 흐름이다. 추적되지 않은 파일과 로컬 환경 변수 및 GitHub의 이슈와 권한 설정까지 모두 담는 방식은 아니다. LFS의 실제 객체와 submodule의 별도 저장소도 보존 범위를 확인해야 한다. 백업 파일이 하나라는 편리함과 프로젝트 전체가 포함되었다는 판단을 구분한다.

복원 목표는 시간과 자료 손실의 허용 범위로 표현한다

복구 시간 목표는 장애 이후 어느 정도 안에 필요한 기능을 되살릴지에 관한 기준이다. 복구 시점 목표는 어느 시점의 자료까지 되살릴 수 있어야 하는지에 관한 기준이다. 매일 백업하는 서비스와 매시간 백업하는 서비스는 같은 장애에서도 잃을 수 있는 자료의 범위가 다르다. 두 목표는 같은 숫자로 표현할 필요가 없다.

교육 자료 저장소는 하루 전 판본으로 복원해도 수업을 이어갈 수 있지만 실시간 제출 시스템은 최근 답안 손실이 큰 영향을 줄 수 있다. 자산의 성격에 따라 보존 주기와 복원 우선순위를 정한다. 모든 자료에 가장 높은 수준을 적용하면 비용과 관리 부담이 커지므로 실제 요구에 연결해야 한다.

복원 연습에서는 파일을 꺼내는 데 걸린 시간뿐 아니라 실행 환경 준비와 권한 연결 및 결과 검증에 걸린 시간을 측정한다. 압축 해제에 성공한 시점이 서비스 복구의 완료 시점은 아니다. 다른 사람이 문서를 따라 복원할 수 있는지도 시험하면 개인의 기억에 의존한 절차를 발견할 수 있다.

백업은 복원으로 확인한다

GIF 재생이전 상태다음 상태

마지막 상태

1. 파일 존재는 복원 성공의 증거가 아니다
2. 원본과 분리된 위치에서 복원을 시작한다
3. 필요한 이력과 파일 및 외부 자료를 확인한다
4. 프로그램과 운영 절차까지 시험한다

git clone --mirror https://github.com/YOUR-ID/lesson-lab.git lesson-lab-backup.git
git -C lesson-lab-backup.git fsck --full
git clone lesson-lab-backup.git lesson-restore-check
git -C lesson-restore-check log -5 --oneline

git status
git bundle create ../lesson-lab.bundle --all
git bundle verify ../lesson-lab.bundle
git bundle list-heads ../lesson-lab.bundle

git clone ../lesson-lab.bundle ../lesson-restored
git -C ../lesson-restored log -5 --oneline
git -C ../lesson-restored branch -a
git -C ../lesson-restored fsck --full

16장 이력 재작성과 원인 조사

개인 이력을 정리하고 공유된 기준이 바뀌는 영향을 검토한다. Worktree와 Bisect와 range-diff를 조사 목적에 맞게 활용한다.

재작성의 목적을 먼저 제한한다

Interactive rebase는 커밋을 묶거나 순서를 바꾸고 메시지를 다듬는 데 사용할 수 있다. 목적은 검토 가능한 논리적 이력을 만드는 것이다. 이미 공유된 이력을 바꿀 때는 다른 작업자의 참조와 자동화에 미치는 영향을 확인한다. 정리된 그래프의 미관만으로 협업 비용을 정당화할 수는 없다.

force-with-lease는 원격 참조가 예상 상태일 때 갱신하도록 조건을 둔다. 다만 기대값을 명시하지 않는 형태는 로컬 원격 추적 참조에 의존하므로 백그라운드 fetch가 그 기준을 바꿀 수 있다. 특정 원격 커밋을 읽고 그 값으로 조건을 명시하는 방법을 이해하면 보호 장치가 무엇을 비교하는지 더 분명해진다. 이 옵션도 팀 정책과 권한 제한을 대체하지 않는다. [T09]

재작성 전후에는 단순히 커밋 개수만 보지 않는다. 최종 파일 상태와 패치의 의미가 유지되는지 확인한다. range-diff는 두 커밋 범위의 패치 시리즈를 비교하는 데 유용하다. 테스트와 함께 사용하면 정리 과정에서 의도하지 않은 변경이 들어갔는지 살피는 근거가 된다.

bisect는 판정 가능한 질문이 있어야 작동한다

git bisect는 알려진 좋은 상태와 나쁜 상태 사이에서 문제를 도입한 커밋을 좁힌다. 후보를 나누어 검사하기 때문에 선형으로 모든 커밋을 보는 것보다 효율적일 수 있다. 그러나 성공과 실패를 판정하는 검사가 안정적이어야 한다. 같은 커밋이 실행할 때마다 다른 결과를 내면 탐색의 의미가 약해진다.

자동 bisect 스크립트의 종료 코드는 계약이다. 성공과 실패 및 검사 불가능을 구분해야 한다. 해당 커밋이 옛 런타임을 요구해 실행하지 못하는 경우를 기능 실패로 판정하면 잘못된 원인을 찾을 수 있다. 테스트 환경의 변화와 실제 회귀를 분리하는 과정이 필요하다.

worktree는 조사와 개발의 상태를 분리한다

worktree를 사용하면 같은 저장소 객체를 공유하면서 다른 작업 트리를 둘 수 있다. 현재 작업을 억지로 치우지 않고 과거 판본을 조사하거나 긴 테스트를 돌릴 수 있다. 하지만 작업 디렉터리의 의존성 파일과 외부 데이터베이스까지 자동으로 분리되는 것은 아니다. 각 작업 트리의 실행 설정을 확인한다.

원인 커밋을 찾았다고 분석이 끝나는 것은 아니다. 왜 그 변경이 기존 테스트를 통과했는지와 요구가 어디에서 누락되었는지 확인한다. 커밋은 원인이 드러난 위치를 가리키며 조직적 원인이나 설계의 빈틈까지 모두 설명하지는 않는다.

커밋의 새 식별자와 변경의 새 의미를 구분한다

rebase 뒤 커밋 식별자가 달라지는 것은 예상되는 현상이다. 중요한 질문은 변경의 의도가 유지되었는지다. git range-diff는 두 패치 계열을 비교해 재작성 전후의 관계를 읽는 데 도움을 준다. 일반 diff가 최종 스냅샷의 차이를 보는 데 쓰인다면 range-diff는 변경 묶음 사이의 대응을 이해하는 도구다. [T23]

충돌 해결을 포함한 rebase에서는 자동 적용이 끝났다고 의미가 보존되었다고 가정하지 않는다. 이전 계열과 새 계열을 비교하고 기존 검사와 상호작용 검사를 다시 수행한다. 커밋이 합쳐지거나 순서가 바뀌면 중간 상태의 실행 가능성이 달라질 수 있다. 팀이 커밋 단위로 bisect하는지에 따라 중간 상태의 품질도 중요해진다.

diff는 유일한 객관적 서술이 아니다

두 파일 사이의 변화는 여러 방식으로 줄을 대응시켜 표현할 수 있다. 반복되는 문장과 이동한 코드가 많으면 선택한 diff 알고리즘에 따라 변경 묶음의 모양이 달라질 수 있다. Nugroho와 동료들의 연구는 Git diff 알고리즘 선택이 코드 변경량과 결함 유입 추정 같은 분석에 영향을 줄 수 있음을 보고했다. 연구의 대상 프로젝트와 분석 절차를 현재의 모든 저장소로 일반화하지 않되 측정 도구의 선택도 결과의 일부임을 기억한다. [S23]

리뷰에서 차이가 이해되지 않으면 다른 알고리즘과 공백 표시 옵션을 비교할 수 있다. 다만 보기 좋은 결과를 얻기 위해 중요한 공백 변화나 생성 규칙의 변화를 숨겨서는 안 된다. 분석의 목적과 옵션을 기록해야 다른 사람이 같은 결과를 재현할 수 있다.

bisect의 판정 스크립트도 측정 도구다. 테스트가 간헐적으로 실패하거나 외부 서비스 상태에 따라 달라지면 탐색 결과가 흔들린다. 정상과 실패를 안정적으로 구분할 수 있는 최소 조건을 먼저 마련한다. 찾은 커밋은 원인 후보이며 그 변경이 실패를 일으키는 기제를 설명하고 검증하는 단계가 뒤따른다.

rebase는 새로운 부모로 새 커밋을 만든다

GIF 재생이전 상태다음 상태

마지막 상태

1. 작업 커밋 C는 A를 부모로 가진다
2. 기준 브랜치가 B까지 진행한다
3. 변경을 B 위에 다시 적용한다
4. 부모가 달라진 새 객체 C2를 가리킨다

git status
git branch backup/before-interactive
git rebase -i HEAD~3

pick   a111111 Add answer control
fixup  b222222 Fix button label
reword c333333 Add usage guide

git switch feature/history-cleanup
git fetch origin
git status
git branch backup/before-push-rewrite
expected_oid=$(git rev-parse origin/feature/history-cleanup)
git rebase -i HEAD~3
git diff backup/before-push-rewrite HEAD
git log -5 --oneline
git push \
  --force-with-lease=refs/heads/feature/history-cleanup:$expected_oid \
  origin HEAD:refs/heads/feature/history-cleanup

git fetch origin
git worktree add ../lesson-hotfix -b fix/urgent origin/main
git worktree list

git worktree add --detach ../lesson-investigation HEAD
cd ../lesson-investigation
git bisect start
git bisect bad HEAD
git bisect good GOOD-ID
# 현재 파일을 실행해 보고 하나를 선택
git bisect good
# 다음 상태를 실행해 보고 good 또는 bad 반복
git bisect reset

# 별도 조사 Worktree 안에서 실행
git bisect start
git bisect bad BAD-ID
git bisect good GOOD-ID
git bisect run python /ABSOLUTE/PATH/check_regression.py
git bisect reset

git branch backup/before-range-review
# 개인 브랜치의 Rebase 수행 후
git range-diff OLD-BASE..OLD-TIP NEW-BASE..NEW-TIP
git diff OLD-TIP NEW-TIP

17장 CLI와 API를 활용한 업무 연동

명령과 요청의 대상을 명시하고 필요한 결과를 수집한다. REST와 GraphQL과 Webhook의 응답과 페이지 이동과 서명을 검증한다.

API는 화면의 복사본이 아니라 명시적인 계약이다

REST는 자원과 요청 방식 및 응답 상태를 중심으로 읽는다. GraphQL은 필요한 필드를 질의로 표현한다. 어느 방식이든 페이지네이션과 권한 및 오류와 제한을 처리해야 한다. 첫 응답에 자료가 100개 있다고 전체가 100개라고 결론 내리면 데이터가 잘릴 수 있다.

GraphQL의 cursor는 다음 페이지를 읽기 위한 불투명한 값으로 다룬다. 내부 형식을 해석하거나 번호처럼 계산하지 않는다. hasNextPage와 endCursor를 사용해 반복하고 중간 실패 뒤 어디서 재개할지 정한다. 수집 중 원본 자료가 바뀔 수 있으므로 결과가 어느 시점의 완전한 스냅샷인지도 검토해야 한다.

Webhook은 사건을 전달하는 신호다. 중복 전달과 순서 변화 및 일시적 실패를 고려해 수신자를 설계한다. 서명 검증은 원문 바이트를 기준으로 수행하고 처리한 전달 ID를 기록해 중복 효과를 줄인다. Webhook이 도착했다고 외부 자료의 모든 최신 상태를 이미 안다고 가정하지 않는다.

활동 데이터와 성과를 동일시하지 않는다

Kalliamvakou 등의 GitHub 마이닝 연구는 저장소의 목적과 활동 상태 및 PR 병합 기록의 해석에서 주의할 점을 제시했다. 저장소 데이터가 풍부하더라도 연구 질문에 맞는 표본과 측정 정의가 필요하다는 내용이다. 2014년 자료에서 관찰한 비율을 현재 플랫폼 전체의 비율로 재사용해서는 안 된다. [S14]

팀의 커밋 수를 비교할 때도 같은 주의가 필요하다. Squash 정책을 쓰는 팀과 작은 커밋을 유지하는 팀은 같은 작업을 다른 개수로 기록할 수 있다. 자동 생성 커밋과 봇의 활동도 섞인다. 활동량은 관찰 가능한 행동의 흔적이지 가치와 품질의 완전한 대리 지표가 아니다.

자동화의 완료 조건을 부분 실패까지 확장한다

이슈 목록을 내보내는 자동화가 중간 페이지에서 실패하면 이미 저장한 자료와 남은 자료를 구분해야 한다. 중복 없이 재개할 수 있는 키와 진행 기록을 남긴다. 삭제된 자원과 권한 변경으로 더 이상 읽을 수 없는 자원을 단순한 빈 값으로 처리하면 의미가 사라질 수 있다.

자동화는 필요한 권한만 가진 자격 증명으로 실행하고 결과에 수집 범위와 시점을 적는다. 정확한 수치처럼 보이는 표일수록 누락과 필터 및 페이지네이션의 조건을 함께 설명해야 한다. 전문적인 보고서는 숫자의 정밀도보다 그 숫자가 무엇을 대표하는지 분명하게 한다.

조회의 반복과 변경의 반복은 다른 비용을 가진다

API 자동화는 응답 코드와 페이지네이션 및 제한 헤더를 계약으로 다뤄야 한다. GitHub는 불필요한 polling을 줄이고 조건부 요청을 활용하며 제한 오류의 안내에 맞춰 재시도하도록 설명한다. 변경 요청을 무분별하게 병렬 실행하는 방식도 제한과 순서 문제를 일으킬 수 있다. 최대 호출 수를 고정값으로 외우기보다 실제 응답과 인증 문맥을 확인한다. [T28]

전체 이슈 목록을 매번 처음부터 내려받는 자동화는 자료가 많아질수록 비용이 커진다. 변경된 범위를 식별하고 중간 진행 상태를 남기는 방법을 검토한다. 다만 마지막 시각 하나만 저장하면 동일 시각의 경계 자료나 지연된 갱신을 놓칠 수 있다. 겹치는 조회 범위와 안정적인 식별자 기반 중복 제거를 함께 사용할 수 있다.

페이지를 읽는 동안 원격 자료가 바뀔 수 있다는 점도 고려한다. 첫 페이지와 마지막 페이지가 한 시점의 완전한 스냅샷이라고 보장되는지 API 계약을 확인한다. 보장이 없다면 수집 시각과 조건을 남기고 정확한 스냅샷이 필요한 분석에는 별도 전략을 선택한다. 수집 성공과 측정 타당성은 같은 판단이 아니다.

이벤트 전달과 업무 처리의 완료를 분리한다

Webhook을 받는 서버는 서명을 확인하고 필요한 이벤트와 action을 구분해야 한다. GitHub의 전달 식별자는 중복 처리 방지와 재전달 추적에 사용할 수 있다. 실패한 전달이 자동으로 모두 재전송된다고 가정하지 않으며 누락된 전달을 확인하고 다시 처리하는 경로를 준비한다. [T29]

서버가 성공 응답을 보냈다는 사실은 업무 처리가 끝났다는 뜻이 아닐 수 있다. 오래 걸리는 작업을 큐에 넣는다면 응답은 안전하게 접수했다는 의미로 정의할 수 있다. 이 경우 큐 기록과 실제 처리 결과를 별도로 관리해야 한다. 응답을 먼저 보내고 아무 기록도 남기지 못한 채 프로세스가 종료되면 사건이 사라질 수 있다.

같은 전달을 두 번 받았을 때 이슈 댓글을 두 번 작성하지 않게 하려면 식별자와 처리 결과를 연결한다. 단순히 처리 중이라는 표시만 남긴 뒤 실패하면 영원히 재처리되지 않는 문제도 생길 수 있다. 접수와 처리 중 및 완료와 재시도 가능 실패 같은 상태를 정의하고 상태 전이를 기록한다. 자동화의 신뢰성은 성공 경로보다 중단 이후의 행동에서 드러난다.

페이지네이션은 마지막 페이지까지 이어진다

GIF 재생이전 상태다음 상태

마지막 상태

1. 첫 응답은 전체 결과일 필요가 없다
2. 서버가 제공한 다음 위치를 사용한다
3. 다음 페이지가 없는지 확인한다
4. 수집 시점과 권한 및 필터도 기록한다

gh auth status
gh repo view
gh issue list --state open
gh pr list --state open
gh run list --limit 10

git remote -v
git branch --show-current
gh repo view
git push -u origin HEAD
gh pr create --base main --title 'Improve answer access' \
  --body-file pr-body.md --draft
gh pr view --web

gh pr checks
gh pr diff
gh run list --limit 5
gh run view RUN-ID --log-failed
gh issue list --state open --json number,title,url

gh api --paginate \
  'repos/YOUR-ID/lesson-lab/issues?state=open&per_page=100' \
  --jq '.[].number'

import hashlib
import hmac

def valid_signature(raw_body, signature, secret):
    if not signature or not signature.startswith('sha256='):
        return False
    digest = hmac.new(
        secret.encode('utf-8'),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    expected = 'sha256=' + digest
    return hmac.compare_digest(expected, signature)

payload = b'{}'
demo_secret = 'EXAMPLE-ONLY'
signed = 'sha256=' + hmac.new(
    demo_secret.encode(), payload, hashlib.sha256
).hexdigest()
assert valid_signature(payload, signed, demo_secret)
assert not valid_signature(b'{ }', signed, demo_secret)

query($owner: String!, $name: String!, $cursor: String) {
  repository(owner: $owner, name: $name) {
    issues(first: 50, after: $cursor, states: OPEN) {
      nodes { number title url }
      pageInfo { hasNextPage endCursor }
    }
  }
  rateLimit { remaining resetAt }
}

gh api graphql \
  -F owner=YOUR-ID \
  -F name=lesson-lab \
  -F query=@query.graphql

18장 종합 프로젝트와 교육 자료 운영

개인 작업과 팀 검토를 Issue부터 배포까지 이어 간다. 교육 자료의 수식과 도식과 판본 및 접근 범위를 관리한다.

기능 완료와 운영 준비를 함께 판단한다

lesson-lab의 종합 프로젝트는 저장소 생성에서 끝나지 않는다. 변경 요구를 이슈로 설명하고 브랜치에서 구현하며 PR로 검토하고 CI로 검사한 뒤 판본을 식별해 배포한다. 문제가 생겼을 때 이전 결과와 데이터를 복구할 수 있는지도 확인한다. 각각의 단계는 별도 기능이면서 앞 단계의 주장에 대한 증거를 제공한다.

예를 들어 자료 검색을 개선했다는 주장은 변경된 코드와 테스트 및 배포 결과가 함께 뒷받침해야 한다. 로컬 테스트만 통과했다면 배포 경로의 문제는 아직 확인하지 않은 것이다. CI가 통과했어도 실제 사용자의 키보드 조작과 내용의 정확성은 별도 검토가 필요할 수 있다.

재현 가능한 산출물에는 실행 조건이 남는다

교육 자료와 연구 코드를 GitHub로 공유할 때는 결과만 올리지 않는다. 입력 데이터의 출처와 처리 과정 및 실행 환경을 설명한다. 공개할 수 없는 자료는 가짜 데이터나 접근 절차로 대체하되 그로 인해 재현 범위가 달라진다는 점을 표시한다. 계산 결과가 같다는 의미의 재현성과 연구 해석이 타당하다는 의미의 검증은 구분한다.

수식과 도식은 버전 관리할 원본과 배포할 결과를 함께 생각한다. 소스와 생성 이미지를 모두 보관한다면 어느 쪽이 권위 있는 원본인지 적는다. 자동 생성 결과를 사람이 직접 수정하면 다음 빌드에서 사라질 수 있다. 문서 생성 명령과 확인 절차를 기록하면 유지보수자가 같은 결과를 다시 만들 수 있다.

최종 검토는 질문에 증거로 답하는 과정이다

저장소의 목적을 처음 보는 사람이 이해할 수 있는가. 필요한 권한과 비밀이 문서화되어 있는가. 현재 배포가 어느 커밋에서 나왔는가. 중요한 실패를 어떤 검사로 발견하는가. 담당자가 바뀌어도 복원할 수 있는가. 이 질문에 실제 파일과 실행 결과 및 설정으로 답할 수 있어야 한다.

학술 자료는 이러한 판단의 배경을 제공한다. 하지만 논문을 인용했다고 특정 저장소가 자동으로 좋은 설계를 갖는 것은 아니다. 연구에서 제시한 개념을 자신의 환경에 적용하고 관찰한 결과와 남은 한계를 설명해야 한다. 이 책의 마지막 점검표는 그 과정을 반복 가능하게 만드는 도구다.

주장과 증거와 남은 가정을 연결한다

프로젝트를 마칠 때 모든 기능이 완성되었다는 문장 하나로 보고하면 검토자는 의미를 확인하기 어렵다. 요구별로 구현한 판본과 수행한 검사 및 관찰한 결과를 연결한다. 같은 자료에서 다른 사람이 검사를 반복할 수 있는지도 본다. 증거가 있는 주장과 아직 가정에 의존하는 부분을 구분하면 다음 수정의 우선순위가 드러난다.

이 표는 서류를 늘리기 위한 양식이 아니다. 검사 결과가 어떤 결정을 허용하는지 읽는 방법이다. 검색 함수 검사만으로 운영 계정의 안전성을 주장할 수 없고 서명 검증만으로 교육 내용의 정확성을 주장할 수 없다. 서로 다른 품질 속성에는 서로 다른 증거가 필요하다.

전문성은 변경을 예측하고 한계를 설명하는 능력이다

초보자는 현재 명령의 성공 여부에 집중하기 쉽다. 경험이 쌓이면 그 명령이 어느 상태를 바꾸며 다른 사람의 작업과 어떤 관계를 갖는지 생각한다. 더 나아가 실패했을 때 남는 증거와 복구 경로 및 운영 비용을 함께 설계한다. 이 발전은 사용하는 명령의 개수보다 판단하는 범위의 확장으로 볼 수 있다.

마지막으로 작은 변경을 다른 사람에게 맡겨 본다. 자료 한 개를 추가하고 검사하며 PR을 만들고 배포 판본을 확인하게 한다. 설명이 막히는 곳은 프로젝트의 지식이 개인에게 묶여 있는 지점일 수 있다. 그 지점을 코드와 문서 및 자동화의 계약으로 옮기는 작업이 장기적인 유지보수 능력을 만든다.

한 변의 길이가 $a$인 정사각형의 넓이는 $a^2$다.

$$
V = \frac{1}{3}Bh
$$

flowchart TD
  A[문제 제시] --> B[개인 탐구]
  B --> C{추가 근거가 필요한가}
  C -->|예| B
  C -->|아니오| D[설명 공유]