GitHub Actions lockfiles 정식 제공: 태그와 실행 커밋을 나누어 보기

GitHub Actions의 workflow lockfiles가 2026년 10월 28일 정식 제공으로 전환됐습니다. 워크플로에 읽기 쉬운 태그·브랜치 참조를 두면서 실행할 액션의 커밋을 따로 고정하는 기능입니다. 도입을 검토한다면 고정할 대상, 업데이트를 검토할 사람, 고정 범위 밖의 입력을 나누어 보세요.

이번 글은 공식 발표와 문서를 읽고 도입 판단을 돕는 안내입니다. 확장 도구를 설치하거나 잠금 파일을 생성하고 CI를 실행한 시험 결과는 없습니다. 아래의 검토표와 가상 변경 요청은 팀이 질문을 정리하도록 직접 구성한 예시입니다.

이번 정식 제공에서 무엇이 달라졌나요?

GitHub의 10월 28일 공지는 Enterprise Cloud, 데이터 레지던시를 사용하는 Enterprise Cloud, Team, Free에서 workflow lockfiles를 정식 제공한다고 안내합니다. 액션과 전이 의존성을 고정하고 워크플로별로 점진 도입할 수 있으며, 도입된 액션의 Dependabot 버전 갱신 PR에는 대응하는 잠금 항목 갱신도 포함됩니다.

관리자의 Require lockfile 정책과 파일을 바꾸지 않는 최신 상태 확인도 소개됐습니다. GitHub는 고정이 의존성의 안전성을 판단해 주지는 않는다고 명시합니다. 현재 발표의 범위는 GitHub Actions workflow lockfiles 정식 제공 공지에서 확인할 수 있어요.

여기서 전이 의존성은 직접 선택한 액션이 다시 사용하는 액션을 가리킵니다. 따라서 검토 대상 목록을 만들 때 워크플로에서 눈에 띄는 이름만 적고 끝내지 않는 관점이 필요해요. ‘무엇을 고정했나’와 ‘그 코드가 우리 작업에 적절한가’를 별도 질문으로 남기자는 뜻입니다.

태그와 실행 커밋을 왜 따로 보나요?

GitHub Docs는 태그나 브랜치가 다른 커밋을 가리킬 수 있다고 설명합니다. 잠금 파일은 액션의 참조와 실행할 커밋, 원본 저장소의 숫자 식별자를 기록합니다. 도입된 워크플로의 액션 의존성은 잠금 파일에 있어야 하고, 고정 커밋은 원본 저장소의 기록된 태그·브랜치에서 도달 가능해야 합니다.

독자가 검토할 때는 이름과 실제 대상을 두 칸으로 적어 보는 방식을 제안합니다. 예를 들어 사람이 읽는 액션 이름·버전 표기 옆에 이번 검토에서 선택한 커밋과 확인한 근거를 붙이는 거예요. 다음 사람이 같은 이름을 봤을 때 어떤 코드를 검토했는지 알 수 있도록 남기는 메모입니다.

이때 고정된 값이라는 이유만으로 검토가 끝났다고 표시하지는 마세요. 업데이트를 택한 이유와 확인하지 못한 범위를 함께 남기면 좋겠습니다. 동작이 바뀌었는지 보지 못했다면 ‘미확인’, 원문만 읽었다면 ‘문서 확인’, 별도 환경에서 실행했다면 그 환경과 결과를 적는 식입니다. 이 구분은 제품의 자동 승인 상태가 아니라 팀에서 쓸 수 있는 자체 기록안이에요.

잠금 파일이 담당하는 범위는 어디까지인가요?

공식 문서상 잠금 파일은 해당 저장소에 정의된 워크플로의 액션 의존성을 다룹니다. 재사용 워크플로 호출 자체는 고정하지 않으며, 호출된 워크플로의 액션은 그 정의가 있는 저장소의 잠금 파일을 따릅니다. 입력값, 비밀 값, 러너 이미지 같은 다른 빌드 입력도 잠금 파일의 통제 대상이 아닙니다. 파일은 .github/workflows/actions.lock에 두고 공식 확장으로 생성하며 손으로 편집하지 말라고 안내합니다.

세부 개념은 GitHub Docs의 workflow dependency lockfiles에서 확인했습니다. 문서의 기능 설명과 실제 저장소가 그 조건을 만족하는지는 구분해야 합니다. 설정을 살펴보지 않은 상태에서 이 글만으로 현재 팀의 모든 실행 경로가 고정됐다고 판단할 수는 없어요.

자체 검토 질문	팀 메모에 남길 내용
어느 워크플로를 먼저 검토하나요?	파일 이름, 담당자, 실행 목적, 외부 시스템에 영향을 주는 단계가 있는지.
다른 워크플로를 호출하나요?	호출 대상과 그 저장소의 관리 담당자, 별도로 확인할 고정 범위.
액션 외에 무엇이 달라질 수 있나요?	입력값·실행 환경·프로젝트 의존성 등 이번 점검과 분리할 항목.
아직 확인하지 못한 것은 무엇인가요?	검토에서 제외한 경로와 이후 담당자. 빈칸을 통과로 해석하지 않기.

이 표는 GitHub의 공식 검사 결과표가 아닙니다. 기능의 책임 범위를 읽은 뒤 저장소에 맞는 질문을 만들기 위한 양식이에요. 한 줄에 여러 작업이 섞여 있으면 액션 코드 확인과 실행 환경 확인을 따로 나눠 적어도 좋습니다.

도구를 사용하기 전에 어떤 전제를 확인할까요?

공식 확장 저장소는 인증된 GitHub CLI를 전제로 하며 github.com과 데이터 레지던시 Enterprise Cloud를 지원하고 Enterprise Server는 지원하지 않는다고 안내합니다. 로컬 액션을 따라가며 고정하지 않고 컨테이너 이미지도 고정하지 않는 한계가 있습니다. 또한 온라인 검증과 오프라인의 목록 포함 여부 확인은 검사 범위가 다릅니다. 후자를 통과했다고 원본 출처까지 검증됐다고 읽으면 안 됩니다.

이 글에는 설치·인증·수정 명령을 넣지 않았습니다. 실제 적용 전에는 공식 gh-actions-lock 저장소의 설치 조건·모드·제한을 현재 사용하는 호스트와 워크플로 구성에 대조하세요. 여기서는 계정 인증, 파일 수정, 네트워크 검증을 수행하지 않았습니다.

팀의 점검 메모에도 ‘파일을 바꾸지 않음’과 ‘외부 통신을 하지 않음’을 서로 다른 조건으로 적는 방식을 제안합니다. 읽기 중심의 점검을 원한다면 작업 범위와 실행 환경을 담당자에게 먼저 확인하세요. 이번 글에서 단순히 문서를 읽은 사실을 도구의 읽기 전용 검증 성공으로 바꾸어 쓰지 않은 이유도 그 구분 때문입니다.

작은 범위부터 도입하려면 무엇을 고를까요?

첫 후보를 정할 때는 팀이 현재 동작과 담당자를 설명할 수 있는 워크플로를 고르는 방식을 제안합니다. 가장 짧은 파일이라는 이유만으로 택하기보다, 성공·실패를 어떤 증거로 확인할지와 문제가 생겼을 때 누구에게 연결할지를 먼저 적는 거예요. 중요도가 낮다는 표현도 실제 영향을 확인한 뒤 사용해야 합니다.

예를 들어 ‘테스트용 워크플로’라고 부르는 파일이 있다고 합시다. 가상의 검토 메모에는 언제 실행되는지, 어떤 파일과 외부 서비스를 사용하는지, 실패하면 병합이나 다른 작업에 영향을 주는지를 적을 수 있습니다. 이름만 보고 아무 영향이 없다고 가정하지 않는 연습입니다. 실제 저장소를 조사해 그런 동작을 발견했다는 사례는 아니에요.

그다음 이번 변경의 범위를 한 문장으로 씁니다. ‘이 워크플로의 액션 의존성 고정만 검토하며 애플리케이션 패키지 갱신과 러너 교체는 별도 변경으로 다룬다’ 같은 예시입니다. 서로 다른 변경을 나누면 검토 기록도 무엇을 승인했는지에 맞춰 쓸 수 있습니다. 변경을 나누는 것 자체가 장애 예방 효과를 보장한다는 주장은 아닙니다.

프로젝트의 패키지 설치와 캐시를 점검하는 문제도 별도로 표시하세요. 이 글의 대상은 Actions가 사용하는 액션 코드입니다. npm 설치나 캐시 복원 뒤 모듈을 찾지 못하는 문제를 보고 있다면 GitHub Actions npm 캐시·설치·작업 경로 점검 글에서 그 질문에 맞는 확인 항목을 이어서 볼 수 있습니다.

업데이트 PR에서는 어떤 질문을 남기면 좋을까요?

다음은 실제 실행이 아닌 가상의 변경 요청입니다. 담당자가 액션을 갱신하는 PR을 올렸다면 검토자는 ‘바뀐 참조는 무엇인가’, ‘고정 대상은 무엇인가’, ‘왜 지금 갱신하는가’를 각각 확인하는 메모를 남길 수 있어요. 자동으로 생성된 파일도 검토할 변경의 일부로 취급하자는 제안입니다.

가상 PR의 검토 항목	남길 수 있는 질문
변경 이유	기능 필요·유지보수·문제 대응 중 무엇이 계기이며 근거 링크가 있나요?
변경 범위	직접 선택한 액션과 함께 달라진 다른 의존성은 무엇인가요?
확인 결과	문서 확인, 파일 검증, 실제 워크플로 실행 중 어디까지 했나요?
남은 조건	실행하지 않은 경로와 추가 검토가 필요한 권한·환경은 무엇인가요?

출처와 릴리스 설명을 읽는 단계에서는 작성자가 제시한 이유와 검토자가 확인한 사실을 나눠 써 보세요. ‘업데이트가 필요하다고 함’과 ‘이 변경에서 필요한 동작을 확인함’은 같은 문장이 아닙니다. 확인한 링크와 날짜를 남기고 아직 읽지 않은 자료는 근거로 세지 않는 방식입니다.

기존에 고정해 두었다는 사실을 무기한 유지의 이유로 삼을 필요도 없습니다. 다음 갱신을 검토할 담당자와 계기를 기록하는 방식이 좋겠습니다. 날짜를 정한다면 팀의 운영 조건에 맞춰 정하세요. 이 글은 모든 팀에 같은 갱신 주기나 자동 병합 규칙을 권하지 않습니다.

관리 정책을 켜기 전에는 무엇을 정리할까요?

강제 적용을 검토하는 담당자라면 현재 도입 범위와 예외를 먼저 목록으로 적어 보세요. 전체 저장소 수를 세는 일보다 어떤 워크플로가 아직 검토되지 않았고 누가 처리할 수 있는지를 알아보는 데 초점을 두는 방법입니다. 정확히 확인하지 못한 항목은 ‘미도입’과 ‘확인 불가’를 나누어 표시하면 좋겠습니다.

현재 구성에서 가능한지 문서로 확인한 상태, 파일을 준비한 상태, 검토한 상태, 실제 실행 결과가 있는 상태도 분리해 보세요. ‘준비됨’ 한 단어만으로는 무엇이 끝났는지 알기 어렵기 때문입니다. 이 상태 이름은 이 글에서 제안하는 팀 메모이며 GitHub 제품의 공식 단계 이름은 아닙니다.

문제가 생겼을 때의 대응도 같은 검토 안에 남길 수 있어요. 변경 전 구성과 검토한 파일을 어디에서 확인할지, 누가 적용 중단이나 수정 여부를 판단할지, 어떤 결과가 있어야 다음 범위로 넓힐지 적는 겁니다. 정책을 일단 끄거나 검증 실패를 무시하는 것을 기본 해결책으로 삼지 말고 실제 원인에 맞는 공식 안내를 확인하세요.

자주 묻는 질문은 어떻게 이해하면 될까요?

잠금 파일이 있으면 보안 검토를 끝내도 되나요? 앞서 확인한 안전성 한계를 기준으로 검토 항목을 분리하세요. 어떤 대상을 선택했는지에 관한 기록과 그 대상을 사용해도 되는지에 관한 판단을 같은 체크로 합치지 않는 방식을 제안합니다.

자동 갱신 PR이면 바로 병합해도 되나요? 이 글에서는 그런 자동 병합 규칙을 제안하지 않습니다. 팀에서 정한 검토자, 확인한 변경 이유, 실제 점검 범위와 남은 조건에 따라 판단할 일입니다. 도구가 만든 파일이라는 사실을 내가 검토했다는 증거로 대신하지 마세요.

기존 설정을 전부 한 번에 바꿔야 하나요? 앞의 점진 도입 기능을 읽고 팀의 검토 가능한 범위를 먼저 고르는 방식을 제안합니다. 일정과 책임자가 없는 전면 전환을 약속하기보다, 첫 범위의 결과를 남긴 뒤 다음 대상을 결정하는 흐름으로 준비할 수 있습니다.

이번 글은 어디까지 확인했나요?

사실 기준일은 2026년 11월 1일입니다. 공식 공지·개념 문서·확장 저장소 README를 실제 읽었으며 설치·인증·잠금 파일 생성·CI 실행·보안 시험은 하지 않았습니다. 계정별 도입 상태와 현재 저장소의 호환성은 미확인입니다.

도입 검토를 시작한다면 먼저 워크플로 하나의 목적과 고정할 대상, 별도로 살펴볼 입력, 검토 담당자를 한 장에 적어 보세요. 실제 적용 결과를 남길 때도 문서 확인과 파일 준비, 검증과 실행을 구분하면 다음 검토자가 어떤 증거를 이어 받아야 하는지 알 수 있습니다.

직접 생성한 개념 이미지입니다. 실제 서비스 화면이나 구축·성능 시험 결과가 아닙니다.