# 종속성 캐싱 참조 워크플로에서 의존성 캐싱 기능에 대한 정보를 확인하십시오. ## `cache` 작업 사용 [ `cache`작업](https://github.com/actions/cache)은 캐시를 복원할 때 다음 순서를 시도합니다. 1. 먼저, 제공한 `key`과 정확히 일치하는 항목을 검색합니다. 2. 정확히 일치하는 항목을 찾지 못하면 `key`의 부분 일치를 검색합니다. 3. 여전히 일치하는 항목이 없고 `restore-keys`을 제공한 경우, 해당 키들은 부분 일치를 확인하기 위해 순차적으로 검사됩니다. 자세한 내용은 [캐시 키 일치](#cache-key-matching)를 참조하세요. 제공된 `key`과(와) 정확히 일치하는 항목이 있는 경우 캐시 적중으로 간주됩니다. 제공된 `key`과(와) 정확히 일치하는 캐시가 없으면 캐시 누락으로 간주됩니다. 캐시 미스가 발생하면 작업이 성공적으로 완료될 경우 작업이 자동으로 새 캐시를 생성합니다. 새 캐시는 사용자가 제공한 `key`를 사용하고 `path`에서 지정한 파일을 포함합니다. 이 처리 방법에 대한 자세한 내용은 [캐시 적수 및 누락](#cache-hits-and-misses)을 참조하세요. 기존 캐시의 내용은 변경할 수 없습니다. 대신 새 키를 사용해 새로운 캐시를 생성할 수 있습니다. ### `cache` 작업에 대한 입력 매개 변수입니다. * `key`: **필수** 캐시를 저장할 때 생성되는 키이자 캐시를 검색하는 데 사용되는 키입니다. 변수, 컨텍스트 값, 정적 문자열 및 함수의 조합일 수 있습니다. 키의 최대 길이는 512자이며 최대 길이보다 키가 길면 작업이 실패합니다. * `path`: **필수** 캐시하거나 복원할 러너의 경로입니다. * 단일 경로를 지정하거나 별도의 줄에 여러 경로를 추가할 수 있습니다. 예를 들어: ```yaml - name: Cache Gradle packages uses: actions/cache@v4 with: path: | ~/.gradle/caches ~/.gradle/wrapper ``` * 디렉터리 또는 단일 파일을 지정할 수 있으며 GLOB 패턴이 지원됩니다. * 절대 경로 또는 작업 영역 디렉터리를 기준으로 상대적인 경로를 지정할 수 있습니다. * `restore-keys`: **선택적** 대체 복원 키가 포함된 문자열로, 각 복원 키가 새 줄에 배치됩니다. `key`에 대해 캐시 적중이 발생하지 않는 경우 이러한 복원 키는 캐시를 찾고 복원하기 위해 제공된 순서대로 순차적으로 사용됩니다. 예를 들어: ```yaml restore-keys: | npm-feature-${{ hashFiles('package-lock.json') }} npm-feature- npm- ``` * `enableCrossOsArchive`: **Optional** 사용하도록 설정하면 Windows 실행자가 캐시를 만든 운영 체제와 관계없이 캐시를 저장하거나 복원할 수 있는 부울 값입니다. 이 매개 변수가 설정되지 않으면 기본적으로 `false`(으)로 설정됩니다. 자세한 내용은 작업 캐시 설명서의 [OS 간 캐시](https://github.com/actions/cache/blob/main/tips-and-workarounds.md#cross-os-cache)를 참조하세요. > \[!NOTE] > 캐시 경로의 파일에는 액세스 토큰이나 로그인 자격 증명과 같은 민감한 정보를 저장하지 않는 것을 권장합니다. 읽기 액세스 권한이 있는 사용자는 리포지토리에서 끌어오기 요청을 만들고 캐시의 콘텐츠에 액세스할 수 있습니다. 또한 리포지토리의 포크는 베이스 브랜치에 대해 풀 리퀘스트를 생성할 수 있으며, 베이스 브랜치의 캐시에 접근할 수 있습니다. ### `cache` 작업에 대한 출력 매개 변수입니다. * `cache-hit`: 키에 대한 정확한 일치 항목을 나타내는 부울 값입니다. ### 캐시 적중 및 누락 `key`이(가) 기존 캐시와 정확하게 일치하면 \_캐시 적중\_이라고 하며 작업은 캐시된 파일을 `path` 디렉터리로 복원합니다. `key`가 기존 캐시와 일치하지 않는 경우 \_캐시 누락\_이라고 하며 작업이 성공적으로 완료되면 자동으로 새 캐시를 만듭니다. 캐시 누락이 발생하면 작업은 지정된 `restore-keys`에서 일치 항목을 검색합니다. 1. `restore-keys`를 입력하면 `cache` 작업은 `restore-keys` 목록과 일치하는 캐시를 순차적으로 검색합니다. * 정확히 일치하는 경우 작업은 캐시의 파일을 `path` 디렉터리로 복원합니다. * 정확히 일치하는 항목이 없으면 작업은 복원 키의 부분 일치 항목을 검색합니다. 작업이 부분 일치 항목을 찾으면 가장 최근 캐시가 `path` 디렉터리로 복원됩니다. 2. `cache` 작업이 완료되면 작업의 다음 단계가 실행됩니다. 3. 작업이 성공적으로 완료되면 작업은 `path` 디렉터리의 콘텐츠가 포함된 새 캐시를 자동으로 만듭니다. 캐시 매칭 프로세스에 대한 자세한 설명은 [캐시 키 매칭](#cache-key-matching)을 참고하세요. ### `cache` 작업을 사용하는 예제 이 예제에서는 `package-lock.json` 파일의 패키지가 변경되거나 실행기 운영 체제가 변경되는 경우 새 캐시를 만듭니다. 캐시 키는 컨텍스트 및 식을 사용하여 실행기의 운영 체제와 `package-lock.json` 파일의 SHA-256 해시를 포함하는 키를 생성합니다. ```yaml copy name: Caching with npm on: push jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - name: Cache node modules id: cache-npm uses: actions/cache@v4 env: cache-name: cache-node-modules with: # npm cache files are stored in `~/.npm` on Linux/macOS path: ~/.npm key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }} restore-keys: | ${{ runner.os }}-build-${{ env.cache-name }}- ${{ runner.os }}-build- ${{ runner.os }}- - if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }} name: List the state of node modules continue-on-error: true run: npm list - name: Install dependencies run: npm install - name: Build run: npm run build - name: Test run: npm test ``` ### 컨텍스트를 사용하여 캐시 키 만들기 캐시 키에는 지원되는 GitHub Actions컨텍스트, 함수, 리터럴 및 연산자가 포함될 수 있습니다. 자세한 내용은 [문맥 참조](/ko/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts) 및 [워크플로 및 작업에서 식 평가](/ko/enterprise-server@3.22/actions/reference/workflows-and-actions/expressions)을(를) 참조하세요. 식을 사용하여 `key`를 만들면 종속성이 변경되는 경우 자동으로 새 캐시를 만들 수 있습니다. 예를 들어 npm `key` 파일의 해시를 계산하는 식을 사용하여 `package-lock.json`를 만들 수 있습니다. 따라서 `package-lock.json` 파일을 구성하는 종속성이 변경되면 캐시 키가 변경되고 새 캐시가 자동으로 만들어집니다. ```yaml npm-${{ hashFiles('package-lock.json') }} ``` GitHub 는 식을 `hash "package-lock.json"` 계산하여 최종 `key`을 파생합니다. ```yaml npm-d5ea0750 ``` ### `cache` 작업의 출력 사용 `cache` 작업의 출력을 사용하여 캐시 적중 또는 누락이 발생했는지 여부에 따라 작업을 수행할 수 있습니다. 지정된 `key`에 대한 캐시와 정확히 일치하는 항목이 발견되면, `cache-hit` 출력이 `true`로 설정됩니다. 위의 예제 워크플로에는 캐시 누락이 발생한 경우 노드 모듈의 상태를 나열하는 단계가 있습니다. ```yaml - if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }} name: List the state of node modules continue-on-error: true run: npm list ``` ## 캐시 키 일치 이 `cache` 작업은 먼저 워크플로 실행을 포함하는 분기의 `key` 및 캐시 \_버전\_에 대한 캐시 적중 항목을 검색합니다. 일치하는 항목이 없으면 `key`에 대한 접두사 일치 항목을 검색하고, 그래도 일치하는 항목이 없는 경우에는 `restore-keys`와 \_버전\_을 검색합니다. 현재 분기에 일치하는 항목이 여전히 없으면 `cache` 작업은 기본 분기에서 동일한 단계를 다시 시도합니다. 검색 중에는 범위 제한이 적용됨을 유의하시기 바랍니다. 자세한 내용은 [캐시 액세스 제한 사항](#restrictions-for-accessing-a-cache)을(를) 참조하세요. 캐시 버전은 캐시를 만드는 동안 사용된 `path` 및 압축 도구의 메타데이터를 사용하여 캐시를 스탬프하는 방법입니다. 이렇게 하면 소비 워크플로 실행이 실제로 압축을 해제하고 사용할 수 있는 캐시와 고유하게 일치합니다. 자세한 내용은 작업 캐시 설명서의 [캐시 버전](https://github.com/actions/cache#cache-version)을 참조하세요. `restore-keys`를 사용하면 `key`에 캐시 누락이 있을 때 사용할 대체 복원 키 목록을 지정할 수 있습니다. 가장 구체적인 키부터 정렬된 여러 복원 키를 만들 수 있습니다. `cache` 작업은 순차적으로 `restore-keys`를 검색합니다. 키가 직접 일치하지 않으면 작업은 복원 키가 접두사로 지정된 키를 검색합니다. 복원 키에 대해 여러 부분 일치 항목이 있는 경우 작업은 가장 최근에 만든 캐시를 반환합니다. ### 여러 복원 키를 사용하는 예제 ```yaml restore-keys: | npm-feature-${{ hashFiles('package-lock.json') }} npm-feature- npm- ``` 실행기는 다음 `restore-keys`로 확인되는 식을 평가합니다. ```yaml restore-keys: | npm-feature-d5ea0750 npm-feature- npm- ``` 복원 키 `npm-feature-`는 문자열 `npm-feature-`로 시작하는 모든 키와 일치합니다. 예를 들어 `npm-feature-fd3052de`와 `npm-feature-a9b253ff` 두 키 모두 복원 키와 일치합니다. 가장 최근 생성 날짜의 캐시가 사용됩니다. 이 예제의 키는 다음 순서로 검색됩니다. 1. \*\* `npm-feature-d5ea0750` \*\*은 특정 해시와 일치합니다. 2. \*\* `npm-feature-` \*\*은 `npm-feature-`로 접두사가 지정된 캐시 키와 일치합니다. 3. \*\* `npm-` \*\*은 `npm-`로 접두사가 지정된 모든 키와 일치합니다. #### 검색 우선 순위의 예 ```yaml key: npm-feature-d5ea0750 restore-keys: | npm-feature- npm- ``` 예를 들어 끌어오기 요청에 `feature` 분기가 포함되어 있고 기본 분기(`main`)를 대상으로 하는 경우 작업은 다음 순서로 `key` 및 `restore-keys`를 검색합니다. 1. `npm-feature-d5ea0750` 분기의 `feature` 키 2. `npm-feature-` 분기의 `feature` 키 3. `npm-` 분기의 `feature` 키 4. `npm-feature-d5ea0750` 분기의 `main` 키 5. `npm-feature-` 분기의 `main` 키 6. `npm-` 분기의 `main` 키 ## `setup-*` 특정 패키지 관리자용 작업 아래에 나열된 패키지 관리자를 캐시하는 경우, 각 패키지 관리자에 해당하는 setup-\* 작업을 사용하면 최소한의 구성만으로 의존성 캐시를 자동으로 생성하고 복원할 수 있습니다. | 패키지 관리자 | 캐싱에 대한 setup-\* 작업 | | ------------------------------------------------------------------------------------------------- | ------------------ | | npm, Yarn, pnpm | | | [setup-node](https://github.com/actions/setup-node#caching-global-packages-data) | | | pip, pipenv, 시 | | | [setup-python](https://github.com/actions/setup-python#caching-packages-dependencies) | | | Gradle, Maven | | | [setup-java](https://github.com/actions/setup-java#caching-packages-dependencies) | | | RubyGems | | | [setup-ruby](https://github.com/ruby/setup-ruby#caching-bundle-install-automatically) | | | 바둑 `go.sum` | | | [setup-go](https://github.com/actions/setup-go#caching-dependency-files-and-build-outputs) | | | nuGet .NET | | | [setup-dotnet](https://github.com/actions/setup-dotnet?tab=readme-ov-file#caching-nuget-packages) | | ## 캐시 액세스 제한 사항 액세스 제한은 서로 다른 분기 또는 태그 간에 논리적 경계를 만들어 캐시 격리 및 보안을 제공합니다. 워크플로 실행은 현재 브랜치 또는 기본 브랜치(보통 `main`)에서 생성된 캐시를 복원할 수 있습니다. 워크플로 실행이 풀 리퀘스트로 트리거된 경우, 포크된 리포지토리의 기본 브랜치를 포함해 베이스 브랜치에서 생성된 캐시도 복원할 수 있습니다. 예를 들어 `feature-b` 브랜치의 베이스 브랜치가 `feature-a`인 경우, 풀 리퀘스트로 트리거된 워크플로 실행은 기본 `main` 브랜치, 베이스 `feature-a` 브랜치, 그리고 현재 `feature-b` 브랜치에서 생성된 캐시에 접근할 수 있습니다. 워크플로 실행은 하위 브랜치나 형제 브랜치에서 생성된 캐시는 복원할 수 없습니다. 예를 들어 자식 `feature-b` 분기에 대해 생성된 캐시는 부모 `main` 분기에서 트리거된 워크플로 실행에 액세스할 수 없습니다. 마찬가지로 베이스 `feature-a`이(가) 있는 `main` 분기에 대해 생성된 캐시는 베이스 `feature-c`을(를) 사용하여 해당 형제 `main` 분기에 액세스할 수 없습니다. 워크플로 실행은 서로 다른 태그 이름으로 생성된 캐시도 복원할 수 없습니다. 예를 들어 베이스 `release-a`이(가) 있는 태그 `main`에 대해 생성된 캐시는 베이스 `release-b`이(가) 있는 태그 `main`에 대해 트리거된 워크플로 실행에 액세스할 수 없습니다. 끌어오기 요청에서 트리거된 워크플로 실행에 의해 캐시가 생성되면 병합 참조(`refs/pull/.../merge`)에 대한 캐시가 생성됩니다. 이로 인해 캐시는 범위가 제한되며, 풀 리퀘스트를 다시 실행할 때만 복원할 수 있습니다. 해당 캐시는 베이스 브랜치나 그 베이스 브랜치를 대상으로 하는 다른 풀 리퀘스트에서는 복원할 수 없습니다. 리포지토리 내 여러 워크플로 실행은 캐시를 공유할 수 있습니다. 워크플로 실행에서 특정 브랜치용으로 생성된 캐시는 동일한 리포지토리와 브랜치의 다른 워크플로 실행에서도 접근하고 복원할 수 있습니다. > \[!NOTE] > 개체가 러너에서 직접 캐시로부터 검색되거나 캐시에 저장되므로, Actions 러너는 AWS S3 또는 Azure Blob Storage와 같은 GitHub Enterprise Server에 구성된 Actions 개체 스토리지에 직접 연결할 수 있어야 합니다. 자체 호스팅 실행기는 GitHub Enterprise Server 인스턴스가 제공한 액세스 URL을 사용해 Blob Storage 공급자에 인증합니다. 이 URL은 Blob Storage 제공자에 유효한 임시 인증 자격 증명을 제공합니다. 이 프로세스는 인스턴스 자체에 의해 시작되며, 인스턴스가 개체 스토리지에 대한 모든 요청을 중개합니다. > > 즉, `actions/cache`이(가) 정상적으로 작동하려면 Blob Storage에 대한 HTTPS 연결이 필요합니다. > > 모든 메타데이터는 아티팩트 캐시 서비스에서 관리되며, 이 서비스는 내의 마이크로 서비스 GitHub Actions입니다. > > 캐시 스토리지에 대한 자세한 내용은 [외부 스토리지 요구 사항](/ko/enterprise-server@3.22/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server#external-storage-requirements)을 참조하세요. ## 낮은 신뢰 워크플로 트리거에 대한 캐시 액세스 일부 워크플로는 포크 끌어오기 요청 또는 문제 주석과 같이 리포지토리에 대한 쓰기 권한이 없는 사용자가 시작할 수 있는 이벤트에 대한 응답으로 실행됩니다. 이러한 이벤트는 기본 분기의 컨텍스트에서 실행될 때 나중에 더 권한 있는 워크플로가 복원하고 신뢰하는 악의적인 캐시를 작성하는 데 사용할 수 있습니다. 이 공격 클래스를 \_캐시 중독\_이라고 합니다. 이러한 위험을 줄이기 위해 이러한 워크플로 트리거만 기본 분기의 범위에서 캐시를 만들거나 덮어쓸 수 있습니다. * `push` * `workflow_dispatch` * `repository_dispatch` * `delete` * `registry_package` * `page_build` * `schedule` 기본 브랜치로 확인되는 다른 이벤트에 의해 트리거된 실행에는 기본 브랜치 범위의 캐시에 대한 읽기 전용 액세스 권한이 부여됩니다. 이러한 실행은 기존 캐시를 복원할 수 있지만 만들거나 덮어쓸 수 없습니다. 여기에는 페이로드 또는 트리거한 행위자가 리포지토리 외부의 누군가에 의해 영향을 받을 수 있는 트리거(예: `pull_request_target`, `issue_comment`, `workflow_run`)가 포함됩니다. 이벤트는 `pull_request` 영향을 받지 않습니다. 실행에서 `pull_request` 만든 캐시는 이미 병합 참조(`refs/pull/.../merge`)로 범위가 지정되어 있으며 기본 분기의 범위에 쓸 수 없습니다. 자세한 내용은 [캐시 액세스 제한 사항](#restrictions-for-accessing-a-cache)을(를) 참조하세요. 읽기 전용 캐시 액세스 권한이 있는 실행에서 캐시를 저장하려고 하면 저장이 실패하지만 단계와 작업은 저장되지 않습니다. 워크플로가 계속되고 실패가 워크플로 로그에 경고로 보고됩니다. 이 경우 다음을 고려합니다. * 기본 브랜치 범위에서 캐싱의 성능 이점을 유지하려면 캐시를 최신 상태로 유지하는 신뢰할 수 있는 워크플로를 마련해야 합니다. 예를 들어 기본 브랜치에 대한 `push`로 트리거되는 CI 빌드가 이에 해당합니다. 그런 다음, 이러한 캐시 항목은 다음과 같은 `pull_request_target`낮은 신뢰 이벤트에 의해 트리거되는 워크플로에 의해 복원될 수 있습니다. * 낮은 신뢰 워크플로에서 의도한 캐시 사용량을 명확히 하고 워크플로 실행 로그의 경고를 방지하는 등의 복원 전용 캐시 작업으로 `actions/cache/restore` 전환합니다. ## 캐시를 안전하게 사용하는 모범 사례 캐시 콘텐츠는 서명되거나 확인되지 않으며 캐시를 읽을 수 있는 워크플로 실행은 해당 콘텐츠를 추출할 수 있습니다. 추출된 캐시는 이후에 워크플로 실행에서 실행되는 파일을 수정하여 악성 코드 실행으로 이어질 수 있습니다. 캐시를 사용하는 보안 위험을 줄이려면 다음 방법을 따르세요. * **중요한 정보를 캐시에 저장하지 마세요.** 리포지토리에 대해 끌어오기 요청을 열 수 있는 모든 사용자는 기본 분기의 캐시 내용을 읽을 수 있습니다. 캐시된 경로에 비밀, 토큰 또는 자격 증명을 작성하지 마세요. 대신 중요한 값을 비밀로 저장합니다. [비밀](/ko/enterprise-server@3.22/actions/concepts/security/secrets)을(를) 참조하세요. * **신뢰할 수 있는 트리거에서 캐시를 저장합니다.** 신뢰할 수 있는 행위자(일반적으로 리포지토리에 대한 쓰기 액세스 권한이 있는 행위자)에 의해 트리거되는 워크플로에 대한 캐시 쓰기를 제한합니다. 캐시에 쓸 수 있는 [워크플로 트리거를](#cache-access-for-low-trust-workflow-triggers) 제한하기 위해 적용되는 기본 제한 사항은 낮은 신뢰 워크플로 트리거에 대한 캐시 액세스를 참조하세요. 또한 배포 보호 규칙과 함께 환경을 사용하여 캐시를 수정할 수 있는 워크플로를 추가로 제한하는 것이 좋습니다. [배포 환경 관리](/ko/enterprise-server@3.22/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)을(를) 참조하세요. * **워크플로 모범 보안 사례를 따라 워크플로를 강화합니다.** 워크플로 취약성에 대해 강화된 워크플로에 대한 캐시-쓰기 액세스 권한이 있는 워크플로를 제한합니다. [안전 사용 참조](/ko/enterprise-server@3.22/actions/reference/security/secure-use#writing-workflows)의 지침에 따라 코드 실행 및 악성 캐시 항목의 도입으로 이어질 수 있는 워크플로의 취약성을 방지합니다. 워크플로 보안에 대한 광범위한 지침은 [안전 사용 참조](/ko/enterprise-server@3.22/actions/reference/security/secure-use)을 참조하세요. ## 사용 제한 및 제거 정책 GitHub 는 스토리지 비용을 관리하고 남용을 방지하기 위해 캐시 스토리지 및 보존에 제한을 적용합니다. 이러한 제한을 이해하면 캐시 사용량을 최적화할 수 있습니다. ### 기본 제한 GitHub 는 7일 동안 액세스되지 않은 캐시 항목을 제거합니다. 저장할 수 있는 캐시 수는 제한되지 않지만 리포지토리에 있는 모든 캐시의 총 크기는 제한됩니다. 기본적으로 리포지토리당 제한은 10GB이지만 엔터프라이즈 소유자, 조직 소유자 또는 리포지토리 관리자가 이 제한을 늘릴 수 있습니다. 리포지토리가 최대 캐시 스토리지에 도달하면, 캐시 제거 정책에 따라 가장 오래전에 액세스된 캐시부터 최근에 액세스된 캐시 순으로 삭제하여 공간을 확보합니다. 이 제한을 초과하면 GitHub는 새 캐시를 저장하지만 총 크기가 리포지토리 한도 미만이 될 때까지 캐시 제거를 시작합니다. 캐시 제거 프로세스는 캐시가 생성되고 높은 빈도로 삭제되는 캐시 스래싱을 일으킬 수 있습니다. 이를 줄이기 위해 리포지토리에 대한 캐시를 검토하고 특정 워크플로을 구성하여 사용하도록 선택한, 등록된 결제 수단이 있는 사용자에게만 제공됩니다. [캐시 관리](/ko/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/manage-caches)을 참조하세요. 리포지토리의 캐시 크기 제한을 늘릴 수도 있습니다. 자세한 내용은 [리포지토리에 대한 GitHub Actions 설정 관리](/ko/enterprise-server@3.22/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#configuring-cache-storage-for-a-repository)을(를) 참조하세요. ## 다음 단계 종속성 캐시를 관리하려면 [캐시 관리](/ko/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/manage-caches)을(를) 참조하세요.