GitHub Actions workflow lockfile 정식 제공, 태그 참조는 고정 커밋으로 실행
GitHub는 2026년 10월 28일 GitHub Actions workflow lockfile을 공개 프리뷰에서 일반 제공으로 전환했습니다. 워크플로에는 읽기 쉬운 태그나 브랜치 참조를 두고 actions.lock에 액션과 전이 의존성의 커밋을 기록해 해당 코드를 실행하며, Dependabot은 등록된 워크플로의 잠금 항목도 같은 PR에서 갱신합니다. 재사용 워크플로 호출과 러너 이미지, 입력값, 시크릿은 잠금 범위에서 제외됩니다.
본문
GitHub는 2026년 10월 28일 GitHub Actions workflow dependency lockfile을 일반 제공으로 전환한다고 발표했습니다. 공개 프리뷰에 있던 기능을 GitHub Free, Team, Enterprise Cloud, Enterprise Cloud with data residency 요금제에서 사용할 수 있게 했습니다. 워크플로 파일에는 읽기 쉬운 태그나 브랜치 참조를 두고 별도 lockfile에 액션 코드의 정확한 커밋을 기록해, 실행 때 해당 커밋을 사용합니다.
읽기 쉬운 참조와 실행할 커밋을 분리합니다
GitHub Actions 워크플로는 저장소를 가져오고, 코드를 빌드하고, 테스트하거나 배포하는 과정에서 다른 저장소의 액션을 실행합니다. 예를 들어 uses: actions/checkout@v4처럼 태그를 적으면 파일은 읽기 쉽지만 태그가 다른 커밋을 가리키도록 바뀔 수 있습니다. 이때 워크플로 파일은 그대로인데 실행되는 액션 코드는 달라질 수 있습니다.
워크플로 YAML에 40자리 커밋 SHA를 직접 적으면 참조를 고정할 수 있습니다. 반면 긴 SHA는 파일의 가독성을 낮추고 액션을 갱신할 때 해당 줄도 수정해야 합니다. workflow lockfile은 액션을 부르는 YAML의 참조와 실제 실행할 커밋 정보를 분리합니다. YAML에는 이해하기 쉬운 버전 참조를 남기고 .github/workflows/actions.lock에는 해당 참조가 해석된 커밋을 기록합니다.
lockfile은 워크플로별 의존성 목록과 각 의존성의 참조, 커밋, 저장소 소유자 ID와 저장소 ID를 담습니다. 저장소 ID를 이용해 이름 뒤의 원본 저장소가 처음 기록한 곳과 같은지 확인합니다. 액션이 다른 액션을 사용하는 경우 그 전이 의존성도 기록합니다. 실행할 때 Actions는 태그가 새 커밋을 가리키더라도 잠금 파일에 적힌 커밋의 액션 코드를 선택합니다.
잠근 커밋은 기록된 태그나 브랜치에서 접근 가능해야 합니다. 원본 저장소에서 해당 커밋이 그 참조로 더는 확인되지 않으면 워크플로 실행이 거부됩니다. 따라서 참조가 움직여도 새 커밋으로 조용히 바뀌지 않으며, upstream에서 기존 커밋을 제거하면 실행이 거부될 수 있습니다.
생성·등록 뒤 업데이트를 함께 관리합니다
저장소에 GitHub CLI와 gh-actions-lock 확장 프로그램을 설치한 뒤 gh actions-lock을 실행하면 .github/workflows/actions.lock을 생성합니다. 저장소의 워크플로 전체를 처리하거나 파일 경로를 지정해 하나씩 등록할 수 있습니다. 확장 프로그램은 워크플로의 참조를 더 구체적인 버전으로 바꿀 수도 있습니다. GitHub는 lockfile뿐 아니라 전체 변경 내용을 검토한 뒤 커밋하도록 안내합니다.
등록된 워크플로는 사용하는 모든 액션 의존성이 lockfile에 들어 있어야 실행됩니다. 저장소·조직·엔터프라이즈 관리자는 Require lockfile 정책으로 워크플로 등록을 요구할 수 있고, CI 검사에서 lockfile의 최신 상태도 확인할 수 있습니다. lockfile 생성과 관리 정책 적용은 별도 단계이므로 관리자는 저장소별로 적용 수준을 정합니다.
액션 업데이트는 Dependabot과 연결됩니다. Dependabot이 등록된 워크플로에서 지원되는 액션의 버전을 올리는 PR을 만들면 일치하는 lockfile 항목도 같은 PR에서 다시 생성합니다. 등록하지 않은 워크플로의 업데이트는 lockfile에 반영되지 않습니다. 브랜치나 v3 같은 부분 버전 참조가 바뀌면 기존 잠금 커밋을 유지하고 확장 프로그램이 참조 이동을 알립니다. 새 코드로 갱신할 때는 upstream 변경을 검토한 뒤 gh actions-lock --relock을 실행합니다. 전체 버전 태그가 잠근 커밋에서 다른 커밋으로 바뀌면 오류가 발생하며, 다시 잠그거나 워크플로 참조를 바꿔야 합니다.
적용 범위는 액션 코드입니다
lockfile은 워크플로가 사용하는 액션 코드와 그 전이 의존성을 다룹니다. jobs.<job_id>.uses로 호출하는 재사용 워크플로는 이 lockfile에 포함되지 않습니다. 재사용 워크플로 내부의 액션은 그 워크플로가 정의된 저장소의 lockfile이 다룹니다.
러너 이미지, 액션에 넘기는 입력값, 시크릿은 lockfile에 기록되지 않습니다. 생성 시점에 이미 악성인 액션 코드도 잠금 파일이 판별하지 않습니다. GitHub가 일반 제공한 기능은 긴 SHA를 워크플로 파일마다 직접 적지 않고도 액션 의존성의 실행 커밋을 따로 기록하고 갱신할 수 있게 합니다.
자료: GitHub Changelog, GitHub Docs / 정리·해설: Trawling