GitHub Actions 잠금 파일(actions.lock): 설정 방법과 공급망 보안 주의점

GitHub Actions 잠금 파일 원리를 설명하는 AI 생성 이미지, 실제 GitHub 제품 화면이 아닌 예시 — AI 생성 개념 이미지: 실제 GitHub UI·실행 결과 화면이 아닙니다.

GitHub Actions가 의존성 잠금 파일 기능을 공개 미리보기로 제공한다. 워크플로 코드 검토 후 태그가 이동하더라도 검토한 커밋이 실행되도록 하는 방식이다. 실제 사용 전 지원 범위와 한계를 함께 확인해야 한다.

왜 잠금 파일이 필요한가

GitHub는 2026년 10월 14일 GitHub Actions 잠금 파일 기능을 공개 미리보기로 소개했다. GitHub Actions 공급망 보안에서 중요한 문제는 워크플로의 uses: 참조가 고정된 것처럼 보여도 태그나 브랜치가 다른 커밋을 가리킬 수 있다는 점이다. 리뷰를 마친 뒤 상위 저장소의 태그가 이동하면, 해당 워크플로는 원래 확인한 코드와 다른 코드를 실행할 가능성이 있다. GitHub Actions 커밋 고정은 이 위험을 줄이기 위한 접근이다. actions.lock은 기존 워크플로에서 읽기 쉬운 버전 표기를 유지하면서 실제 실행 대상을 잠금 파일에 기록된 커밋으로 연결한다. 이는 작업 흐름의 재현성을 높이지만, 잠근 코드 자체가 안전하다는 증명은 아니다.

지원 요금제와 공개 미리보기 범위

GitHub의 2026년 10월 14일 공식 상세 공지에는 Enterprise Cloud와 Enterprise Cloud with data residency가 공개 미리보기 대상으로 명시되어 있다. 반면 같은 달 공식 변경이력 목록에는 Team·Free까지 포함되어 공식 페이지 간 지원 요금제 표기가 일치하지 않는다. 따라서 “GitHub Actions lockfile Free 요금제” 및 Team 요금제의 실제 이용 가능 여부를 확정할 수 없다. 사용 전에 해당 조직·저장소에서 기능 노출 여부 및 GitHub 최신 공식 문서를 확인해야 한다. 관리자의 Require lockfile 정책 적용 권한도 계정 유형별로 별도 확인해야 하며, 공개 미리보기 기능은 변경될 수 있다.

actions.lock 생성과 검증 절차

GitHub Actions lockfile 적용 방법을 이해하려면 .github/workflows/actions.lock과 gh actions-lock 두 요소를 구분해야 한다. 전자는 저장소 안에 생성되는 의존성 잠금 파일이고 후자는 이를 생성·관리하기 위한 GitHub CLI 확장이다. GitHub의 시작 안내는 확장 프로그램을 공식 공개 저장소에서 설치하고, 생성된 잠금 파일과 워크플로 변경 사항을 검토한 다음 커밋하도록 설명한다. GitHub 문서는 잠금 파일을 직접 손으로 수정하지 말라고 안내한다. gh actions-lock --verify를 활용한 최신성 검사도 문서에 설명돼 있다. 다만 여기에 적힌 명령과 절차는 공식 문서 요약이며, 이 글의 작성 과정에서 특정 운영 저장소나 CLI 환경에 직접 실행해 테스트한 결과는 아니다. 사용자는 설치된 확장 버전의 도움말과 문서를 먼저 확인해야 한다.

전이 의존성과 재사용 워크플로 예외

직접 참조된 액션 외에 액션이 내부에서 호출하는 전이 의존성도 잠금 대상에 포함될 수 있다. 하지만 GitHub Actions 재사용 워크플로 의존성에는 중요한 경계가 있다. 재사용 워크플로를 참조하는 측의 잠금 파일은 해당 재사용 워크플로를 참조 대상으로 기록하지만, 재사용 워크플로 내부에서 사용하는 의존성은 그 워크플로가 정의된 저장소의 잠금 파일에서 관리된다. 잠금 파일을 도입했다고 모든 외부 코드가 안전해지는 것은 아니므로, 코드 검토와 최소 권한, 업데이트 검토를 병행해야 한다.

Dependabot과 조직 정책 운영

Dependabot 잠금 파일 갱신은 업데이트의 일관성을 유지하는 데 도움이 된다. GitHub 발표에 따르면 이미 잠금 파일에 온보딩된 워크플로에서 Dependabot이 액션 버전 업데이트 PR을 만들면 대응하는 잠금 항목도 같은 PR에서 다시 생성한다. 운영 담당자는 PR에서 버전과 커밋 변화가 합당한지 함께 검토할 수 있다. GitHub는 Require lockfile 정책의 공개 미리보기도 소개했다. 다만 조직 전체에 정책을 강제하기 전에 해당 요금제와 관리자 권한, 현재 제공되는 정책 화면과 적용 범위를 공식 문서에서 확인해야 한다. 구체적인 정책 활성화 성공 여부는 이 글에서 테스트하지 않았다.