Merge pull request #45003 from github/repo-sync

Repo sync

Author: docs-bot

.github/instructions/content.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "content/**,data/**,**/*.md"
+applyTo: "content/**,data/**"
 ---
 
 # Copilot content instructions for docs.github.com

.github/instructions/style-guide-summary.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "content/**,data/**,**/*.md"
+applyTo: "content/**,data/**"
 ---
 
 # Concise style guide for docs.github.com

content/actions/concepts/workflows-and-actions/dependency-caching.md

@@ -27,6 +27,14 @@ Workflow runs often reuse the same outputs or downloaded dependencies from one r
 
 For more information on workflow run artifacts, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts).
 
+## Cache security
+
+Caches are shared based on the branch or tag a workflow run uses, not on the identity of the workflow or job. See [AUTOTITLE](/actions/reference/workflows-and-actions/events-that-trigger-workflows) and the `GITHUB_REF` for the branch used for various workflow triggers. Any run that can read a cache restores its contents as-is, so you should treat restored files as untrusted input and never store secrets or other sensitive data in a cache.
+
+Untrusted workflows can read sensitive cache contents, such as when a `pull_request` from a fork restores a cache. Poisoned caches can lead to code execution in trusted workflows. To limit the risk of cache poisoning, {% data variables.product.github %} gives workflows that run in response to low-trust triggers read-only access to caches in the default branch's scope.
+
+For details on cache scope, access restrictions, and best practices for using caches securely, see [AUTOTITLE](/actions/reference/dependency-caching-reference#cache-access-for-low-trust-workflow-triggers).
+
 ## Next steps
 
 To implement dependency caching in your workflows, see [AUTOTITLE](/actions/reference/dependency-caching-reference).

content/actions/reference/workflows-and-actions/dependency-caching.md

@@ -261,6 +261,37 @@ Multiple workflow runs in a repository can share caches. A cache created for a b
 
 {% endif %}
 
+## Cache access for low-trust workflow triggers
+
+Some workflows run in response to events that can be initiated by people who do not have write access to the repository, such as a fork pull request or an issue comment. When these events run in the context of the default branch, they could be used to write a malicious cache that a later, more privileged workflow restores and trusts. This class of attack is known as _cache poisoning_.
+
+To reduce this risk, only these workflow triggers can create or overwrite caches in the default branch’s scope:
+ * `push`
+ * `workflow_dispatch`
+ * `repository_dispatch`
+ * `delete`
+ * `registry_package`
+ * `page_build`
+ * `schedule`
+
+Runs triggered by any other event that resolves to the default branch are given read-only access to caches in the default branch's scope. These runs can restore existing caches but cannot create or overwrite them. This includes triggers whose payload or initiating actor can be influenced by someone outside the repository, such as `pull_request_target`, `issue_comment`, and `workflow_run`.
+
+The `pull_request` event is not affected. Caches created by a `pull_request` run are already scoped to the merge ref (`refs/pull/.../merge`) and cannot be written to the default branch's scope. For more information, see [Restrictions for accessing a cache](#restrictions-for-accessing-a-cache).
+
+When a run with read-only cache access tries to save a cache, the save fails but the step and the job do not. The workflow continues, and the failure is reported as a warning in the workflow log. In that case, consider the following:
+ * To retain the performance benefits of caching on the default branch scope, ensure there is a trusted workflow that keeps the cache updated, for example a CI build triggered by a `push` to the default branch. Those cache entries can then be restored by workflows triggered by low-trust events such as `pull_request_target`.
+ * In low-trust workflows, switch to a restore-only cache operation such as `actions/cache/restore` to make the intended cache usage clear and avoid the warning in the workflow run logs.
+
+## Best practices for using caches securely
+
+Cache contents are not signed or verified, and any workflow run that can read a cache may extract its contents. Extracted caches may modify files that are subsequently executed in a workflow run, leading to malicious code execution. Follow these practices to reduce the security risk of using caches.
+
+ * **Don't store sensitive information in a cache.** Anyone who can open a pull request against your repository can read the contents of caches in the base branch. Don't write secrets, tokens, or credentials to a cached path. Store sensitive values as secrets instead. See [AUTOTITLE](/actions/concepts/security/secrets).
+ * **Save caches from trusted triggers.** Restrict cache writes to workflows triggered by trusted actors (typically those with write access to the repository). See [Cache access for low-trust workflow triggers](#cache-access-for-low-trust-workflow-triggers) for the default restrictions that are enforced to limit what workflow triggers can write to the cache. Additionally, consider using environments with deployment protection rules to further limit the workflows that can modify the cache. See [AUTOTITLE](/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments).
+ * **Follow workflow best security practices to harden your workflows:** Limit workflows that have cache-write access to those that have been hardened against workflow vulnerabilities. Follow the guidance at [AUTOTITLE](/actions/reference/security/secure-use#writing-workflows) to prevent vulnerabilities in your workflows that could lead to code execution and the introduction of malicious cache entries.
+
+For broader guidance on securing your workflows, see [AUTOTITLE](/actions/reference/security/secure-use).
+
 ## Usage limits and eviction policy
 
 {% data variables.product.prodname_dotcom %} applies limits to cache storage and retention to manage storage costs and prevent abuse. Understanding these limits helps you optimize your cache usage.