GitHub Actions lockfile 정식 출시: 태그는 읽기 쉽게, 실행 커밋은 고정하기

여러 의존성을 고정된 기준에 묶어 두는 모습을 표현한 생성형 개념 이미지다. 실제 GitHub 화면이 아니다.

워크플로 YAML을 바꾸지 않았는데 다음 빌드에서 다른 액션 코드가 실행될 수 있다. uses: owner/action@v3의 태그가 다른 커밋을 가리키게 되면 생기는 일이다. 액션 의존성 lockfile을 도입하면 읽기 쉬운 참조를 유지하면서 실제 실행 커밋을 검토한 상태로 고정할 수 있다.

GitHub는 October 28, 2026 workflow dependency lockfiles의 정식 출시를 발표했다. 발표 기준 지원 플랜은 Free·Team·Enterprise Cloud와 data residency 환경이다. GitHub Enterprise Server는 공식 CLI의 지원 대상이 아니다. GA 발표, CLI 지원 범위

어떤 코드가 실행되는지 고정한다

저장소의 .github/workflows/actions.lock은 워크플로가 사용하는 액션과 그 액션이 다시 사용하는 의존성의 커밋을 기록한다. 도입한 워크플로는 필요한 항목이 lockfile에 있어야 하며, 실행 시 잠긴 커밋을 사용한다.

참조 이름뿐 아니라 출처 저장소의 식별자도 기록한다. 같은 이름 뒤의 저장소가 바뀌는 상황을 확인하기 위한 정보다. 단, lockfile이 그 커밋의 코드를 안전하다고 판정해 주지는 않는다. 의존성 코드 검토와 업데이트 절차는 여전히 필요하다. 동작 원리

이번 기능은 Agentic Workflows의 *.lock.yml과 구분해야 한다. 앞서 다룬 *.lock.yml은 Markdown을 컴파일한 실행 정의이고, 여기서 다루는 actions.lock은 액션 의존성 목록이다. GitHub Agentic Workflows 정식 출시: Markdown 자동화와 쓰기 권한을 분리하기

첫 적용은 워크플로 하나부터

아래는 공식 문서에 근거한 도입 예제다. 이 글을 작성하면서 확장을 설치하거나 저장소에 실행하지 않았다. 기존 인증과 저장소 쓰기 권한이 있는 승인된 테스트 환경에서 진행한다.

도구는 lockfile만 추가하는 것이 아니다. 넓은 버전 참조를 더 구체적인 태그로 바꿀 수 있으므로 전체 diff를 확인해야 한다. 생성 파일을 손으로 수정하기보다 워크플로 원본을 고치고 다시 생성한다. 설정 절차

조직이 허용 액션 목록을 운영한다면 이 부분을 먼저 점검한다. 도입 이후에는 잠긴 SHA로 허용 여부를 평가하므로 기존의 태그 기반 허용 규칙과 충돌할 수 있다. 편의를 위해 허용 범위를 넓히기보다 필요한 커밋과 정책을 함께 리뷰하는 편이 좋다.

검사와 업데이트 명령을 분리한다

--verify-local은 빠른 로컬 검사에 유용하지만 출처까지 검증하지는 않는다. 두 명령을 같은 수준의 확인으로 취급하지 않는다.

반면 --relock은 움직인 참조를 현재 커밋으로 갱신하는 작업이다. 검사 실패를 없애려고 자동 실행하면 검토하지 않은 코드로 고정점이 바뀔 수 있다. --accept-moved도 무조건 통과시키는 자동화에 넣지 않는다. CLI 모드와 제한

이 글에서 제안하는 PR 검토 기준은 세 가지다.

워크플로에 새로 등장한 액션이 lockfile에도 포함됐는가.

바뀐 커밋이 의도한 버전과 변경 내역을 가리키는가.

잠금 변경과 무관한 권한·트리거·비밀값 사용이 함께 추가되지 않았는가.

단순히 검사가 통과했다는 사실보다 변경된 실행 대상을 이해하는 것이 중요하다.

재사용 워크플로는 별도로 확인한다

현재 공식 문서는 jobs.<job_id>.uses로 호출하는 재사용 워크플로 자체를 이 lockfile이 고정하지 않는다고 설명한다. 호출 참조는 전체 commit SHA로 고정하고, 내부 액션은 재사용 워크플로가 정의된 저장소의 lockfile로 관리해야 한다. 호출하는 저장소의 lockfile이 내부까지 대신 덮어주지 않는다. 적용 경계

로컬 경로 액션과 컨테이너 이미지에도 별도 제약이 있다. 특히 컨테이너 이미지는 이 도구의 잠금 대상이 아니다. 러너 이미지, 입력값, 비밀값까지 고정되는 것도 아니므로 “전체 빌드가 완전히 재현 가능해졌다”라고 확대 해석하면 안 된다. CLI 제한

강제 정책은 준비가 끝난 뒤 켠다

Dependabot은 이미 도입한 워크플로의 액션 버전을 올릴 때 관련 lockfile 항목도 같은 PR에서 갱신한다. 그러나 아직 등록되지 않은 워크플로를 새로 등록해 주지는 않는다.

Require lockfile 정책을 먼저 활성화하면 준비되지 않은 대상 워크플로가 차단될 수 있다. 개별 워크플로 생성·검증, 허용 규칙 점검, 테스트 실행을 마친 뒤 강제 범위를 넓히는 순서가 낫다. Enterprise Cloud에서는 Evaluate 모드와 Policy insights를 활용할 수 있지만 이 모드를 모든 플랜에서 사용할 수 있다고 가정하지 않는다. 정책 도입 가이드

운영 기준으로는 신규 워크플로를 추가할 때 잠금 등록도 함께 검토하고, lockfile 변경을 리뷰할 담당자를 정하는 것을 권한다. 의존성을 고정한 뒤 업데이트를 멈추는 것이 아니라, 변경을 눈에 보이게 만드는 데 목적을 두면 된다.