2026년 10월 14일, GitHub는 workflow dependency lockfile을 공개 미리 보기로 발표했습니다(공식 발표). 결론은 간단합니다. GitHub Actions workflow lockfile은 연결된 Actions 의존성의 커밋을 고정하지만 Mac Runner, macOS, Xcode 환경은 고정하지 않습니다. 기존 macOS CI에서는 의존성 잠금과 실행 환경 관리를 따로 운영해야 합니다.
이 글은 Action 태그나 브랜치 변경이 빌드에 미칠 영향을 걱정하는 CI 엔지니어, 미리 보기 기능의 단계적 도입을 검토하는 DevOps 엔지니어, Runner와 의존성 정책을 맡은 플랫폼 담당자를 위한 안내입니다.
GitHub Actions workflow lockfile의 잠금 범위
워크플로에서 Action을 태그나 브랜치로 참조하면, 그 이름이 가리키는 커밋은 시간이 지나며 달라질 수 있습니다. lockfile은 지원되는 워크플로 의존성의 커밋 정보를 기록하므로, 검토 시점의 참조와 실제 실행에서 사용될 의존성을 대조할 수 있게 합니다. 단, 참조를 고정한다고 해서 그 코드가 안전하다는 뜻은 아닙니다. GitHub의 lockfile 설명은 이 기능을 의존성 추적과 검토의 수단으로 안내합니다.
| 시나리오 | lockfile이 기록하는 범위 | 별도로 관리할 대상 |
|---|---|---|
| 워크플로가 Action을 직접 호출 | 연결된 Action의 의존성 커밋 | Action 코드의 안전성, 워크플로 권한 |
| Action이 다른 Action을 호출 | 지원되는 전달 의존성의 커밋 정보 | 새로 추가되거나 바뀐 하위 의존성 검토 |
| 재사용 워크플로 호출 | 호출 워크플로 쪽에서 관리하는 의존성 범위 | 재사용 워크플로 정의 저장소의 의존성 |
직접 참조만 검토하면 놓치는 변경
워크플로에 보이는 uses 항목은 시작점일 뿐입니다. Action이 내부에서 다른 Action을 호출한다면 전달 의존성도 검토 대상입니다. lockfile 변경을 검토할 때는 최상위 참조만 비교하지 말고, 기록된 의존성 항목이 늘거나 바뀌었는지 살펴야 합니다.
steps:
- uses: example/build-action@v2
위 코드는 설명용 예시입니다. 태그가 같아도 그 이름이 가리키는 커밋이 달라질 수 있으므로, 코드 리뷰에서는 워크플로 선언과 lockfile 변경을 함께 확인합니다. 공식 안내는 lockfile을 만들고 관리하는 절차와 적용 범위를 설명합니다(lockfile 설정 및 유지 안내).
주의: lockfile 차이가 없다는 사실만으로 Action 코드의 안전성, 저장소의 신뢰성 또는 실행 권한이 검증된 것은 아닙니다. 잠금 결과와 코드 검토는 별개입니다.
재사용 워크플로는 정의한 저장소에서 관리합니다
호출 워크플로와 재사용 워크플로가 서로 다른 저장소에 있으면, 어느 쪽이 의존성을 소유하는지 먼저 나눠야 합니다. 호출하는 쪽은 자신이 정의한 워크플로와 그에 연결된 의존성을 관리합니다. 재사용 워크플로 내부에서 호출하는 Action은 해당 워크플로를 정의하고 유지하는 저장소에서 관리하는 범위입니다. 공식 문서의 잠금 범위 설명을 기준으로 저장소별 책임을 구분하세요.
| 저장소 상황 | lockfile을 생성·검토할 위치 | 리뷰에서 확인할 점 |
|---|---|---|
| 한 저장소 안에서 워크플로와 Action을 관리 | 해당 저장소 | 직접 참조와 전달 의존성의 변경 |
| 호출 워크플로와 재사용 워크플로가 별도 저장소 | 각 워크플로를 관리하는 저장소 | 호출부의 변경과 재사용 워크플로 내부 변경을 분리 |
| 여러 팀이 공용 워크플로를 관리 | 공용 워크플로 정의 저장소와 호출 저장소 | 책임 팀, 변경 승인자, 업데이트 전달 방식 |
따라서 호출 저장소의 lockfile 하나가 다른 저장소의 내부 구현까지 대신 관리한다고 가정하면 안 됩니다. 공용 워크플로를 바꾸는 팀은 그 저장소에서 자체 의존성 차이를 검토하고, 호출 팀은 참조하는 워크플로 변경을 확인하는 식으로 책임을 나눕니다.
macOS CI의 실행 환경은 별도 관리 대상입니다
lockfile은 워크플로 의존성 커밋을 기록하는 기능이지 Runner 이미지 목록이 아닙니다. runs-on에서 지정하는 Runner는 워크플로 실행 대상을 고르는 설정입니다. GitHub 문서에서도 워크플로 구문과 Runner 선택, 호스팅 Runner의 이미지와 환경을 별도 주제로 설명합니다.
| 빌드 입력 | workflow dependency lockfile로 고정 | 필요한 별도 관리 |
|---|---|---|
| Action 의존성 커밋 | 지원 범위에 포함 | lockfile 차이와 코드 검토 |
runs-on으로 고른 Runner |
고정 대상이 아님 | 레이블과 Runner 제공 방식을 검토 |
| macOS 이미지와 시스템 | 고정 대상이 아님 | 이미지 변경과 실행 환경 기록 |
| Xcode 및 SDK | 고정 대상이 아님 | 설치 버전 선택, 확인, 환경 유지 |
GitHub 호스팅 Runner를 쓰든 자체 운영 Runner를 쓰든 이 구분은 같습니다. 자체 운영 환경을 관리한다면 자체 호스팅 Runner 문서에 따라 Runner의 운영 경계를 별도로 다뤄야 합니다. Xcode 빌드 결과를 재현해야 한다면 Runner 이미지와 도구 모음 관리 방식을 정하고, 실제 작업에서 사용한 Xcode와 SDK를 로그나 빌드 기록에 남깁니다.
macOS CI에서 의존성 참조가 안정되어도 Runner 이미지나 도구 버전이 바뀌면 결과가 달라질 수 있습니다. lockfile 적용을 전체 빌드 환경의 재현성 확보로 간주하지 마세요.
lockfile 업데이트는 자동화 이후에도 검토해야 합니다
Action 참조를 업그레이드했다면 lockfile도 함께 갱신하고, 두 변경이 일치하는지 확인해야 합니다. GitHub는 미리 보기 기능의 설정과 유지 절차를 안내하며, Dependabot 버전 업데이트 문서에서 자동 업데이트가 다루는 범위를 설명합니다. 자동으로 만든 변경도 검토와 테스트를 거쳐야 합니다. 업데이트가 열렸다는 사실은 승인이나 보안 검증을 뜻하지 않습니다.
| 변경 상황 | 해야 할 일 | 통과 판단 |
|---|---|---|
| Action 참조를 새 버전으로 변경 | 공식 절차에 따라 lockfile도 갱신 | 선언과 잠금 정보가 서로 맞음 |
| lockfile에 예상하지 않은 의존성 차이 발생 | 전달 의존성과 변경 이유 확인 | 리뷰에서 새 의존성을 설명할 수 있음 |
| 자동 업데이트 제안 도착 | 영향 범위와 실행 결과 검토 | 팀의 테스트와 승인 기준 충족 |
| lockfile이 오래되었거나 검증에 실패 | 선언과 잠금 정보를 다시 맞추고 검증 | 오래된 항목이나 불일치가 남지 않음 |
단계별로 도입 범위를 넓히기
- 대상 저장소를 고릅니다. macOS/Xcode 빌드가 있고 Action 변경을 검토하는 팀이 정해진 저장소부터 시작합니다.
- 현재 워크플로 참조를 살핍니다. 직접 Action뿐 아니라 재사용 워크플로와 전달 의존성이 있는지 확인합니다.
- 공식 설정 절차에 따라 lockfile을 도입합니다. 생성 방법과 검증 방법은 공개 미리 보기 문서를 기준으로 확인합니다. 미리 보기 중에는 동작이나 지원 범위가 달라질 수 있으므로 오래된 내부 절차를 그대로 신뢰하지 않습니다.
- 변경 검토 기준을 둡니다. 워크플로 참조와 lockfile 차이를 함께 리뷰하고, 새 의존성이나 설명되지 않는 변경은 승인 전에 확인합니다.
- 검증 결과를 기록합니다. lockfile 검증 결과와 실제 macOS 빌드 결과를 구분해 남깁니다. 전자는 의존성 잠금 상태, 후자는 Runner 환경에서의 실행 확인입니다.
- 다른 저장소로 확대합니다. 시험 운영에서 업데이트와 리뷰가 안정적으로 이어지는지 확인한 뒤 적용 범위를 늘립니다.
조직 정책을 적용할 때도 범위를 먼저 확인해야 합니다. 워크플로 실행 제어 문서에서 설정 가능한 정책을 확인하되, 정책이 모든 저장소와 워크플로에 자동으로 같은 방식으로 적용된다고 추정하지 마세요.
도입 여부는 다음 조건으로 결정합니다
- Action 참조 변경을 검토 가능한 커밋 기록으로 관리하려는 저장소라면, 미리 보기 상태와 지원 범위를 확인한 뒤 한 저장소에서 시험합니다.
- 재사용 워크플로가 다른 저장소에 있다면, 호출 저장소와 정의 저장소의 담당자를 나누고 각 저장소에서 책임 범위를 확인합니다.
- 필요한 목표가 macOS 이미지나 Xcode 버전의 재현이라면, lockfile만으로 해결하려 하지 말고 Runner 환경 관리 방식을 별도로 마련합니다.
- lockfile을 보안 승인이나 악성 Action 차단의 대체물로 쓰려는 경우라면, 적용을 보류하고 코드 및 권한 검토와 실행 정책을 함께 설계합니다. GitHub의 Actions 안전 사용 지침도 잠금 기능과 별도로 검토해야 합니다.
2026년 10월 24일 기준으로 GitHub 공식 발표와 문서에서 공개 미리 보기 상태, 지원 범위, 재사용 워크플로의 책임 경계를 확인했습니다. 미리 보기 기능은 지원 내용과 동작이 바뀔 수 있으므로, 도입 전에는 공식 변경 기록과 최신 문서를 다시 확인하세요.
workflow lockfile을 도입해도 macOS 이미지와 Xcode, Runner 운영이라는 별도 관리 부담은 남습니다. 이미 자체 운영 중인 Mac이 있고 장기간 안정적인 고부하 작업이나 물리 장치 연결이 필요하다면 보유 장비가 더 알맞을 수 있습니다. 반대로 테스트나 프로젝트 전환을 위해 독립된 Mac 실행 환경이 필요한 경우에는 구매 전에 필요한 기간과 운영 방식을 비교할 수 있습니다. NodeMini 서비스의 안내는 Mac mini 이용 정보에서 확인하고, 다른 선택지까지 비교할 때는 NodeMini 서비스 안내를 참고하세요.