의존성 캐싱 참조(Dependency caching reference)

의존성 캐싱 참조(Dependency caching reference)

워크플로에서 의존성 캐싱의 기능에 대한 정보를 알려드릴게요. 캐시 키 매칭과 보안 제한을 이해하면 캐싱을 안전하고 효율적으로 쓸 수 있어요.

출처: 문서

본문

워크플로에서 의존성 캐싱의 기능에 대한 정보를 확인할 수 있습니다.

cache 액션 사용법

cache 액션은 캐시를 복원할 때 다음 순서를 시도합니다:

1. 먼저 제공한 key에 대한 정확한 일치를 검색합니다.
2. 정확한 일치가 없으면 key의 부분 일치를 검색합니다.
3. 여전히 일치가 없고 restore-keys를 제공했다면 이 키들을 순서대로 부분 일치 여부를 확인합니다. 자세한 내용은 Cache key matching을 참고하세요.

제공한 key에 대한 정확한 일치가 있으면 이를 캐시 히트(cache hit)라고 합니다. 제공한 key와 정확히 일치하는 캐시가 없으면 캐시 미스(cache miss)라고 합니다. 캐시 미스가 발생하면 잡이 성공적으로 완료될 때 액션이 자동으로 새 캐시를 만듭니다. 새 캐시는 제공한 key를 사용하며 path에 지정한 파일을 포함합니다. 이것이 처리되는 방법에 대한 자세한 내용은 Cache hits and misses를 참고하세요.

기존 캐시의 내용을 변경할 수는 없습니다. 대신 새 키로 새 캐시를 만들 수 있습니다.

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 러너가 캐시가 생성된 운영 체제와 무관하게 캐시를 저장하거나 복원할 수 있게 하는 boolean 값입니다. 이 파라미터를 설정하지 않으면 기본값은 false입니다. 자세한 내용은 Actions Cache 문서의 Cross OS cache를 참고하세요.

[!NOTE] 액세스 토큰이나 로그인 자격 증명 같은 민감한 정보를 캐시 경로의 파일에 저장하지 않는 것이 좋습니다. 읽기 접근 권한이 있는 사람은 누구나 저장소에 풀 리퀘스트를 만들고 캐시 내용에 접근할 수 있습니다. 또한 저장소의 포크는 베이스 브랜치에 풀 리퀘스트를 만들고 베이스 브랜치의 캐시에 접근할 수 있습니다.

cache 액션의 출력 파라미터

• cache-hit: 키에 대한 정확한 일치가 발견되었는지 나타내는 boolean 값입니다.

캐시 히트와 미스

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 해시를 포함하는 키를 생성합니다.

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가 지원하는 모든 컨텍스트, 함수, 리터럴, 연산자가 포함될 수 있습니다. 자세한 내용은 Contexts reference와 Evaluate expressions in workflows and 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로 설정됩니다.

위의 예시 워크플로에서 캐시 미스가 발생하면 Node 모듈의 상태를 나열하는 스텝이 있습니다:

- 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와 캐시 생성 시 사용된 압축 도구의 메타데이터로 캐시에 스탬프를 찍는 방법입니다. 이를 통해 소비 워크플로 실행이 실제로 압축 해제하고 사용할 수 있는 캐시와 고유하게 일치하도록 보장합니다. 자세한 내용은 Actions Cache 문서의 Cache Version을 참고하세요.

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 두 키 모두 복원 키와 일치합니다. 생성 날짜가 가장 최근인 캐시가 사용됩니다. 이 예시의 키들은 다음 순서로 검색됩니다:

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

검색 우선순위 예시

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

예를 들어 풀 리퀘스트에 feature 브랜치가 포함되고 기본 브랜치(main)를 대상으로 한다면, 액션은 다음 순서로 key와 restore-keys를 검색합니다:

1. feature 브랜치의 키 npm-feature-d5ea0750
2. feature 브랜치의 키 npm-feature-
3. feature 브랜치의 키 npm-
4. main 브랜치의 키 npm-feature-d5ea0750
5. main 브랜치의 키 npm-feature-
6. main 브랜치의 키 npm-

특정 패키지 매니저용 setup-* 액션

아래 나열된 패키지 매니저를 캐시한다면 해당하는 setup-* 액션을 사용하는 것이 최소한의 구성으로 충분하며, 의존성 캐시를 만들어 복원해 줍니다.

Package managers	setup-* action for caching
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에 대해 트리거된 워크플로 실행에서 접근할 수 없습니다.

풀 리퀘스트에서 트리거된 워크플로 실행이 캐시를 만들면 해당 캐시는 머지 ref(refs/pull/.../merge)용으로 생성됩니다. 이로 인해 캐시는 제한된 스코프를 가지며 풀 리퀘스트의 재실행에서만 복원될 수 있습니다. 베이스 브랜치나 해당 베이스 브랜치를 대상으로 하는 다른 풀 리퀘스트는 복원할 수 없습니다.

저장소의 여러 워크플로 실행이 캐시를 공유할 수 있습니다. 워크플로 실행에서 브랜치를 위해 생성된 캐시는 같은 저장소와 브랜치의 다른 워크플로 실행에서 접근하고 복원할 수 있습니다.

저신뢰 워크플로 트리거의 캐시 접근

일부 워크플로는 저장소에 write 접근 권한이 없는 사람이 시작할 수 있는 이벤트에 응답해서 실행됩니다. 예를 들어 포크 풀 리퀘스트나 이슈 댓글이 있습니다. 이러한 이벤트가 기본 브랜치의 컨텍스트에서 실행되면 나중에 더 권한 있는 워크플로가 복원하고 신뢰하는 악성 캐시를 쓰는 데 사용될 수 있습니다. 이 공격 클래스를 *캐시 오염(cache poisoning)*이라고 합니다.

이 위험을 줄이기 위해 다음 워크플로 트리거만 기본 브랜치 스코프의 캐시를 생성하거나 덮어쓸 수 있습니다:

• push
• workflow_dispatch
• repository_dispatch
• delete
• registry_package
• page_build
• schedule

기본 브랜치로 해석되는 다른 이벤트로 트리거된 실행은 기본 브랜치 스코프의 캐시에 대해 읽기 전용 접근을 받습니다. 이러한 실행은 기존 캐시를 복원할 수 있지만 생성하거나 덮어쓸 수는 없습니다. 여기에는 페이로드나 시작 주체가 저장소 외부의 누군가에 의해 영향을 받을 수 있는 트리거, 예를 들어 pull_request_target, issue_comment, workflow_run이 포함됩니다. 저장소는 특정 워크플로나 잡에 대해 write 가능한 cache-mode를 명시적으로 선언해서 이 제한에서 제외될 수 있습니다. Bypassing the default untrusted-trigger cache restriction을 참고하세요.

pull_request 이벤트는 영향을 받지 않습니다. pull_request 실행이 만든 캐시는 이미 머지 ref(refs/pull/.../merge)로 스코프가 지정되어 기본 브랜치 스코프에 쓸 수 없습니다. 자세한 내용은 Restrictions for accessing a cache를 참고하세요.

읽기 전용 캐시 접근이 있는 실행이 캐시를 저장하려고 하면 저장은 실패하지만 스텝과 잡은 실패하지 않습니다. 워크플로는 계속되고 실패는 워크플로 로그에서 경고로 보고됩니다. 이 경우 다음을 고려하세요:

• 기본 브랜치 스코프에서 캐싱의 성능 이점을 유지하려면 기본 브랜치에 대한 push로 트리거되는 CI 빌드처럼 캐시를 최신 상태로 유지하는 신뢰할 수 있는 워크플로가 있는지 확인하세요. 그러면 그 캐시 항목들은 pull_request_target 같은 저신뢰 이벤트로 트리거된 워크플로가 복원할 수 있습니다.
• 저신뢰 워크플로에서는 의도한 캐시 사용을 명확히 하고 워크플로 실행 로그의 경고를 피하기 위해 actions/cache/restore 같은 복원 전용 캐시 작업으로 전환하세요.

cache-mode로 캐시 접근 제어하기

cache-mode 워크플로 키를 사용해서 잡에 필요한 최소한의 캐시 접근을 부여합니다. cache-mode는 워크플로 레벨, 잡 레벨, 또는 둘 다에 설정할 수 있습니다. 잡 레벨 값이 해당 잡의 워크플로 레벨 값을 재정의합니다. 구문은 Workflow syntax for GitHub Actions를 참고하세요.

cache-mode는 잡의 토큰에 부여되는 캐시 접근을 제어하며, 스코프가 지정된 캐시 토큰으로 강제됩니다. 이 키는 다음 값을 허용합니다.

Value	Restore caches	Save caches
read	Yes	No
write	Yes	Yes
write-only	No	Yes
none	No	No

cache-mode를 생략하면 트리거 유형에 따라 read 또는 write 기본값이 사용됩니다. Defaults와 Bypassing the default untrusted-trigger cache restriction을 참고하세요.

기본값

Configuration	Trigger type	Effective access
cache-mode omitted	Trusted	write
cache-mode omitted	Low-trust	read
cache-mode: write	Trusted or low-trust	write
cache-mode: write-only	Trusted or low-trust	write-only
cache-mode: read	Trusted or low-trust	read
cache-mode: none	Trusted or low-trust	none

신뢰 대 저신뢰 트리거 분류는 Cache access for low-trust workflow triggers를 참고하세요.

러너는 유효 모드를 ACTIONS_CACHE_MODE 환경 변수에 노출하며, actions/cache 액션과 @actions/cache 툴킷이 이를 존중합니다. 모드가 읽기를 허용하지 않으면 (none 또는 write-only) 복원이 건너뛰어지고, 모드가 쓰기를 허용하지 않으면 (none 또는 read) 저장이 건너뛰어집니다. 모드 때문에 캐시 작업이 건너뛰어지면 액션은 정보 메시지를 기록하고 스텝과 실행은 실패 없이 계속됩니다. 건너뛰어진 복원은 캐시 미스로 처리되고, 건너뛰어진 저장은 단순히 수행되지 않습니다.

재사용 가능한 워크플로의 캐시 접근

cache-mode는 호출자 워크플로에서 호출하는 재사용 가능한 워크플로로 전파됩니다. 호출 잡에 명시적인 cache-mode가 있거나 호출자 워크플로에서 상속되면 호출되는 워크플로가 요청할 수 있는 캐시 접근이 제한됩니다.

호출 잡이 명시적인 cache-mode를 설정하지도 상속하지도 않으면, 호출자의 저신뢰 트리거가 read로 기본 설정되더라도 호출되는 워크플로가 명시적으로 write를 요청할 수 있습니다. 호출되는 워크플로를 읽기 전용으로 제한하려면 호출하는 잡에 cache-mode: read를 설정하세요.

호출되는 워크플로가 이 명시적 한도를 초과하는 접근을 요청하는 cache-mode를 선언하면 실행이 시작되지 않고 GitHub가 검증 오류를 보고합니다. 예를 들어 최대 read를 허용하는 호출자는 write를 선언하는 워크플로를 호출할 수 없습니다. read와 write-only는 서로 다른 겹치지 않는 기능을 부여하므로 둘 사이의 불일치도 과잉 요청입니다. 예를 들어 write-only 호출자는 read를 선언하는 워크플로를 호출할 수 없습니다. 재사용 가능한 워크플로 호출에 대한 자세한 내용은 Reuse workflows를 참고하세요.

기본 신뢰할 수 없는 트리거 캐시 제한 우회하기

cache-mode: write나 cache-mode: write-only를 명시적으로 선언하는 잡이나 워크플로는 저신뢰 이벤트로 트리거된 실행에 적용되는 안전한 읽기 전용 기본값을 재정의합니다. Cache access for low-trust workflow triggers를 참고하세요.

[!WARNING] cache-mode: write나 cache-mode: write-only를 명시적으로 선언하면 기본 신뢰할 수 없는 트리거 읽기 전용 권한이 방지하려고 설계된 캐시 오염 위험이 다시 도입됩니다. pull_request_target, issue_comment, workflow_run 같은 신뢰할 수 없는 트리거에서 실행되는 워크플로가 write 가능한 cache-mode를 선언하면, 워크플로의 취약점이나 신뢰할 수 없는 코드 실행이 캐시를 저장하는 데 사용될 수 있습니다. 나중에 그 캐시를 복원하는 더 권한 있는 워크플로가 공격자가 제어하는 콘텐츠를 실행할 수 있습니다.

저신뢰 트리거가 있는 워크플로에서 write 가능한 cache-mode를 선언하기 전에 더 좁은 완화가 요구 사항을 충족하는지 고려하세요:

• 잡에 cache-mode: read를 명시적으로 선언해서 안전한 캐시 접근 제한을 유지하고, 대신 신뢰할 수 있는 push 트리거 워크플로가 캐시를 유지 관리하세요. Cache access for low-trust workflow triggers를 참고하세요.
• 캐시에 쓰기 전에 신뢰할 수 없는 입력을 처리하지 않는 잡에서만 저신뢰 트리거에 write 가능한 cache-mode를 선언하세요. 여기에는 포크와 풀 리퀘스트 같은 신뢰할 수 없는 소스에서 체크아웃된 코드가 포함됩니다.
• 안전한 기본값을 재정의한다면 결과 캐시를 복원하는 모든 워크플로에서 그 캐시를 신뢰할 수 없는 것으로 취급하고, 시크릿에 대한 write 접근이나 높아진 권한이 있는 실행으로 복원하지 마세요.
• 캐시를 안전하게 사용하기 위한 모범 사례 지침을 따르세요.

캐시를 안전하게 사용하기 위한 모범 사례

캐시 내용은 서명되거나 검증되지 않으며, 캐시를 읽을 수 있는 모든 워크플로 실행은 그 내용을 추출할 수 있습니다. 추출된 캐시는 이후 워크플로 실행에서 실행되는 파일을 수정할 수 있으며, 이는 악성 코드 실행으로 이어질 수 있습니다. 캐시 사용의 보안 위험을 줄이려면 다음 관행을 따르세요.

• 캐시에 민감한 정보를 저장하지 마세요. 저장소에 대해 풀 리퀘스트를 열 수 있는 사람은 누구나 베이스 브랜치의 캐시 내용을 읽을 수 있습니다. 시크릿, 토큰, 자격 증명을 캐시된 경로에 쓰지 마세요. 민감한 값은 대신 시크릿으로 저장하세요. Secrets를 참고하세요.
• 신뢰할 수 있는 트리거에서 캐시를 저장하세요. 캐시 쓰기를 신뢰할 수 있는 주체(일반적으로 저장소에 write 접근 권한이 있는 사람)가 트리거한 워크플로로 제한하세요. 어떤 워크플로 트리거가 캐시에 쓸 수 있는지 제한하기 위해 강제되는 기본 제한은 Cache access for low-trust workflow triggers를 참고하세요. 또한 배포 보호 규칙이 있는 환경을 사용해서 캐시를 수정할 수 있는 워크플로를 더 제한하는 것을 고려하세요. Managing environments for deployment를 참고하세요.
• 워크플로 보안 모범 사례를 따라 워크플로를 강화하세요: 캐시 쓰기 접근이 있는 워크플로를 워크플로 취약점에 대해 강화된 워크플로로 제한하세요. 코드 실행과 악성 캐시 항목 도입으로 이어질 수 있는 워크플로 취약점을 방지하려면 Secure use reference의 지침을 따르세요.

워크플로 보안에 대한 더 넓은 지침은 Secure use reference를 참고하세요.

사용 한도 및 퇴거(eviction) 정책

GitHub는 저장 비용을 관리하고 남용을 방지하기 위해 캐시 저장과 보존에 한도를 적용합니다. 이러한 한도를 이해하면 캐시 사용을 최적화하는 데 도움이 됩니다.

기본 한도

GitHub는 7일 이상 접근되지 않은 모든 캐시 항목을 제거합니다. 저장할 수 있는 캐시 수에는 제한이 없지만, 저장소의 모든 캐시 총 크기는 제한됩니다. 기본적으로 저장소당 10GB가 한도이지만, 이 한도는 엔터프라이즈 소유자, 조직 소유자, 또는 저장소 관리자가 늘릴 수 있습니다. 10GB를 초과하는 사용량은 계정에 청구됩니다. 저장소가 최대 캐시 저장량에 도달하면 캐시 퇴거 정책은 마지막 접근 날짜 순서(오래된 것부터 최신 것)대로 캐시를 삭제해서 공간을 만듭니다.

한도를 초과하면 GitHub는 새 캐시를 저장하지만 총 크기가 저장소 한도보다 작아질 때까지 캐시를 퇴거하기 시작합니다. 캐시 퇴거 과정은 캐시가 높은 빈도로 생성되고 삭제되는 캐시 스래싱(cache thrashing)을 일으킬 수 있습니다. 이를 줄이려면 저장소의 캐시를 검토하고 특정 워크플로에서 캐싱 제거하거나 캐시 크기 늘리기 같은 시정 조치를 취할 수 있습니다. 이 기능은 결제 방법이 등록되어 있고 캐시 설정을 구성해서 옵트인한 사용자만 사용할 수 있습니다. Managing caches를 참고하세요.

저장소당 분당 최대 200회 업로드, 분당 1500회 다운로드의 속도로 캐시 항목을 만들고 다운로드할 수 있습니다. 이 속도를 초과하면 관련 속도 제한이 리셋될 때까지 이후 캐시 업로드나 다운로드 시도가 실패합니다. 속도 제한이 리셋될 때까지의 시간은 응답의 Retry-After 헤더에 반환됩니다. GitHub Actions 속도 제한에 대한 자세한 내용은 Actions limits를 참고하세요.

캐시 크기 늘리기

캐시 항목이 퇴거되는 속도를 줄이려면 Actions Settings에서 캐시의 저장 한도를 늘릴 수 있습니다. 사용자가 소유한 저장소는 저장소당 최대 10TB까지 구성할 수 있습니다. 조직이 소유한 저장소의 경우 최대 구성 가능 한도는 조직의 설정에 의해 결정됩니다. 엔터프라이즈가 소유한 조직의 경우 최대 구성 가능 한도는 엔터프라이즈의 설정에 의해 결정됩니다. 기본 10GB를 초과해서 한도를 늘리면, 해당 저장소가 사용될 경우 추가 비용이 발생합니다.

자세한 내용은 다음을 참고하세요:

• Managing GitHub Actions settings for a repository
• Disabling or limiting GitHub Actions for your organization
• Enforcing policies for GitHub Actions in your enterprise

추가 저장소 사용은 GitHub Actions 또는 Actions Cache Storage SKU에 설정된 예산으로도 제어됩니다. 한도를 구성했고 예산을 초과하면 캐시가 결제 상태가 해결되거나, 캐시가 만료되거나 명시적으로 삭제되어 사용량이 10GB의 무료 한도 아래로 내려갈 때까지 캐시가 읽기 전용이 됩니다. 예산 설정 방법에 대한 자세한 내용은 Setting up budgets to control spending on metered products를 참고하세요.

Actions Cache Storage SKU 예산을 결제 기간 동안 구성된 저장소를 사용하는 총 비용보다 낮게 설정하면 캐시가 자주 읽기 전용 모드로 들어갈 수 있습니다. 예를 들어 SKU 예산이 $0이고 저장소의 최대 캐시 크기를 20GB로 구성했다면, 저장량이 무료 임계값을 초과하는 즉시 캐시가 읽기 전용 모드로 들어갑니다.

아래는 Actions Cache Storage SKU에 대해 설정하고 싶을 수 있는 예산을 안내하는 예시 월 비용입니다.

Cache size	Monthly cost (if fully utilized)
50GB	$2.80
200GB	$13.30
1000GB	$69.30

다음 단계

의존성 캐시를 관리하려면 Managing caches를 참고하세요.

더 알아보기 (Learn more)

• Actions limits
• Secure use reference
• Contexts reference