Add cache section for Actions REST API (github#24924)

* Add cache section for Actions REST API

* Add permissions entries, cache section

* Add new cache directory after REST reactify changes

* Update content/actions/using-workflows/caching-dependencies-to-speed-up-workflows.md

Co-authored-by: Martin Lopes <[email protected]>

* Add versioning for GHES/AE

Co-authored-by: Martin Lopes <[email protected]>
Co-authored-by: Felicity Chapman <[email protected]>

Author: 3 people

content/actions/using-workflows/caching-dependencies-to-speed-up-workflows.md

@@ -234,3 +234,11 @@ For example, if a pull request contains a `feature` branch (the current scope) a
 ## Usage limits and eviction policy
 
 {% data variables.product.prodname_dotcom %} will remove any cache entries that have not been accessed in over 7 days. There is no limit on the number of caches you can store, but the total size of all caches in a repository is limited to 10 GB. If you exceed this limit, {% data variables.product.prodname_dotcom %} will save your cache but will begin evicting caches until the total size is less than 10 GB.
+
+{% if actions-cache-management %}
+
+## Managing caches
+
+You can use the {% data variables.product.product_name %} REST API to manage your caches. At present, you can use the API to see your cache usage, with more functionality expected in future updates. For more information, see the "[Actions](/rest/reference/actions#cache)" REST API documentation.
+
+{% endif %}

content/rest/overview/permissions-required-for-github-apps.md

@@ -121,6 +121,9 @@ _Search_
 - [`GET /repos/:owner/:repo/actions/artifacts/:artifact_id`](/rest/reference/actions#get-an-artifact) (:read)
 - [`DELETE /repos/:owner/:repo/actions/artifacts/:artifact_id`](/rest/reference/actions#delete-an-artifact) (:write)
 - [`GET /repos/:owner/:repo/actions/artifacts/:artifact_id/zip`](/rest/reference/actions#download-an-artifact) (:read)
+{% if actions-cache-management -%}
+- [`GET /repos/:owner/:repo/actions/cache/usage`](/rest/reference/actions#get-github-actions-cache-usage-for-a-repository) (:read)
+{% endif -%}
 - [`GET /repos/:owner/:repo/actions/jobs/:job_id`](/rest/reference/actions#get-a-job-for-a-workflow-run) (:read)
 - [`GET /repos/:owner/:repo/actions/jobs/:job_id/logs`](/rest/reference/actions#download-job-logs-for-a-workflow-run) (:read)
 - [`GET /repos/:owner/:repo/actions/runs`](/rest/reference/actions#list-workflow-runs-for-a-repository) (:read)
@@ -644,6 +647,10 @@ _Teams_
 ### Permission on "organization administration"
 
 - [`PATCH /orgs/:org`](/rest/reference/orgs#update-an-organization) (:write)
+{% if actions-cache-management -%}
+- [`GET /orgs/:org/actions/cache/usage`](/rest/reference/actions#get-github-actions-cache-usage-for-an-organization) (:read)
+- [`GET /orgs/:org/actions/cache/usage-by-repository`](/rest/reference/actions#list-repositories-with-github-actions-cache-usage-for-an-organization) (:read)
+{% endif -%}
 {% ifversion fpt -%}
 - [`GET /orgs/:org/interaction-limits`](/rest/reference/interactions#get-interaction-restrictions-for-an-organization) (:read)
 {% endif -%}

data/features/actions-cache-management.yml

@@ -0,0 +1,7 @@
+# Reference: #6154
+# Documentation for Actions cache management APIs (initial ship)
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '> 3.4'
+  ghae: 'issue-6154'

data/reusables/rest-reference/actions/cache.md

@@ -0,0 +1,3 @@
+## Cache
+
+The cache API allows you to query and manage the {% data variables.product.prodname_actions %} cache for repositories. For more information, see "[Caching dependencies to speed up workflows](/actions/advanced-guides/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy)."