종속성 캐싱 참조

`cache` 작업 사용

cache작업은 캐시를 복원할 때 다음 순서를 시도합니다.

먼저, 제공한 key과 정확히 일치하는 항목을 검색합니다.
정확히 일치하는 항목을 찾지 못하면 key의 부분 일치를 검색합니다.
여전히 일치하는 항목이 없고 restore-keys을 제공한 경우, 해당 키들은 부분 일치를 확인하기 위해 순차적으로 검사됩니다. 자세한 내용은 캐시 키 일치를 참조하세요.

제공된 key과(와) 정확히 일치하는 항목이 있는 경우 캐시 적중으로 간주됩니다. 제공된 key과(와) 정확히 일치하는 캐시가 없으면 캐시 누락으로 간주됩니다. 캐시 미스가 발생하면 작업이 성공적으로 완료될 경우 작업이 자동으로 새 캐시를 생성합니다. 새 캐시는 사용자가 제공한 key를 사용하고 path에서 지정한 파일을 포함합니다. 이 처리 방법에 대한 자세한 내용은 캐시 적수 및 누락을 참조하세요.

기존 캐시의 내용은 변경할 수 없습니다. 대신 새 키를 사용해 새로운 캐시를 생성할 수 있습니다.

`cache` 작업에 대한 입력 매개 변수입니다.

key: 필수 캐시를 저장할 때 생성되는 키이자 캐시를 검색하는 데 사용되는 키입니다. 변수, 컨텍스트 값, 정적 문자열 및 함수의 조합일 수 있습니다. 키의 최대 길이는 512자이며 최대 길이보다 키가 길면 작업이 실패합니다.
path: 필수 캐시하거나 복원할 러너의 경로입니다.
- 단일 경로를 지정하거나 별도의 줄에 여러 경로를 추가할 수 있습니다. 예를 들어:
```
- name: Cache Gradle packages
  uses: actions/cache@v4
  with:
    path: |
      ~/.gradle/caches
      ~/.gradle/wrapper
```
- 디렉터리 또는 단일 파일을 지정할 수 있으며 GLOB 패턴이 지원됩니다.
- 절대 경로 또는 작업 영역 디렉터리를 기준으로 상대적인 경로를 지정할 수 있습니다.
restore-keys: 선택적 대체 복원 키가 포함된 문자열로, 각 복원 키가 새 줄에 배치됩니다. key에 대해 캐시 적중이 발생하지 않는 경우 이러한 복원 키는 캐시를 찾고 복원하기 위해 제공된 순서대로 순차적으로 사용됩니다. 예를 들어:
```
restore-keys: |
  npm-feature-${{ hashFiles('package-lock.json') }}
  npm-feature-
  npm-
```
enableCrossOsArchive: Optional 사용하도록 설정하면 Windows 실행자가 캐시를 만든 운영 체제와 관계없이 캐시를 저장하거나 복원할 수 있는 부울 값입니다. 이 매개 변수가 설정되지 않으면 기본적으로 false(으)로 설정됩니다. 자세한 내용은 작업 캐시 설명서의 OS 간 캐시를 참조하세요.

참고

캐시 경로의 파일에는 액세스 토큰이나 로그인 자격 증명과 같은 민감한 정보를 저장하지 않는 것을 권장합니다. 읽기 액세스 권한이 있는 사용자는 리포지토리에서 끌어오기 요청을 만들고 캐시의 콘텐츠에 액세스할 수 있습니다. 또한 리포지토리의 포크는 베이스 브랜치에 대해 풀 리퀘스트를 생성할 수 있으며, 베이스 브랜치의 캐시에 접근할 수 있습니다.

`cache` 작업에 대한 출력 매개 변수입니다.

cache-hit: 키에 대한 정확한 일치 항목을 나타내는 부울 값입니다.

캐시 적중 및 누락

key이(가) 기존 캐시와 정확하게 일치하면 _캐시 적중_이라고 하며 작업은 캐시된 파일을 path 디렉터리로 복원합니다.

key가 기존 캐시와 일치하지 않는 경우 _캐시 누락_이라고 하며 작업이 성공적으로 완료되면 자동으로 새 캐시를 만듭니다.

캐시 누락이 발생하면 작업은 지정된 restore-keys에서 일치 항목을 검색합니다.

restore-keys를 입력하면 cache 작업은 restore-keys 목록과 일치하는 캐시를 순차적으로 검색합니다.
- 정확히 일치하는 경우 작업은 캐시의 파일을 path 디렉터리로 복원합니다.
- 정확히 일치하는 항목이 없으면 작업은 복원 키의 부분 일치 항목을 검색합니다. 작업이 부분 일치 항목을 찾으면 가장 최근 캐시가 path 디렉터리로 복원됩니다.
cache 작업이 완료되면 작업의 다음 단계가 실행됩니다.
작업이 성공적으로 완료되면 작업은 path 디렉터리의 콘텐츠가 포함된 새 캐시를 자동으로 만듭니다.

캐시 매칭 프로세스에 대한 자세한 설명은 캐시 키 매칭을 참고하세요.

`cache` 작업을 사용하는 예제

이 예제에서는 package-lock.json 파일의 패키지가 변경되거나 실행기 운영 체제가 변경되는 경우 새 캐시를 만듭니다. 캐시 키는 컨텍스트 및 식을 사용하여 실행기의 운영 체제와 package-lock.json 파일의 SHA-256 해시를 포함하는 키를 생성합니다.

YAML

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

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컨텍스트, 함수, 리터럴 및 연산자가 포함될 수 있습니다. 자세한 내용은 문맥 참조 및 워크플로 및 작업에서 식 평가을(를) 참조하세요.

식을 사용하여 key를 만들면 종속성이 변경되는 경우 자동으로 새 캐시를 만들 수 있습니다.

예를 들어 npm key 파일의 해시를 계산하는 식을 사용하여 package-lock.json를 만들 수 있습니다. 따라서 package-lock.json 파일을 구성하는 종속성이 변경되면 캐시 키가 변경되고 새 캐시가 자동으로 만들어집니다.

npm-${{ hashFiles('package-lock.json') }}

GitHub 는 식을 hash "package-lock.json" 계산하여 최종 key을 파생합니다.

npm-d5ea0750

`cache` 작업의 출력 사용

cache 작업의 출력을 사용하여 캐시 적중 또는 누락이 발생했는지 여부에 따라 작업을 수행할 수 있습니다. 지정된 key에 대한 캐시와 정확히 일치하는 항목이 발견되면, cache-hit 출력이 true로 설정됩니다.

위의 예제 워크플로에는 캐시 누락이 발생한 경우 노드 모듈의 상태를 나열하는 단계가 있습니다.

- 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 작업은 기본 분기에서 동일한 단계를 다시 시도합니다. 검색 중에는 범위 제한이 적용됨을 유의하시기 바랍니다. 자세한 내용은 캐시 액세스 제한 사항을(를) 참조하세요.

캐시 버전은 캐시를 만드는 동안 사용된 path 및 압축 도구의 메타데이터를 사용하여 캐시를 스탬프하는 방법입니다. 이렇게 하면 소비 워크플로 실행이 실제로 압축을 해제하고 사용할 수 있는 캐시와 고유하게 일치합니다. 자세한 내용은 작업 캐시 설명서의 캐시 버전을 참조하세요.

restore-keys를 사용하면 key에 캐시 누락이 있을 때 사용할 대체 복원 키 목록을 지정할 수 있습니다. 가장 구체적인 키부터 정렬된 여러 복원 키를 만들 수 있습니다. cache 작업은 순차적으로 restore-keys를 검색합니다. 키가 직접 일치하지 않으면 작업은 복원 키가 접두사로 지정된 키를 검색합니다. 복원 키에 대해 여러 부분 일치 항목이 있는 경우 작업은 가장 최근에 만든 캐시를 반환합니다.

여러 복원 키를 사용하는 예제

restore-keys: |
  npm-feature-${{ hashFiles('package-lock.json') }}
  npm-feature-
  npm-

실행기는 다음 restore-keys로 확인되는 식을 평가합니다.

restore-keys: |
  npm-feature-d5ea0750
  npm-feature-
  npm-

복원 키 npm-feature-는 문자열 npm-feature-로 시작하는 모든 키와 일치합니다. 예를 들어 npm-feature-fd3052de와 npm-feature-a9b253ff 두 키 모두 복원 키와 일치합니다. 가장 최근 생성 날짜의 캐시가 사용됩니다. 이 예제의 키는 다음 순서로 검색됩니다.

** npm-feature-d5ea0750 **은 특정 해시와 일치합니다.
** npm-feature- **은 npm-feature-로 접두사가 지정된 캐시 키와 일치합니다.
** npm- **은 npm-로 접두사가 지정된 모든 키와 일치합니다.

검색 우선 순위의 예

key:
  npm-feature-d5ea0750
restore-keys: |
  npm-feature-
  npm-

예를 들어 끌어오기 요청에 feature 분기가 포함되어 있고 기본 분기(main)를 대상으로 하는 경우 작업은 다음 순서로 key 및 restore-keys를 검색합니다.

npm-feature-d5ea0750 분기의 feature 키
npm-feature- 분기의 feature 키
npm- 분기의 feature 키
npm-feature-d5ea0750 분기의 main 키
npm-feature- 분기의 main 키
npm- 분기의 main 키

`setup-*` 특정 패키지 관리자용 작업

아래에 나열된 패키지 관리자를 캐시하는 경우, 각 패키지 관리자에 해당하는 setup-* 작업을 사용하면 최소한의 구성만으로 의존성 캐시를 자동으로 생성하고 복원할 수 있습니다.

패키지 관리자	캐싱에 대한 setup-* 작업
npm, Yarn, pnpm
setup-node
pip, pipenv, 시
setup-python
Gradle, Maven
setup-java
RubyGems
setup-ruby
바둑 `go.sum`
setup-go
.NET NuGet
setup-dotnet

캐시 액세스 제한 사항

액세스 제한은 서로 다른 분기 또는 태그 간에 논리적 경계를 만들어 캐시 격리 및 보안을 제공합니다. 워크플로 실행은 현재 브랜치 또는 기본 브랜치(보통 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)에 대한 캐시가 생성됩니다. 이로 인해 캐시는 범위가 제한되며, 풀 리퀘스트를 다시 실행할 때만 복원할 수 있습니다. 해당 캐시는 베이스 브랜치나 그 베이스 브랜치를 대상으로 하는 다른 풀 리퀘스트에서는 복원할 수 없습니다.

리포지토리 내 여러 워크플로 실행은 캐시를 공유할 수 있습니다. 워크플로 실행에서 특정 브랜치용으로 생성된 캐시는 동일한 리포지토리와 브랜치의 다른 워크플로 실행에서도 접근하고 복원할 수 있습니다.

낮은 신뢰 워크플로 트리거에 대한 캐시 액세스

일부 워크플로는 포크 끌어오기 요청 또는 문제 주석과 같이 리포지토리에 대한 쓰기 권한이 없는 사용자가 시작할 수 있는 이벤트에 대한 응답으로 실행됩니다. 이러한 이벤트는 기본 분기의 컨텍스트에서 실행될 때 나중에 더 권한 있는 워크플로가 복원하고 신뢰하는 악의적인 캐시를 작성하는 데 사용할 수 있습니다. 이 공격 클래스를 _캐시 중독_이라고 합니다.

이러한 위험을 줄이기 위해 이러한 워크플로 트리거만 기본 분기의 범위에서 캐시를 만들거나 덮어쓸 수 있습니다.

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)로 범위가 지정되어 있으며 기본 분기의 범위에 쓸 수 없습니다. 자세한 내용은 캐시 액세스 제한 사항을(를) 참조하세요.

읽기 전용 캐시 액세스 권한이 있는 실행에서 캐시를 저장하려고 하면 저장이 실패하지만 단계와 작업은 저장되지 않습니다. 워크플로가 계속되고 실패가 워크플로 로그에 경고로 보고됩니다. 이 경우 다음을 고려합니다.

기본 브랜치 범위에서 캐싱의 성능 이점을 유지하려면 캐시를 최신 상태로 유지하는 신뢰할 수 있는 워크플로를 마련해야 합니다. 예를 들어 기본 브랜치에 대한 push로 트리거되는 CI 빌드가 이에 해당합니다. 그런 다음, 이러한 캐시 항목은 다음과 같은 pull_request_target낮은 신뢰 이벤트에 의해 트리거되는 워크플로에 의해 복원될 수 있습니다.
낮은 신뢰 워크플로에서 의도한 캐시 사용량을 명확히 하고 워크플로 실행 로그의 경고를 방지하는 등의 복원 전용 캐시 작업으로 actions/cache/restore 전환합니다.

캐시를 안전하게 사용하는 모범 사례

캐시 콘텐츠는 서명되거나 확인되지 않으며 캐시를 읽을 수 있는 워크플로 실행은 해당 콘텐츠를 추출할 수 있습니다. 추출된 캐시는 이후에 워크플로 실행에서 실행되는 파일을 수정하여 악성 코드 실행으로 이어질 수 있습니다. 캐시를 사용하는 보안 위험을 줄이려면 다음 방법을 따르세요.

중요한 정보를 캐시에 저장하지 마세요. 리포지토리에 대해 끌어오기 요청을 열 수 있는 모든 사용자는 기본 분기의 캐시 내용을 읽을 수 있습니다. 캐시된 경로에 비밀, 토큰 또는 자격 증명을 작성하지 마세요. 대신 중요한 값을 비밀로 저장합니다. 비밀을(를) 참조하세요.
신뢰할 수 있는 트리거에서 캐시를 저장합니다. 신뢰할 수 있는 행위자(일반적으로 리포지토리에 대한 쓰기 액세스 권한이 있는 행위자)에 의해 트리거되는 워크플로에 대한 캐시 쓰기를 제한합니다. 캐시에 쓸 수 있는 워크플로 트리거를 제한하기 위해 적용되는 기본 제한 사항은 낮은 신뢰 워크플로 트리거에 대한 캐시 액세스를 참조하세요. 또한 배포 보호 규칙과 함께 환경을 사용하여 캐시를 수정할 수 있는 워크플로를 추가로 제한하는 것이 좋습니다. 배포 환경 관리을(를) 참조하세요.
워크플로 모범 보안 사례를 따라 워크플로를 강화합니다. 워크플로 취약성에 대해 강화된 워크플로에 대한 캐시-쓰기 액세스 권한이 있는 워크플로를 제한합니다. 안전 사용 참조의 지침에 따라 코드 실행 및 악성 캐시 항목의 도입으로 이어질 수 있는 워크플로의 취약성을 방지합니다.

워크플로 보안에 대한 광범위한 지침은 안전 사용 참조을 참조하세요.

사용 제한 및 제거 정책

GitHub 는 스토리지 비용을 관리하고 남용을 방지하기 위해 캐시 스토리지 및 보존에 제한을 적용합니다. 이러한 제한을 이해하면 캐시 사용량을 최적화할 수 있습니다.

기본 제한

GitHub 는 7일 동안 액세스되지 않은 캐시 항목을 제거합니다. 저장할 수 있는 캐시 수는 제한되지 않지만 리포지토리에 있는 모든 캐시의 총 크기는 제한됩니다. 기본적으로 리포지토리당 제한은 10GB이지만 엔터프라이즈 소유자, 조직 소유자 또는 리포지토리 관리자가 이 제한을 늘릴 수 있습니다. 10GB를 초과하는 모든 사용량은 계정에 청구됩니다. 리포지토리가 최대 캐시 스토리지에 도달하면, 캐시 제거 정책에 따라 가장 오래전에 액세스된 캐시부터 최근에 액세스된 캐시 순으로 삭제하여 공간을 확보합니다.

이 제한을 초과하면 GitHub는 새 캐시를 저장하지만 총 크기가 리포지토리 한도 미만이 될 때까지 캐시 제거를 시작합니다. 캐시 제거 프로세스는 캐시가 생성되고 높은 빈도로 삭제되는 캐시 스래싱을 일으킬 수 있습니다. 이를 줄이기 위해 리포지토리에 대한 캐시를 검토하고 특정 워크플로 에서 캐싱을 제거하거나 캐시 크기를 늘리는 등의 수정 단계를 수행할 수 있습니다. 이 기능은 캐시 설정을 구성하여 사용하도록 선택한, 등록된 결제 수단이 있는 사용자에게만 제공됩니다. 캐시 관리을 참조하세요.

리포지토리당 분당 최대 200개의 업로드 속도로 캐시 항목을 만들고 리포지토리당 분당 1500 다운로드 속도로 다운로드할 수 있습니다. 이 속도를 초과하면 관련 속도 제한이 재설정될 때까지 후속 캐시 업로드 또는 다운로드 시도가 실패합니다. 응답 헤더의 속도 제한이 초기화되기까지의 시간이 반환됩니다. 속도 제한에 대한 자세한 내용은 작업 제한 을 GitHub Actions 참조하세요.

캐시 크기 늘리기

캐시 항목이 제거되는 속도를 줄이려면 작업 설정에서 캐시에 대한 스토리지 제한을 늘릴 수 있습니다. 사용자가 소유한 리포지토리는 리포지토리당 최대 10TB를 구성할 수 있습니다. 조직이 소유한 리포지토리의 경우 구성 가능한 최대 한도는 조직의 설정에 따라 결정됩니다. 엔터프라이즈가 소유한 조직의 경우 구성 가능한 최대 제한은 엔터프라이즈 설정에 따라 결정됩니다. 해당 스토리지를 사용하는 경우 기본 10GB를 초과하는 제한을 늘리면 추가 비용이 발생합니다.

자세한 내용은 다음을 참조하세요.

추가 스토리지 사용량도 GitHub Actions 또는 Actions 캐시 스토리지 SKU에 대해 설정된 예산에 의해 제어됩니다. 한도가 구성되어 있고 예산을 초과하는 경우 청구 상태가 확인될 때까지 캐시가 읽기 전용이 되거나 캐시가 만료되거나 명시적으로 삭제되어 사용량이 10GB의 무료 한도를 초과하게 됩니다. 예산을 설정하는 방법에 대한 자세한 내용은 예산을 설정하여 요금제 제품에 대한 지출을 제어합니다.을 참조하세요.

작업 캐시 스토리지 SKU 예산을 청구 기간 동안 구성된 스토리지를 사용하는 총 비용보다 낮게 설정하면 캐시가 읽기 전용 모드로 자주 전환됩니다. 예를 들어 SKU에 대한 예산이 $0이고 리포지토리의 최대 캐시 크기를 20GB로 구성한 경우 스토리지가 사용 가능한 임계값을 초과하는 즉시 캐시가 읽기 전용 모드로 전환됩니다.

다음은 Actions Cache Storage SKU의 예산 설정에 참고할 수 있는 몇 가지 예시적인 월별 비용입니다.

캐시 크기	월별 비용(완전히 활용된 경우)
50GB	$2.80
200GB	$13.30
1000GB	$69.30

다음 단계

종속성 캐시를 관리하려면 캐시 관리을(를) 참조하세요.

이 기사에서