Skip to main content

This version of GitHub Enterprise Server was discontinued on 2024-01-04. 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 Server. 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

List GitHub Actions caches for a repository

Works with GitHub Apps

Lists the GitHub Actions caches 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 "List GitHub Actions caches 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.

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

ref string

The full Git reference for narrowing down the cache. The ref for a branch should be formatted as refs/heads/<branch name>. To reference a pull request use refs/pull/<number>/merge.

key string

An explicit key or prefix for identifying the cache

sort string

The property to sort the results by. created_at means when the cache was created. last_accessed_at means when the cache was last accessed. size_in_bytes is the size of the cache in bytes.

Default: last_accessed_at

Can be one of: created_at, last_accessed_at, size_in_bytes

direction string

The direction to sort the results by.

Default: desc

Can be one of: asc, desc

HTTP response status codes for "List GitHub Actions caches for a repository"

Status codeDescription
200

OK

Code samples for "List GitHub Actions caches for a repository"

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

Response

Status: 200
{ "total_count": 1, "actions_caches": [ { "id": 505, "ref": "refs/heads/main", "key": "Linux-node-958aff96db2d75d67787d1e634ae70b659de937b", "version": "73885106f58cc52a7df9ec4d4a5622a5614813162cb516c759a30af6bf56e6f0", "last_accessed_at": "2019-01-24T22:45:36.000Z", "created_at": "2019-01-24T22:45:36.000Z", "size_in_bytes": 1024 } ] }

Delete GitHub Actions caches for a repository (using a cache key)

Works with GitHub Apps

Deletes one or more GitHub Actions caches for a repository, using a complete cache key. By default, all caches that match the provided key are deleted, but you can optionally provide a Git ref to restrict deletions to caches that match both the provided key and the Git ref.

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 "Delete GitHub Actions caches for a repository (using a cache key)"

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.

Query parameters
Name, Type, Description
key string Required

A key for identifying the cache.

ref string

The full Git reference for narrowing down the cache. The ref for a branch should be formatted as refs/heads/<branch name>. To reference a pull request use refs/pull/<number>/merge.

HTTP response status codes for "Delete GitHub Actions caches for a repository (using a cache key)"

Status codeDescription
200

OK

Code samples for "Delete GitHub Actions caches for a repository (using a cache key)"

delete/repos/{owner}/{repo}/actions/caches
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ "http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/actions/caches?key=Linux-node-958aff96db2d75d67787d1e634ae70b659de937b"

Response

Status: 200
{ "total_count": 1, "actions_caches": [ { "id": 505, "ref": "refs/heads/main", "key": "Linux-node-958aff96db2d75d67787d1e634ae70b659de937b", "version": "73885106f58cc52a7df9ec4d4a5622a5614813162cb516c759a30af6bf56e6f0", "last_accessed_at": "2019-01-24T22:45:36.000Z", "created_at": "2019-01-24T22:45:36.000Z", "size_in_bytes": 1024 } ] }

Delete a GitHub Actions cache for a repository (using a cache ID)

Works with GitHub Apps

Deletes a GitHub Actions cache for a repository, using a cache ID.

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 "Delete a GitHub Actions cache for a repository (using a cache ID)"

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.

cache_id integer Required

The unique identifier of the GitHub Actions cache.

HTTP response status codes for "Delete a GitHub Actions cache for a repository (using a cache ID)"

Status codeDescription
204

No Content

Code samples for "Delete a GitHub Actions cache for a repository (using a cache ID)"

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

Response

Status: 204