Справочник по кэшированию зависимостей

cache использование действия

Действие cache попытается выполнить следующую последовательность при восстановлении кэша:

1. Во-первых, он ищет точное совпадение с предоставленным key.
2. Если точное совпадение не найдено, он будет искать частичные совпадения key.
3. Если совпадения по-прежнему не найдено, и вы указали restore-keys, эти ключи будут проверяться последовательно для частичных совпадений. Дополнительные сведения см. в разделе "Сопоставление ключей кэша".

Если есть точное совпадение с предоставленным key, это считается попаданием в кэш. Если кэш точно не соответствует предоставленному key, это считается пропущенным кэшем. Если задание выполнено успешно, действие автоматически создает новый кэш. В новом кэше будет использоваться предоставленный вами key, а также будут содержаться файлы, указанные в path. Дополнительные сведения о том, как это обрабатывается, см. в разделе "Кэширование попаданий и пропущений".

Невозможно изменить содержимое существующего кэша. Вместо этого можно создать новый кэш с новым ключом.

Входные параметры для действия cache

• key. Требуется Ключ, созданный при сохранении кэша, и ключ, используемый для поиска кэша. Это может быть любое сочетание переменных, значений контекста, статических строк и функций. Ключи имеют максимальную длину в 512 символов, а использование ключей большей длины приведет к сбою действия.

• path. Требуется (требуются) Путь (пути) в средстве выполнения тестов для кэширования или восстановления.

  • Вы можете указать один путь или добавить несколько путей в отдельных строках. Например:

    - name: Cache Gradle packages
      uses: actions/cache@v4
      with:
        path: |
          ~/.gradle/caches
          ~/.gradle/wrapper
    

  • Вы можете указать либо каталоги, либо отдельные файлы. Также поддерживаются стандартные маски.

  • Можно указать абсолютные пути или пути относительно каталога рабочей области.

• restore-keys. Необязательно Строка, содержащая альтернативные ключи восстановления, где каждый ключ восстановления, находится в новой строке. Если для key не происходит попадание в кэше, эти ключи восстановления используются последовательно в указанном порядке для поиска и восстановления кэша. Например:

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

• enableCrossOsArchive: Опционально Булево значение, которое при активации позволяет Windows участникам сохранять или восстанавливать кэши независимо от операционной системы, на которой был создан кэш. Если этот параметр не задан, он по умолчанию имеет значение false. Дополнительные сведения см . в документации по кэшу кэша действий между ОС.

Входные параметры для действия cache

• cache-hit. Логическое значение, указывающее, что для ключа найдено точное совпадение.

Попадания и пропущенные кэши

Когда key точно соответствует существующему кэшу, он называется попаданием в кэш, а действие восстанавливает кэшированные файлы в path каталог.

При отсутствии соответствия key существующему кэшу происходит промах кэша, и если задание успешно завершено, автоматически создается новый кэш.

При промахе кэша действие также выполняет поиск указанных restore-keys для любых совпадений:

1. При указании restore-keys действие cache последовательно ищет все кэши, соответствующие списку restore-keys.
   • При точном совпадении действие восстанавливает файлы в кэше в каталог path.
   • Если точных совпадений нет, действие ищет частичные совпадения ключей восстановления. Когда действие находит частичное совпадение, в каталог path восстанавливается самый последний кэш.
2. Действие cache завершается, и выполняется следующий шаг задания.
3. Если задание завершено успешно, действие автоматически создает новый кэш с содержимым каталога path.

Более подробное описание процесса сопоставления кэша см. в разделе "Сопоставление ключей кэша".

Пример использования действия cache

В этом примере создается новый кэш при изменении пакетов в файле package-lock.json или при изменении операционной системы средства выполнения тестов. Ключ кэша использует контексты и выражения для создания ключа, который включает операционную систему средства выполнения тестов и хэш SHA-256 файла package-lock.json.

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. Дополнительные сведения см. в разделе [AUTOTITLE и Справочник по контекстам](/actions/learn-github-actions/expressions).

Использование выражений для создания key позволяет автоматически создавать новый кэш при изменении зависимостей.

Например, можно создать key с помощью выражения, которое вычисляет хэш файла npm 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.

В приведенном выше примере рабочего процесса есть шаг, в котором перечисляется состояние модулей 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 действие повторяет те же действия на ветвь по умолчанию. Обратите внимание, что ограничения области применяются во время поиска. Дополнительные сведения см. в разделе "Ограничения для доступа к кэшу".

Версия кэша — это способ метки кэша метаданными 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 совпадают с ключом восстановления. Будет использоваться кэш с последней датой создания. Ключи в этом примере выполняются в следующем порядке:

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. Ключ npm-feature-d5ea0750 в ветви feature
2. Ключ npm-feature- в ветви feature
3. Ключ npm- в ветви feature
4. Ключ npm-feature-d5ea0750 в ветви main
5. Ключ npm-feature- в ветви main
6. Ключ npm- в ветви main

setup-* действия для определенных диспетчеров пакетов

Если вы выполняете кэширование диспетчеров пакетов, перечисленных ниже, при использовании соответствующих действий установки*требуется минимальная конфигурация и будет создавать и восстанавливать кэши зависимостей.

Ограничения доступа к кэшу

Ограничения доступа обеспечивают изоляцию кэша и защиту путем создания логической границы между разными ветвями и тегами. Запуски рабочих процессов могут восстанавливать кэши, созданные в текущей ветви или в ветвь по умолчанию (обычно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). Из-за этого кэш будет иметь ограниченную область и может быть восстановлен только путем повторного выполнения запроса на вытягивание. Его невозможно восстановить с помощью базовая ветвь или других запросов на вытягивание, предназначенных для этого базовая ветвь.

Несколько рабочих процессов, выполняемых в репозитории, могут совместно использовать кэши. Кэш, созданный для ветви в выполнении рабочего процесса, может быть получен и восстановлен из другого рабочего процесса для одного репозитория и ветви.

Доступ к кэшу для триггеров рабочих процессов с низким уровнем доверия

Некоторые рабочие процессы запускаются в ответ на события, которые могут быть инициированы людьми без доступа к записи репозитория, например, форк-pull request или комментарий по проблеме. Когда эти события выполняются в контексте стандартной ветки, их можно использовать для создания вредоносного кэша, который позже, более привилегированный рабочий процесс восстанавливает и доверяет. Этот класс атаки известен как отравление тайником.

Чтобы снизить этот риск, только эти триггеры рабочих процессов могут создавать или перезаписывать кэши в области действия ветки по умолчанию:

• 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) и не могут быть записаны в область действия ветки по умолчанию. Дополнительные сведения см. в разделе "Ограничения для доступа к кэшу".

Когда запуск с доступом только к кэшу для чтения пытается сохранить кэш, сохранение терпит неудачу, но шаг и задание — нет. Рабочий процесс продолжается, и сбой фиксируется как предупреждение в журнале рабочего процесса. В таком случае рассмотрим следующее:

• Чтобы сохранить преимущества в производительности кэширования на стандартной области ветки, убедитесь, что существует доверенный рабочий процесс, который поддерживает обновление кэша, например, CI-билд, запускаемый push a в стандартную ветку. Эти записи кэша затем могут быть восстановлены с помощью рабочих процессов, запускаемых событиями с низким уровнем доверия, такими pull_request_targetкак .
• В рабочих процессах с низким уровнем доверия переходите к операции кэша только с восстановлением, чтобы actions/cache/restore сделать задуманный кэш ясным и избежать предупреждения в журналах запуска рабочего процесса.

Лучшие практики безопасного использования кэшей

Содержимое кэша не подписывается и не проверяется, и любой рабочий процесс, способный читать кэш, может извлечь его содержимое. Извлечённые кэши могут изменять файлы, которые затем выполняются в процессе, что приводит к выполнению вредоносного кода. Следуйте этим практикам, чтобы снизить риск безопасности при использовании кэшей.

• Не храните конфиденциальную информацию в кэше. Любой, кто может открыть pull request к вашему репозиторию, может читать содержимое кэшей в базовой ветке. Не записывайте секреты, жетоны или учетные данные в кэшированный путь. Храните чувствительные значения как секреты. См . раздел AUTOTITLE.
• Сохраняйте кэши с доверенных триггеров. Ограничьте запись в кэше рабочими процессами, запускаемыми доверенными акторами (обычно теми, кто имеет доступ к репозиторию). См. раздел «Доступ к кэшу» для триггеров рабочих процессов с низким уровнем доверия , чтобы узнать о стандартных ограничениях, которые ограничивают, какие триггеры рабочих процессов могут записывать в кэш. Кроме того, рассмотрите возможность использования сред с правилами защиты развертывания для дальнейшего ограничения рабочих процессов, которые могут изменять кэш. См . раздел AUTOTITLE.
• Следуйте лучшим практикам безопасности рабочих процессов для усиления ваших рабочих процессов: Ограничьте рабочие процессы с доступом к кэш-записи только теми, которые были защищены уязвимостями рабочих процессов. Следуйте рекомендациям в AUTOTITLE , чтобы предотвратить уязвимости в ваших рабочих процессах, которые могут привести к выполнению кода и появлению вредоносных записей в кэше.

Для более широких рекомендаций по безопасности ваших рабочих процессов смотрите Справочник по безопасному использованию.

Ограничения использования и политика вытеснения

GitHub применяет ограничения на хранение и хранение кэша для управления затратами на хранение и предотвращения злоупотреблений. Понимание этих ограничений помогает оптимизировать использование кэша.

Ограничения по умолчанию

GitHub удалит все записи в кэше, которые не были доступны более 7 дней. Нет ограничений на количество кэшей, которые можно хранить, но общий размер всех кэшей в репозитории ограничен. По умолчанию лимит составляет 10 ГБ на репозиторий, но этот лимит может быть увеличен владельцами предприятий, организаций или администраторами репозиториев. После достижения максимального хранилища кэша политика вытеснения кэша создаст пространство, удалив кэши в порядке последней даты доступа, начиная с последней до последней.

Если это ограничение превышено, GitHub сохранит новый кэш, но начнет вытеснять кэши до тех пор, пока общий размер не станет меньше ограничения репозитория. Процесс удаления кэша может вызвать кэш трэшинг, когда кэши создаются и удаляются с высокой частотой. Чтобы уменьшить это, можно просматривать кэши для репозитория и предпринимать корректирующие меры, например, убрать кэширование из определённых рабочих процессов. См. Управление кэшами. Вы также можете увеличить лимит размера кэша для репозитория. Дополнительные сведения см. в разделе Управление настройками GitHub Actions для репозитория.

Следующие шаги

Сведения об управлении кэшами зависимостей см. в разделе Управление кэшами.