Skip to main content

This version of GitHub Enterprise was discontinued on 2023-07-06. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

After a site administrator upgrades your Enterprise Server instance to Enterprise Server 3.9 or later, the REST API will be versioned. To learn how to find your instance's version, see "About versions of GitHub Docs". For more information, see "About API versioning."

GitHub Actions Cache

Use the REST API to interact with the cache for repositories in GitHub Actions.

About the cache in GitHub Actions

You can use the REST API to query and manage the cache for repositories in GitHub Actions. You can also install a GitHub CLI extension to manage your caches from the command line. For more information, see "Caching dependencies to speed up workflows."

Get GitHub Actions cache usage for an enterprise

Gets the total GitHub Actions cache usage for an enterprise. The data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated. You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

Parameters for "Get GitHub Actions cache usage for an enterprise"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
enterprise string Required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

HTTP response status codes for "Get GitHub Actions cache usage for an enterprise"

Status codeDescription
200

OK

Code samples for "Get GitHub Actions cache usage for an enterprise"

get/enterprises/{enterprise}/actions/cache/usage
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/cache/usage

Response

Status: 200
{ "total_active_caches_size_in_bytes": 3344284, "total_active_caches_count": 5 }

Get GitHub Actions cache usage policy for an enterprise

Gets the GitHub Actions cache usage policy for an enterprise. You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

Parameters for "Get GitHub Actions cache usage policy for an enterprise"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
enterprise string Required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

HTTP response status codes for "Get GitHub Actions cache usage policy for an enterprise"

Status codeDescription
200

OK

Code samples for "Get GitHub Actions cache usage policy for an enterprise"

get/enterprises/{enterprise}/actions/cache/usage-policy
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/cache/usage-policy

Response

Status: 200
{ "repo_cache_size_limit_in_gb": 10, "max_repo_cache_size_limit_in_gb": 15 }

Set GitHub Actions cache usage policy for an enterprise

Sets the GitHub Actions cache usage policy for an enterprise. You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

Parameters for "Set GitHub Actions cache usage policy for an enterprise"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
enterprise string Required

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Body parameters
Name, Type, Description
repo_cache_size_limit_in_gb integer

For repositories in an enterprise, the default size limit for the sum of all caches in a repository, in gigabytes.

max_repo_cache_size_limit_in_gb integer

For repositories in an enterprise, the maximum value that can be set as the limit for the sum of all caches in a repository, in gigabytes.

HTTP response status codes for "Set GitHub Actions cache usage policy for an enterprise"

Status codeDescription
204

No Content

Code samples for "Set GitHub Actions cache usage policy for an enterprise"

patch/enterprises/{enterprise}/actions/cache/usage-policy
curl -L \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/cache/usage-policy \ -d '{"repo_cache_size_limit_in_gb":10,"max_repo_cache_size_limit_in_gb":15}'

Response

Status: 204

Get GitHub Actions cache usage for an organization

Works with GitHub Apps

Gets the total GitHub Actions cache usage for an organization. The data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated. You must authenticate using an access token with the read:org scope to use this endpoint. GitHub Apps must have the organization_admistration:read permission to use this endpoint.

Parameters for "Get GitHub Actions cache usage for an organization"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
org string Required

The organization name. The name is not case sensitive.

HTTP response status codes for "Get GitHub Actions cache usage for an organization"

Status codeDescription
200

OK

Code samples for "Get GitHub Actions cache usage for an organization"

get/orgs/{org}/actions/cache/usage
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://HOSTNAME/api/v3/orgs/ORG/actions/cache/usage

Response

Status: 200
{ "total_active_caches_size_in_bytes": 3344284, "total_active_caches_count": 5 }

List repositories with GitHub Actions cache usage for an organization

Works with GitHub Apps

Lists repositories and their GitHub Actions cache usage for an organization. The data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated. You must authenticate using an access token with the read:org scope to use this endpoint. GitHub Apps must have the organization_admistration:read permission to use this endpoint.

Parameters for "List repositories with GitHub Actions cache usage for an organization"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
org string Required

The organization name. The name is not case sensitive.

Query parameters
Name, Type, Description
per_page integer

The number of results per page (max 100).

Default: 30

page integer

Page number of the results to fetch.

Default: 1

HTTP response status codes for "List repositories with GitHub Actions cache usage for an organization"

Status codeDescription
200

OK

Code samples for "List repositories with GitHub Actions cache usage for an organization"

get/orgs/{org}/actions/cache/usage-by-repository
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://HOSTNAME/api/v3/orgs/ORG/actions/cache/usage-by-repository

Response

Status: 200
{ "total_count": 2, "repository_cache_usages": [ { "full_name": "octo-org/Hello-World", "active_caches_size_in_bytes": 2322142, "active_caches_count": 3 }, { "full_name": "octo-org/server", "active_caches_size_in_bytes": 1022142, "active_caches_count": 2 } ] }

Get GitHub Actions cache usage for a repository

Works with GitHub Apps

Gets GitHub Actions cache usage for a repository. The data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated. Anyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.

Parameters for "Get GitHub Actions cache usage for a repository"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
owner string Required

The account owner of the repository. The name is not case sensitive.

repo string Required

The name of the repository without the .git extension. The name is not case sensitive.

HTTP response status codes for "Get GitHub Actions cache usage for a repository"

Status codeDescription
200

OK

Code samples for "Get GitHub Actions cache usage for a repository"

get/repos/{owner}/{repo}/actions/cache/usage
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/actions/cache/usage

Response

Status: 200
{ "full_name": "octo-org/Hello-World", "active_caches_size_in_bytes": 2322142, "active_caches_count": 3 }

Get GitHub Actions cache usage policy for a repository

Works with GitHub Apps

Gets GitHub Actions cache usage policy for a repository. You must authenticate using an access token with the repo scope to use this endpoint. GitHub Apps must have the actions:read permission to use this endpoint.

Parameters for "Get GitHub Actions cache usage policy for a repository"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
owner string Required

The account owner of the repository. The name is not case sensitive.

repo string Required

The name of the repository without the .git extension. The name is not case sensitive.

HTTP response status codes for "Get GitHub Actions cache usage policy for a repository"

Status codeDescription
200

OK

Code samples for "Get GitHub Actions cache usage policy for a repository"

get/repos/{owner}/{repo}/actions/cache/usage-policy
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/actions/cache/usage-policy

Response

Status: 200
{ "repo_cache_size_limit_in_gb": 14 }

Set GitHub Actions cache usage policy for a repository

Works with GitHub Apps

Sets GitHub Actions cache usage policy for a repository. You must authenticate using an access token with the repo scope to use this endpoint. GitHub Apps must have the actions:write permission to use this endpoint.

Parameters for "Set GitHub Actions cache usage policy for a repository"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
owner string Required

The account owner of the repository. The name is not case sensitive.

repo string Required

The name of the repository without the .git extension. The name is not case sensitive.

Body parameters
Name, Type, Description
repo_cache_size_limit_in_gb integer Required

The size limit for the sum of all caches, in gigabytes.

HTTP response status codes for "Set GitHub Actions cache usage policy for a repository"

Status codeDescription
204

No Content

Code samples for "Set GitHub Actions cache usage policy for a repository"

patch/repos/{owner}/{repo}/actions/cache/usage-policy
curl -L \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/actions/cache/usage-policy \ -d '{"repo_cache_size_limit_in_gb":14}'

Response

Status: 204