종속성 캐싱 참조

`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: 선택적 사용하도록 설정된 경우 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@v4

      - 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@v4

      - 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 package-lock.json 파일의 해시를 계산하는 식을 사용하여 key를 만들 수 있습니다. 따라서 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를 검색합니다.

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

특정 패키지 관리자에 대한 `setup-*` 작업

아래에 나열된 패키지 관리자를 캐싱하는 경우 해당 설치-* 작업을 사용하려면 최소한의 구성이 필요하며 종속성 캐시를 만들고 복원합니다.

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

캐시 액세스 제한 사항

액세스 제한은 서로 다른 분기 또는 태그 간에 논리적 경계를 만들어 캐시 격리 및 보안을 제공합니다. 워크플로 실행은 현재 분기 또는 기본 분기(일반적으로 main)에서 만든 캐시를 복원할 수 있습니다. 끌어오기 요청에 대해 워크플로 실행이 트리거되면 포크된 리포지토리의 기본 분기를 포함하여 베이스 분기에서 생성된 캐시를 복원할 수도 있습니다. 예를 들어 분기 feature-b에 베이스 분기 feature-a이(가) 있는 경우 끌어오기 요청에서 트리거된 워크플로 실행은 기본 main 분기, 베이스 feature-a 분기 및 현재 feature-b 분기에서 생성된 캐시에 액세스할 수 있습니다.

워크플로 실행은 자식 분기 또는 형제 분기에 대해 생성된 캐시를 복원할 수 없습니다. 예를 들어 자식 feature-b 분기에 대해 생성된 캐시는 부모 main 분기에서 트리거된 워크플로 실행에 액세스할 수 없습니다. 마찬가지로 베이스 main이(가) 있는 feature-a 분기에 대해 생성된 캐시는 베이스 main을(를) 사용하여 해당 형제 feature-c 분기에 액세스할 수 없습니다. 워크플로 실행은 다른 태그 이름에 대해 생성된 캐시를 복원할 수도 없습니다. 예를 들어 베이스 main이(가) 있는 태그 release-a에 대해 생성된 캐시는 베이스 main이(가) 있는 태그 release-b에 대해 트리거된 워크플로 실행에 액세스할 수 없습니다.

끌어오기 요청에서 트리거된 워크플로 실행에 의해 캐시가 생성되면 병합 참조(refs/pull/.../merge)에 대한 캐시가 생성됩니다. 이 때문에 캐시의 범위가 제한되며 끌어오기 요청을 다시 실행해야만 복원할 수 있습니다. 베이스 분기 또는 해당 베이스 분기를 대상으로 하는 다른 끌어오기 요청으로는 복원할 수 없습니다.

리포지토리에서 여러 워크플로 실행을 통해 캐시를 공유할 수 있습니다. 워크플로 내의 분기에 대해 만든 캐시는 동일한 리포지토리 및 분기에 대한 다른 워크플로 실행에서 액세스하고 복원할 수 있습니다.

사용 제한 및 제거 정책

GitHub는 7일 동안 액세스되지 않은 캐시 항목을 제거합니다. 저장할 수 있는 캐시 수에는 제한이 없지만 리포지토리에 있는 모든 캐시의 총 크기는 제한됩니다10GB까지. 리포지토리가 최대 캐시 스토리지에 도달하면, 캐시 제거 정책에 따라 가장 오래전에 액세스된 캐시부터 최근에 액세스된 캐시 순으로 삭제하여 공간을 확보합니다.

이 제한을 초과하면 GitHub는 새 캐시를 저장하지만 총 크기가 리포지토리 한도 미만이 될 때까지 캐시 제거를 시작합니다. 캐시 제거 프로세스로 인해 캐시가 높은 빈도로 생성되고 삭제되는 캐시 스래싱을 일으킬 수 있습니다. 이를 줄이려면 리포지토리의 캐시를 검토하고 특정 워크플로에서 캐싱을 제거하는 등의 수정 단계를 수행할 수 있습니다. 캐시 관리을(를) 참조하세요.

다음 단계

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

종속성 캐싱 참조

이 문서의 내용