gh-aw compile 뒤 .lock.yml 차이, 6칸으로 확인하기

읽는 시간 약 7분 · 검토한 Markdown과 생성 workflow가 같은 변경인지 확인하는 방법

핵심 요약

• GitHub Agentic Workflows는 Markdown 정의를 GitHub Actions용 .lock.yml로 compile하며, 두 파일을 함께 관리합니다.
• 공식 문서상 frontmatter 변경은 재컴파일 대상이고, Markdown 본문 지시는 runtime에 읽히므로 본문만 바꾼 경우는 구분해서 판단해야 합니다.
• frontmatter_hash는 생성 metadata의 한 항목입니다. source의 진위나 전체 변경 이력을 증명하는 서명으로 해석하지 마세요.
• source revision, gh-aw 버전·실행 옵션, compile 결과, lockfile diff와 검토 결정을 한 묶음으로 남기면 오래된 산출물을 승격 전에 발견하기 쉬워집니다.
• 차이가 없다는 사실만으로 안전하다고 결론 내리지 말고, compile 실패·미설명 diff·revision 불일치에서는 보류하세요.

목차

Markdown PR은 승인됐는데 실행 lockfile은 이전 상태일 수 있습니다

GitHub Agentic Workflows에서는 사람이 읽기 쉬운 Markdown이 workflow의 원본 역할을 하고, compile 결과인 .lock.yml이 GitHub Actions workflow로 사용됩니다. 여기서 lockfile은 패키지 의존성 잠금 파일이 아니라 gh-aw가 생성한 workflow 정의를 뜻합니다. 그래서 PR에서 Markdown만 확인하고 생성 파일의 변경·동기화 상태를 놓치면, 리뷰한 source와 기본 브랜치에 올라간 실행 파일이 서로 다른 변경을 반영할 수 있습니다.

이때 필요한 질문은 “Markdown이 보기 좋게 바뀌었나요?”가 아닙니다. 어떤 source revision을 어떤 gh-aw 버전과 옵션으로 compile했고, 그 결과로 생성된 lockfile의 diff를 누가 검토했나요?를 확인해야 합니다.

gh-aw에서 source와 .lock.yml은 각각 무엇을 맡을까요?

GitHub 공식 문서는 workflow Markdown을 YAML frontmatter와 Markdown 본문의 두 부분으로 설명합니다. frontmatter는 workflow 설정을 담고, 본문은 에이전트가 따를 자연어 지시를 담습니다. gh-aw compiler는 Markdown workflow를 GitHub Actions가 사용할 .lock.yml로 변환하며, 공식 안내는 두 파일을 기본 브랜치에 함께 commit하는 흐름을 설명합니다.

여기서 중요한 구분이 하나 있습니다. 공식 Workflow Structure 문서는 Markdown 본문이 실행 시 읽히며, 본문 지시만 수정할 때는 재컴파일 없이 반영할 수 있다고 설명합니다. 반면 frontmatter를 바꾸면 lockfile을 다시 생성해야 합니다. 따라서 “원본 Markdown이 달라졌다”는 사실만으로 모든 변경을 같은 방식으로 처리하지 말고, frontmatter 변경인지 본문 변경인지 먼저 구분하세요.

.lock.yml의 header에는 gh-aw-metadata와 frontmatter_hash가 기록될 수 있습니다. 이것은 생성물에서 확인할 metadata이지, source commit의 출처를 인증하거나 실행 결과 전체의 무결성을 보증하는 서명은 아닙니다. source revision과 생성 파일의 연결은 저장소의 변경 이력 및 compile 증거와 함께 확인해야 합니다.

언제 다시 compile해야 할까요?

현재 공식 문서가 구분하는 기본 기준은 명확합니다. frontmatter 변경은 재컴파일하고, Markdown 본문만 바꾼 경우에는 본문이 runtime에 읽히는 특성을 고려합니다. 이 기준은 모든 프로젝트별 검토 절차를 대신하지 않으므로, 저장소의 실제 branch protection이나 팀 정책이 추가 검사를 요구한다면 그 절차도 따라야 합니다.

• frontmatter를 바꿨다면: 같은 source revision에서 gh aw compile을 실행하고 짝이 되는 lockfile을 확인합니다.
• 본문 지시만 바꿨다면: 공식 문서상 재컴파일이 필수인 변경과 구분합니다. 다만 본문 리뷰와 source revision 확인은 여전히 필요합니다.
• compiler 버전이나 compile 실행 조건이 달라졌다면: 사용한 버전과 실제 옵션을 기록하고, 새 diff가 생긴 원인을 설명할 수 있는지 검토합니다.
• compile 실패 또는 필요한 source를 확인할 수 없다면: 성공한 것처럼 처리하지 말고 결과를 unknown/hold로 남깁니다.

gh aw compile은 공식 문서에 나오는 명령 형태입니다. 아래는 설명용 절차이지 이 글에서 실행해 확인한 결과가 아닙니다. 실제 저장소와 설치 버전에 맞는 경로·옵션을 확인한 뒤 사용하세요.

# 설명용 예시: 실제 저장소의 workflow 경로와 팀 절차를 먼저 확인하세요
gh aw compile
# 이어서 해당 workflow의 생성 .lock.yml 변경과 새 파일 상태를 검토합니다

6칸 source-to-lock 증빙 카드

아래 카드는 특정 repository의 상태를 진단한 결과가 아니라, 팀이 재컴파일 검토 때 채울 수 있는 운영 템플릿입니다. 민감한 설정값이나 비밀값은 복사하지 말고, 확인 가능한 revision과 결과 및 책임자만 남기세요.

이 카드의 실무 가치는 체크 표시 자체가 아니라 나중에 같은 변경을 다시 추적할 수 있는 운영 기록에 있습니다. compiler 버전이 바뀌거나 같은 source에서 diff가 달라졌다면, 버전 차이·생성 조건·의도된 변경을 하나씩 설명한 뒤에만 다음 단계로 넘기세요.

가상 PR 예시: trigger 설정을 바꿨다면

아래는 절차를 설명하기 위한 가상 예시이며, 실제 repository에서 실행한 사례가 아닙니다. 한 PR에서 workflow의 frontmatter에 있는 trigger 설정을 바꿨다고 가정해 보겠습니다.

1. 리뷰할 Markdown revision과 짝이 되는 .lock.yml을 확인합니다.
2. PR이 사용하는 gh-aw 버전과 compile 조건을 기록합니다.
3. 그 revision에서 공식 compiler를 실행해 lockfile을 다시 생성합니다.
4. 새 lockfile이 기존 파일과 어떻게 달라졌는지 확인하고, diff가 의도한 trigger 변경과 연결되는지 설명합니다.
5. 설명되지 않는 변경, compile 실패, source와 생성물의 revision 불일치가 남으면 merge 또는 배포 승격을 멈춥니다.

예를 들어 의도한 frontmatter 수정과 무관한 생성 workflow 변경이 함께 나타났다면, “자동 생성이니 괜찮겠지”라고 넘기지 않습니다. 사용한 compiler 조건과 diff를 다시 확인하고, 원인을 설명할 수 없으면 보류 후 재검토가 합리적인 결정입니다. 이 예시에는 고정된 파일 내용이나 측정 결과를 넣지 않았습니다.

통과·추가 확인·보류 기준

이 확인이 보증하지 않는 것

source-to-lock 검토는 검토한 입력과 생성 파일의 관계를 더 분명하게 만드는 절차입니다. diff가 비어 있거나 metadata가 일치해도 workflow의 실제 실행 결과, 런타임 동작, 모든 조직 정책의 적절성까지 입증되지는 않습니다. 따라서 이 카드를 전체 실행 위험 검토나 배포 산출물 출처 확인으로 바꾸어 읽지 마세요.

실행 시 무엇을 읽고 어떤 경계를 검토할지 판단하는 작업은 별도입니다. FLOWIT의 GitHub Agentic Workflow 실행 경계 카드는 그 질문을 다룹니다. 또 배포 파일 자체의 출처·digest를 확인해야 한다면 Artifact Attestation 검토 절차와 구분해 살펴보세요. 세 절차는 서로 대체하지 않습니다.

자주 묻는 질문

Markdown 본문만 바꿔도 .lock.yml을 다시 생성해야 하나요?

GitHub Agentic Workflows의 Workflow Structure 문서는 Markdown 본문이 runtime에 읽히므로 본문 지시만 수정할 때는 재컴파일이 필요하지 않다고 설명합니다. 반면 frontmatter 변경은 재컴파일 대상입니다. 저장소별 정책이 더 엄격하면 해당 정책을 따르세요.

재컴파일 diff가 비어 있으면 workflow가 안전하다고 볼 수 있나요?

아닙니다. diff가 없다는 것은 그 비교에서 생성 파일 변경을 찾지 못했다는 뜻일 뿐입니다. 정확한 source revision과 compile 조건을 사용했는지, 별도의 운영 검토가 필요한지는 따로 확인해야 합니다.

frontmatter_hash는 source를 인증하는 서명인가요?

아닙니다. 공식 문서는 이를 생성 lock header의 metadata 항목으로 보여 줍니다. 이 값만으로 source의 진위, commit의 출처 또는 전체 무결성이 보장된다고 해석하지 마세요.

compiler 버전이 달라 lockfile diff가 생기면 무조건 실패인가요?

버전 차이만으로 오류라고 단정할 수는 없습니다. 사용한 버전과 옵션을 기록하고, 결과 차이가 설명되는지 검토하세요. 원인을 설명하지 못하거나 영향 범위를 판단할 수 없다면 보류가 맞습니다.

참고 자료

• GitHub Agentic Workflows generally available — Markdown 정의가 표준 Actions YAML로 compile되는 구조를 설명하는 공식 발표입니다. 여기서는 그 구조 설명만 근거로 사용했으며, 출시 상태를 workflow별 준비 완료의 증거로 사용하지 않았습니다.
• GitHub Agentic Workflows — GitHub Docs — frontmatter와 Markdown 본문의 역할, compile 후 두 파일을 기본 브랜치에 반영하는 흐름을 확인할 수 있는 공식 제품 문서입니다.
• Workflow Structure — GitHub Agentic Workflows — gh aw compile, .md/.lock.yml 파일 관계, header metadata 및 frontmatter 변경 시 재컴파일 기준을 설명합니다.
• Compilation Process — GitHub Agentic Workflows — Markdown에서 실행용 YAML이 만들어지는 컴파일 단계와 검증 범위를 설명합니다. compile 설명을 runtime 동작 전체의 보증으로 확대하지 않기 위해 함께 참고했습니다.

자료 확인일: 2026년 10월 30일. 실제 workflow의 source revision, compiler 버전, 저장소 정책은 각 repository에서 별도로 확인해 주세요.