GitHub Actions lockfile 설정: actions.lock으로 실행 커밋 고정하기

상황별 바로가기: 워크플로 하나에 적용 · 검증 명령 확인 · 실행 커밋 대조

2026년 10월 14일 공개 미리보기로 발표됐습니다. 미리보기 동안 CLI 옵션과 파일 형식은 적용 전에 다시 확인하세요. GitHub 공식 발표

actions.lock은 무엇을 고정하나요?

uses: owner/action@v3처럼 태그를 지정하면 나중에 그 태그가 다른 커밋을 가리킬 수 있습니다. 잠금 파일에 적용된 워크플로는 기록된 커밋으로 실행 대상을 정합니다. workflows에는 적용된 워크플로와 의존성을, dependencies에는 참조별 고정값을 기록합니다. 저장소의 숫자 ID도 함께 확인하므로 이름만 같은 다른 저장소로 바뀌는 상황을 구분합니다. 근거: 잠금 파일 개념과 구조

파일	관리 대상	생성·갱신 도구
.github/workflows/actions.lock	워크플로가 참조하는 Action 등의 실행 커밋	gh actions-lock
package-lock.json	npm으로 설치할 앱 패키지 의존성 트리	npm
이름.lock.yml	GitHub Agentic Workflows의 Markdown에서 컴파일한 실행 워크플로	gh aw compile

같은 lock이라는 이름이 붙어도 서로 대체하지 않습니다. npm 잠금 파일은 패키지 설치를, Agentic Workflows의 .lock.yml은 컴파일 결과를 다룹니다. PR 테스트 구성 자체가 필요하다면 AI 코딩 에이전트 GitHub Actions 테스트 자동화를 먼저 참고하세요. 이번 글은 그 테스트를 실행하는 Action 의존성을 고정하는 단계입니다.

지원 플랜·권한과 적용 전 확인사항

10월 14일 발표는 Free·Team·GitHub Enterprise Cloud·데이터 레지던시를 사용하는 Enterprise Cloud를 공개 대상으로 안내합니다. GitHub Enterprise Server, 즉 GHES는 현재 지원하지 않습니다. 변경을 저장하려면 저장소 쓰기 권한이 필요하고, CLI 인증 주체는 사용하는 비공개 의존성도 읽을 수 있어야 합니다. 발표의 플랜 안내 · CLI 요구 조건

일부 설정 문서의 이용 대상 표시는 Enterprise Cloud로 남아 있어 발표의 플랜 목록과 차이가 있습니다. 플랜 범위는 위 발표를 기준으로 설명하되, 실제 저장소에서 정책 메뉴 제공 여부까지 확인하세요. 미리보기 중에는 파일 형식과 CLI 옵션도 바뀔 수 있으므로 적용 날짜·확장 버전을 기록하는 편이 좋습니다.

• 고정할 Action의 현재 버전과 변경 이력을 먼저 검토합니다.
• 운영 배포 대신 수동 실행할 작은 워크플로로 시작합니다.
• 공유 워크플로가 있다면 그 정의 저장소의 잠금 파일도 확인합니다.
• 이미 적용된 Action 허용 목록과 SHA 고정 정책을 확인합니다.

1단계: gh actions-lock 확장 설치

GitHub CLI가 설치된 저장소 루트에서 시작합니다. 먼저 버전과 인증 상태를 확인하고, 인증이 없다면 대상 GitHub 호스트에 로그인하세요. 로그나 캡처에는 토큰 값을 남기지 않습니다.

gh --version
gh auth status
# 인증이 필요한 경우에만 실행
gh auth login
gh extension install github/gh-actions-lock
gh extension list
gh actions-lock --help

확장이 이미 설치돼 있다면 설치 명령 대신 gh extension upgrade gh-actions-lock로 갱신할 수 있습니다. 데이터 레지던시 호스트를 쓰는 조직은 해당 호스트에 인증하고 그 저장소 체크아웃에서 실행해야 합니다. 근거: 공식 CLI 설치·호스트 안내

2단계: 워크플로 하나만 먼저 적용

다음은 수동 실행으로 체크아웃만 확인하는 편집부 작성 예제입니다. lockfile-pilot.yml 다운로드 후 테스트 브랜치의 .github/workflows/lockfile-pilot.yml에 저장하세요. actions/checkout@v6.0.2는 구조 설명용 참조이며, 자신의 환경에서 지원되는 버전과 코드를 확인한 뒤 선택합니다.

name: Lockfile pilot

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  inspect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6.0.2
      - name: Confirm workspace
        run: test -d .git

전체 워크플로를 한꺼번에 처리하지 않고 대상 경로를 전달합니다.

gh actions-lock .github/workflows/lockfile-pilot.yml
git status --short
git diff -- .github/workflows
cat .github/workflows/actions.lock

경로를 생략한 gh actions-lock은 워크플로 디렉터리 전체를 처리합니다. 처음부터 전체 적용을 원하는 경우에만 사용하세요. 생성 파일은 직접 작성하거나 다른 저장소에서 복사하지 않습니다. 근거: 단일 워크플로 적용 절차

3단계: 잠금 파일뿐 아니라 전체 diff 검토

새 파일은 아직 추적되지 않아 git diff에 안 보일 수 있습니다. 그래서 위 예제는 status와 파일 내용도 함께 확인합니다. 최소한 다음 항목을 PR의 검토 대상으로 남기세요.

확인할 변경	판단 기준
workflows	대상 경로가 등록됐는지, 빠진 의존성이 없는지
commit	이번부터 실행할 코드인지, 변경 내용을 검토했는지
owner_id·repo_id	기존 값이 바뀌었다면 저장소 이전·정체성 변경을 조사했는지
워크플로의 uses	태그가 더 구체적인 버전으로 정리됐는지
로컬 Action 참조	./ 경로가 $/ 경로로 바뀐 파일까지 검토했는지

확장은 부분 버전 태그를 구체적인 버전으로 정리할 수 있습니다. 공식 CLI의 참조 정리 설명도 이 동작을 안내합니다. 해석 가능한 같은 저장소의 로컬 Action 참조는 $/…로 바뀔 수 있습니다. 따라서 “태그를 유지할 수 있다”는 설명을 “워크플로 파일이 전혀 바뀌지 않는다”로 이해하면 안 됩니다. 근거: 생성 후 검토할 변경

아래는 공식 CLI 저장소가 공개한 잠금 파일의 일부입니다. 이 글에서 생성한 결과가 아니며, 독자의 잠금 파일로 복사할 예제도 아닙니다. 실제 파일에서 각 값이 어떤 역할을 하는지 읽는 참고 자료입니다. 공식 저장소의 원본 파일

dependencies:
    'actions/checkout@v6.0.2':
        ref: 'v6.0.2'
        commit: 'sha1-de0fac2e4500dabe0009e67214ff5f5447ce83dd'
        owner_id: 44036562
        repo_id: 197814629

이 형식의 commit 값에는 sha1- 접두사가 붙습니다. 나중에 실행 로그와 비교할 때에는 접두사를 제외한 전체 해시를 대조하세요. 문서의 샘플 값을 자신의 결과로 기록하지 말고, 실제 CLI가 만든 파일과 diff를 보관합니다.

4단계: --verify와 --verify-local의 차이 확인

하나만 적용했다면 검증할 때에도 같은 경로를 지정합니다. 이렇게 해야 아직 적용하지 않은 다른 워크플로의 누락을 첫 적용 실패로 혼동하지 않습니다.

gh actions-lock .github/workflows/lockfile-pilot.yml --verify

현재 공식 CLI 구현은 정상 완료를 종료 코드 0, 남아 있는 차단 항목을 1, 잘못된 옵션·네트워크 등 도구 실행 실패를 2로 구분합니다. CI에서는 검증 실패 코드가 뒤의 출력 명령에 가려지지 않도록 하세요. 근거: 명령 종료 코드 구현

명령	역할	해석할 때 주의
gh actions-lock [경로]	필요한 의존성을 해석하고 파일 갱신	일반 실행만으로 기존 고정값이 모두 최신화되지는 않음
gh actions-lock [경로] --verify	워크플로·잠금 파일을 고치지 않고 원격 확인을 포함해 검증	인증이 필요하며 실제 출력과 종료 코드를 보관
gh actions-lock [경로] --verify-local	오프라인으로 잠금 항목의 포함 여부 확인	원격 커밋·저장소의 신뢰성을 검증하는 결과는 아님

오프라인 검사 통과는 원격 검증이나 Actions 실행 성공의 근거로 사용할 수 없습니다. 공식 검증 구현에서 두 검사의 범위를 확인할 수 있습니다.

브랜치나 부분 버전 태그가 앞으로 진행해도 기존 커밋은 일반 실행에서 자동으로 새 커밋으로 바뀌지 않습니다. 반면 전체 버전 태그가 다른 커밋으로 옮겨졌거나 기록된 커밋이 해당 참조의 이력에서 사라지면 검증에 문제가 생길 수 있습니다. 실패했다고 바로 덮어쓰기보다 upstream 이력을 먼저 확인하세요. 근거: 고정값 유지와 검증 동작

5단계: 실제 실행 커밋까지 대조하기

검증 명령 다음에는 실제 실행을 확인합니다. 잠금 파일이 포함된 저장소 커밋과 다운로드한 Action의 커밋을 각각 기록하세요.

1. 검토한 워크플로와 actions.lock을 같은 변경으로 커밋합니다.
2. 테스트 저장소의 기본 브랜치에 수동 실행 워크플로가 등록됐는지 확인하고, Actions의 Run workflow에서 시험할 브랜치를 선택합니다.
3. 해당 실행이 사용하는 저장소 커밋에 잠금 파일과 대상 워크플로 등록이 포함됐는지 확인합니다.
4. runner 준비·Action 다운로드 로그에서 참조와 해시가 제공되면 전체 SHA를 기록합니다.
5. 그 실행 커밋의 잠금 파일에 있는 commit과 대조하고 실행 URL을 보관합니다.

수동 실행 버튼을 사용하려면 워크플로가 기본 브랜치에 있어야 합니다. 근거: 수동 실행 조건·브랜치 선택

로그에서 Action SHA를 확인하지 못했다면 “실행 성공, Action SHA 대조 미완료”로 남기세요. 앱의 체크아웃 커밋이나 git rev-parse HEAD 결과는 Action 자체의 커밋과 대상이 다릅니다. 두 해시를 비교해서 일치 여부를 판단하면 안 됩니다.

Dependabot으로 버전과 잠금 파일 함께 갱신

GitHub Actions 버전 업데이트를 활성화하면, 이미 잠금 파일에 적용된 워크플로의 Action 버전을 올릴 때 대응하는 잠금 항목도 같은 PR에서 갱신합니다. Dependabot이 미적용 워크플로의 최초 등록까지 대신하는 것은 아닙니다. 근거: 잠금 파일과 Dependabot 연동

다음은 .github/dependabot.yml에 넣을 주간 점검 예제입니다. 기존 파일이 있으면 덮어쓰지 말고 updates에 항목을 병합하세요. 설정 예제 다운로드

version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly

github-actions 생태계의 directory는 /로 지정합니다. 근거: Dependabot Actions 설정 PR에서는 워크플로 참조·잠금 commit·릴리스 변경 내용을 함께 검토하고 다시 검증하세요. 브랜치나 부분 태그를 수동으로 다시 해석할 때는 이력을 검토한 뒤 gh actions-lock --relock을 사용합니다. 기존 커밋이 사라진 상황에서 --accept-moved를 오류 해소용 기본 옵션으로 붙이지 마세요. 근거: 재고정 옵션

재사용 워크플로 내부까지 전부 고정되나요?

다른 저장소의 재사용 워크플로를 호출할 때에는 호출 대상의 커밋과 호출된 워크플로 내부 Action을 나눠 봐야 합니다. 내부 의존성은 워크플로를 정의한 저장소의 잠금 파일이 담당합니다. 공식 문서는 공용 워크플로 정의 저장소부터 적용하는 순서를 권장합니다. 적용 범위 · 공유 저장소 적용 순서

호출 관계	확인할 위치
앱 저장소 → 원격 Action	앱 저장소 actions.lock의 해당 의존성
Action → 다른 Action	전이 의존성이 잠금 파일에 반영됐는지
앱 저장소 → 공용 재사용 워크플로	앱 저장소의 호출 대상 고정값
공용 재사용 워크플로 → 내부 Action	그 워크플로가 정의된 저장소의 잠금 파일

운영 문서에는 “앱 저장소는 적용 완료, 공용 워크플로 정의 저장소는 미확인”처럼 범위를 적으세요. 파일 하나가 생성됐다는 이유로 조직 전체 공급망을 검증했다고 표현하면 실제 미적용 구간을 놓치기 쉽습니다.

기존 SHA 고정 방식·Require lockfile 정책과 비교

워크플로에 전체 SHA를 직접 적는 방식은 참조 위치에 실행 커밋을 표시합니다. actions.lock은 워크플로의 가독성을 유지하면서 전이 의존성과 저장소 식별 정보를 함께 관리하는 선택지입니다. GitHub는 잠금 파일을 채택한 워크플로에서는 uses에 별도 SHA를 적을 필요가 없다고 설명합니다. 근거: SHA 직접 고정과 비교

기존의 전체 SHA 고정 요구 정책은 유지할 수 있습니다. 잠금 파일이 담당하는 의존성에는 고정된 SHA로 정책을 평가하고, 아직 적용하지 않은 워크플로에는 기존 요구를 유지합니다. 관리자라면 Settings → Actions → Policies에서 제공되는 Require lockfile의 대상과 상태도 확인하세요. 정책 제공 범위는 저장소 공개 여부와 플랜에 따라 확인이 필요합니다. 근거: 정책 설정과 SHA 요구 병행

Require lockfile을 Active로 설정하면 대상 중 준비되지 않은 워크플로의 실행이 차단될 수 있습니다. 먼저 적용한 저장소·워크플로로 범위를 좁히세요. Evaluate 모드는 Enterprise에서만 제공되므로 모든 Free·Team 저장소에서 시험 모드를 쓸 수 있다고 가정하면 안 됩니다. 정책과 별개로 PR의 --verify 검사는 유지하는 편이 작성 단계에서 누락을 찾기 쉽습니다. 근거: 단계별 정책 적용

설정·검증에 실패하면 확인할 순서

관측한 상황	다음 확인
명령 또는 확장을 찾지 못함	gh 설치·확장 목록·현재 --help
인증·원격 의존성 해석 실패	gh 호스트·로그인 상태·비공개 의존성 읽기 권한
대상 워크플로가 잠금 목록에 없음	지정한 경로와 생성 명령의 경고·누락 항목
로컬 ./ Action 때문에 건너뜀	저장소 루트 기준 경로와 실제 action.yml·action.yaml 존재
전체 버전 태그·커밋 검증 실패	upstream 이동·삭제·이전 이력, 확장 버전
CLI는 통과하지만 실행 정책이 거부	잠긴 SHA와 허용 목록, Require lockfile 대상
공유 워크플로의 내부만 미확인	정의 저장소·호출된 커밋의 잠금 파일 적용 여부

로컬 ./ 참조가 지원되지 않는다는 메시지는 경로가 실제 Action으로 해석되는지도 확인해야 합니다. 현재 문서는 이 경로가 참조 파일의 폴더가 아닌 저장소 루트를 기준으로 한다고 안내합니다. 근거: 로컬 경로 진단 Action 허용 목록 역시 잠긴 SHA를 기준으로 평가되므로, 태그만 허용했던 항목이 그대로 일치하지 않을 수 있습니다. 범위를 불필요하게 넓히기보다 허용할 전체 SHA 등 기존 정책에 맞는 항목을 검토하세요.

어디까지 적용했는지 남기는 완료 기준

완료 단계	남길 증거	아직 확인하지 못한 범위
생성·검토	대상 경로가 등록된 잠금 파일과 전체 diff	원격 검증·실제 실행
검증	같은 워크플로 경로의 --verify 출력과 종료 코드 0	runner가 받은 Action 커밋
실행 대조	실행 URL과 그 실행의 잠금 commit·Action SHA 일치 기록	다른 워크플로·공유 정의 저장소의 적용 여부

GitHub Actions lockfile 검토 기록표 CSV에 환경·생성 diff·검증 출력·실행 SHA 대조·공유 워크플로 범위를 기록할 수 있습니다. 빈 기록표이므로 실제 출력과 실행 URL을 채워 사용하세요. 미리보기 업데이트 후에는 확장 버전과 현재 --help를 비교하고 재검증합니다.

이 파일이 고정하는 범위와 별개로 앱 패키지, runner 이미지, run 단계에서 내려받는 외부 스크립트는 따로 관리해야 합니다. 잠금 파일은 검토 대상을 명확하게 만드는 장치입니다. 의존성 코드 검토·업데이트·최소 권한 운영을 함께 적용해야 유용합니다.

자주 묻는 질문

package-lock.json이나 .lock.yml과 무엇이 다른가요?

package-lock.json은 npm 패키지 설치 트리를 기록합니다. Agentic Workflows의 .lock.yml은 Markdown 정의를 컴파일한 실행 워크플로입니다. actions.lock은 워크플로가 사용하는 Action 등의 커밋을 기록하므로 서로 대체하지 않습니다.

기존 SHA 고정 방식과 어떻게 비교하나요?

전체 SHA를 uses에 직접 적는 방식과 달리, 태그를 읽기 쉽게 두고 실행 커밋을 잠금 파일에서 관리할 수 있습니다. 전이 의존성과 저장소 ID도 함께 다룹니다. 잠금 적용 전후 모두 코드 검토는 필요하고, 미적용 워크플로의 SHA 고정 정책을 급히 해제할 이유는 없습니다.

재사용 워크플로 내부 의존성도 같은 파일로 전부 고정되나요?

아닙니다. 호출 대상 워크플로의 커밋과 내부 Action은 구분해야 합니다. 다른 저장소에서 정의한 재사용 워크플로의 내부 의존성은 그 저장소의 잠금 파일이 담당하므로 공용 정의 저장소의 적용 상태도 별도로 확인하세요.