리포지토리의 워크플로에서 액션 종속성 잠금

워크플로에서 사용하는 모든 작업을 확인된 커밋에 고정하는 잠금 파일을 생성하고 종속성이 변경될 때 최신 상태로 유지합니다.

누가 이 기능을 사용할 수 있나요?

People with write access to a repository

GitHub Enterprise Cloud

이 기사에서

워크플로의 종속성을 잠그면 참조된 작업에 원래 검토된 것과 동일한 코드가 포함됩니다. 자세한 내용은 워크플로 종속성 락파일을(를) 참조하세요.

1. 동작 참조 확인

잠금 파일을 만들면 종속성이 현재 브랜치 또는 태그 참조 기준의 커밋으로 고정됩니다. 이 버전들이 제자리에 고정하려는 버전인지 확인합니다.

워크플로의 각 uses 참조가 지원되는 현재 버전의 액션을 가리키는지 확인합니다. 모범 사례는 안전 사용 참조을 참조하세요.

워크플로 중 하나라도 다른 리포지토리에서 재사용 가능한 워크플로를 호출하는 경우 해당 참조도 확인합니다. 재사용 가능한 워크플로의 종속성은 사용자의 잠금 파일이 아니라 정의된 리포지토리의 잠금 파일로 처리됩니다. 해당 원본 리포지토리는 완전한 커버리지를 위해 자체 잠금 파일이 필요합니다. 조직에서 공유 워크플로를 유지 관리하는 경우 먼저 해당 리포지토리를 등록합니다. 워크플로 구성 재사용을(를) 참조하세요.

GitHub Actions가 Dependabot 종속성을 관리하도록 하는 것을 권장합니다. 아직 사용하도록 설정되지 않은 경우 잠금 파일을 만들기 전에 사용하도록 설정합니다. Dependabot을 사용하여 작업을 최신 상태로 유지을(를) 참조하세요.

2. 확장 actions-lock 프로그램을 설치합니다

  1. GitHub CLI 를 설치합니다.

  2. 익스텐션을 설치합니다.

    Bash
    gh extension install github/gh-actions-lock

팁

나중에 확장을 업데이트하려면 다음을 실행합니다 gh extension upgrade gh-actions-lock.

3. 잠금 파일 생성

리포지토리의 루트에서 인수 없이 확장 프로그램을 실행합니다. .github/workflows/ 아래의 모든 워크플로를 검사하고, 확인할 수 있는 각 작업을 커밋 SHA에 고정하고, 잠금 파일을 작성합니다.

Bash
gh actions-lock

전체 디렉터리 대신 단일 워크플로를 온보딩하려면 해당 경로를 전달합니다.

Bash
gh actions-lock .github/workflows/ci.yml

확장은 로컬 경로 동작(uses: ./…)을 따르거나 잠그지 않습니다. ./ 경로를 사용하면 실행기 작업 영역에서 체크 아웃된 모든 항목이 실행되므로, 확장에서 이를 고정하거나 그것이 사용하는 항목을 볼 수 없습니다. $/ 경로는 워크플로의 커밋에서 리포지토리 자체의 작업을 실행하므로 고정되며 참조하는 작업도 잠글 수 있습니다. 이 두 가지를 비교하려면 GitHub Actions에 대한 워크플로 구문을 참조하세요.

체크아웃의 로컬 작업에서 다른 작업을 사용하는 경우, 해당 작업은 잠금 파일 항목 없이 런타임에 실패하므로 확장은 local-action 오류를 보고하고 아무 것도 기록하지 않습니다. 로컬 액션을 동일한 리포지토리 참조로 잠그려면 다음을 실행합니다.

Bash
gh actions-lock --migrate-local-actions

./ 참조를 유지하고 대신 경고로 보고하려면 --ignore-local-actions을 전달하세요. 로컬 경로 작업 유지를 참조하세요.

전체 옵션 집합에 대해 다음을 실행 gh actions-lock --help합니다. 특정 오류 또는 경고에 대한 도움말은 gh-actions-lock 문제 해결 가이드를 참조하세요.

로컬 경로 동작 유지

--ignore-local-actions를 전달하면 런타임에 수행되는 작업은 로컬 작업에서 사용하는 작업에 따라 달라집니다.

  • 다른 작업은 사용하지 않습니다, 예를 들어 run: 단계만 해당됩니다: 워크플로는 정상적으로 실행됩니다.
  • 동일한 워크플로에 대한 잠금 파일 항목이 있는 작업을 사용하는 경우: 워크플로는 정상적으로 실행됩니다.
  • 해당 워크플로에 대한 잠금 파일 항목이 없는 액션을 사용합니다: 로컬 액션의 단계에 도달하면 작업이 실패하고 lockfile missing pin for octo-org/setup-tool@v2.0.0와 같은 오류가 발생합니다. 이전 단계가 이미 실행되었습니다.

대신 $/를 권장합니다. 그러면 작업이 고정된 --migrate-local-actions 참조로 실행됩니다. 참조를 ./ 유지해야 하는 경우 로컬 작업에서 사용하는 작업에 대한 워크플로 잠금 파일 항목을 제공하세요. 동일한 참조를 사용하여 동일한 작업을 사용하는 복합 작업을 추가하고 실행되지 않는 단계에서 워크플로 내에서 호출합니다. 그런 다음 gh actions-lock --ignore-local-actions를 실행합니다.

# .github/actions/lock-local-deps/action.yml
name: Lock local action dependencies
description: Never runs. Lists the actions that ./.github/actions/build uses.
runs:
  using: composite
  steps:
    - uses: octo-org/setup-tool@v2.0.0

# In the workflow
steps:
  - uses: actions/checkout@v6
  - if: false
    uses: $/.github/actions/lock-local-deps
  - uses: ./.github/actions/build

동일한 워크플로에 대해 항목을 기록해야 합니다. 다른 워크플로에 대해서만 기록된 항목은 계산되지 않습니다. 로컬 작업의 종속성이 변경되면 복합 작업을 업데이트하고 gh actions-lock --ignore-local-actions를 다시 실행합니다.

4. 변경 내용을 검토하고 커밋하세요

확장이 lockfile 외에도 변경하므로 커밋하기 전에 전체 차이를 검토하세요. 또한 워크플로 uses 참조를 확인된 특정 버전으로 다시 작성하므로 참조 octo-org/deploy-action@v3는 octo-org/deploy-action@v3.1.0로 바뀔 수 있습니다. 이렇게 하면 해석되는 커밋을 변경하지 않고 참조를 보다 구체적으로 만듭니다.

중요

리포지토리, 조직 또는 엔터프라이즈에서 지정된 작업만 허용하는 경우 커밋하기 전에 허용 목록을 확인합니다. 워크플로를 온보딩한 후에는 태그를 다른 코드로 이동할 수 있지만 잠긴 SHA는 이동할 수 없으므로 태그 대신 잠긴 커밋 SHA에 대해 허용 목록을 확인합니다. 예를 들어 actions/checkout@v6 태그에 고정된 항목은 워크플로를 온보딩한 후 더 이상 일치하지 않습니다. 대신 와일드카드 또는 전체 커밋 SHA를 사용하세요. 리포지토리에 대한 GitHub Actions 설정 관리을(를) 참조하세요.

--migrate-local-actions를 전달한 경우, 확장은 워크플로와 리포지토리의 uses: $/… 파일에서 자체 리포지토리의 작업에 대한 참조를 action.yml에서 uses: ./…로 다시 작성합니다. 두 양식이 다르게 동작하기 때문에 옵션을 전달할 때만 이 작업을 수행합니다. ./ 경로는 실행기 작업 영역에 있는 항목을 기준으로 해석되지만 $/… 참조는 항상 워크플로의 자체 커밋에서 실행되므로 잠금 파일 항목이 필요하지 않습니다. 다시 작성된 각 줄을 검토합니다.

5. 잠금 파일을 최신 상태로 유지

리포지토리의 워크플로 파일 및 보안 업데이트를 사용하여 잠금 파일을 최신 상태로 유지합니다.

  1. 종속성을 변경하면 확장을 다시 실행하세요. uses에 uses 종속성이 있는 워크플로를 추가하거나 기존 워크플로에서 gh actions-lock 종속성을 추가하거나 제거할 때마다 다시 실행합니다.

  2. ** Dependabot가 버전 범프를 처리하도록 하세요.** Dependabot가 온보딩한 워크플로의 작업에 대한 버전 업데이트를 열면 동일한 끌어오기 요청에서 일치하는 잠금 파일 항목도 다시 생성됩니다. 워크플로 파일과 잠금 파일은 서로 어긋나면 안 됩니다.

Dependabot 는 이미 온보딩된 워크플로에 대한 잠금 파일 항목만 업데이트합니다. 잠금 파일에 없는 워크플로의 작업 버전을 올리는 경우 워크플로 파일을 평소와 같이 업데이트하고 잠금 파일은 변경하지 않은 상태로 둡니다.

  1. 이동한 참조를 다시 해결합니다. 확장에서 이동된 참조를 처리하는 방법은 참조에 따라 달라집니다.

    • 분기 또는 부분 버전(예: main 또는 v3)은 잠긴 커밋을 유지하고 확장은 경고를 보고합니다 ref-moved . 이를 진행하려면 업스트림 기록을 확인한 다음 gh actions-lock --relock를 실행하세요.
    • 전체 버전 태그(예: v3.1.0)는 고정된 커밋을 가리켜야 합니다. 태그가 이동하면 gh actions-lock --relock를 실행하거나 uses: 줄을 변경할 때까지 확장에서 오류를 보고합니다.
    • 잠긴 커밋이 더 이상 참조의 기록에 없는 다시 작성된 기록(예: 강제 푸시 후)은 --relock로도 해결되지 않는 오류입니다. 업스트림 기록을 검토한 후 실행 gh actions-lock --accept-moved합니다. --accept-moved를 자동화에 사용하지 마세요.

잠금 파일 변경 검토

다른 종속성 변경과 마찬가지로 잠금 파일의 변경 내용을 검토합니다.

  • 변경된 내용 commit 는 워크플로가 실행할 코드입니다. 다른 종속성 버전 범프를 다루듯이 다루세요.
  • 변경된 값 owner_id 또는 repo_id 은 드문 경우여야 합니다. 즉, 해당 이름 뒤에 있는 리포지토리가 원래 잠근 리포지토리가 아니므로 병합하기 전에 조사하세요.

잠금 파일이 잘못된 것 같으면 워크플로 파일을 수정하고 잠금 파일을 다시 생성합니다. 잠금 파일을 수동으로 편집하지 마세요.

다음 단계

리포지토리에 대한 잠금 파일을 생성한 후에는 개발자가 명령을 실행하는 것을 기억할 필요가 없도록 강제 적용되고 최신 상태인지 확인합니다. 액션 종속성에 lockfile 적용을(를) 참조하세요.