shithub Public

Watch 1 Fork 0 Star 0
markdown · 2555 bytes Raw Blame History

Actions caches

Read + delete surface over the workflow_caches table — shithub's record of cache tarballs uploaded by actions/cache@v* workflow steps.

The runner-side cache upload protocol that POPULATES the table is a separate sprint; this REST surface lands first so operators have an audit + purge seat for when caches arrive.

Scopes:

  • repo:read on list
  • repo:write on delete

Endpoints

GET    /api/v1/repos/{owner}/{repo}/actions/caches
DELETE /api/v1/repos/{owner}/{repo}/actions/caches
DELETE /api/v1/repos/{owner}/{repo}/actions/caches/{cache_id}

GET accepts ?key=&ref=&page=&per_page=. DELETE without a {cache_id} deletes by ?key=... and optional &ref=....

List response

{
  "total_count": 2,
  "actions_caches": [
    {
      "id":               17,
      "key":              "node-modules",
      "version":          "8f3b...",
      "ref":              "refs/heads/trunk",
      "size_bytes":       1048576,
      "last_accessed_at": "2026-05-12T18:00:00Z",
      "created_at":       "2026-05-12T17:00:00Z"
    }
  ]
}

Sorted by last_accessed_at DESC so an operator sees the live caches first. Standard Link: pagination headers are emitted when results exceed per_page (default 30, max 100).

Filter params:

  • key=<cache_key> — restrict to a single cache key.
  • ref=<git_ref> — restrict to caches created against this ref (e.g. refs/heads/trunk).

Delete by id

DELETE /api/v1/repos/alice/demo/actions/caches/17

Returns 204 No Content. The DB row is removed atomically; the tarball in object storage is purged best-effort in the background.

404 when:

  • the cache id is unknown
  • the cache exists but belongs to a different repo (existence-leak-safe)
  • the caller lacks repo:write on the target (returned as 404 by the policy gate, not 403, to keep the existence-leak guarantee)

Delete by key

DELETE /api/v1/repos/alice/demo/actions/caches?key=node-modules

Removes every cache with that key, regardless of version, scoped to the repo. Add ref=... to scope by ref as well. Returns 204 even when zero rows match (idempotent).

400 when the key query parameter is missing or empty.

Errors

Status Cause
400 DELETE-by-key without a key query parameter.
403 PAT lacks repo:write on the delete endpoints.
404 Cache id unknown or belongs to a different repo.
View source
1 # Actions caches
2
3 Read + delete surface over the `workflow_caches` table —
4 shithub's record of cache tarballs uploaded by `actions/cache@v*`
5 workflow steps.
6
7 The runner-side cache upload protocol that POPULATES the table is
8 a separate sprint; this REST surface lands first so operators have
9 an audit + purge seat for when caches arrive.
10
11 Scopes:
12
13 - `repo:read` on list
14 - `repo:write` on delete
15
16 ## Endpoints
17
18 ```
19 GET /api/v1/repos/{owner}/{repo}/actions/caches
20 DELETE /api/v1/repos/{owner}/{repo}/actions/caches
21 DELETE /api/v1/repos/{owner}/{repo}/actions/caches/{cache_id}
22 ```
23
24 `GET` accepts `?key=&ref=&page=&per_page=`. `DELETE` without a
25 `{cache_id}` deletes by `?key=...` and optional `&ref=...`.
26
27 ## List response
28
29 ```json
30 {
31 "total_count": 2,
32 "actions_caches": [
33 {
34 "id": 17,
35 "key": "node-modules",
36 "version": "8f3b...",
37 "ref": "refs/heads/trunk",
38 "size_bytes": 1048576,
39 "last_accessed_at": "2026-05-12T18:00:00Z",
40 "created_at": "2026-05-12T17:00:00Z"
41 }
42 ]
43 }
44 ```
45
46 Sorted by `last_accessed_at DESC` so an operator sees the live
47 caches first. Standard `Link:` pagination headers are emitted
48 when results exceed `per_page` (default 30, max 100).
49
50 Filter params:
51
52 - `key=<cache_key>` — restrict to a single cache key.
53 - `ref=<git_ref>` — restrict to caches created against this ref
54 (e.g. `refs/heads/trunk`).
55
56 ## Delete by id
57
58 ```
59 DELETE /api/v1/repos/alice/demo/actions/caches/17
60 ```
61
62 Returns `204 No Content`. The DB row is removed atomically; the
63 tarball in object storage is purged best-effort in the background.
64
65 `404` when:
66
67 - the cache id is unknown
68 - the cache exists but belongs to a different repo (existence-leak-safe)
69 - the caller lacks `repo:write` on the target (returned as 404 by
70 the policy gate, not 403, to keep the existence-leak guarantee)
71
72 ## Delete by key
73
74 ```
75 DELETE /api/v1/repos/alice/demo/actions/caches?key=node-modules
76 ```
77
78 Removes every cache with that key, regardless of version, scoped
79 to the repo. Add `ref=...` to scope by ref as well. Returns `204`
80 even when zero rows match (idempotent).
81
82 `400` when the `key` query parameter is missing or empty.
83
84 ## Errors
85
86 | Status | Cause |
87 |------:|--------------------------------------------------------|
88 | 400 | DELETE-by-key without a `key` query parameter. |
89 | 403 | PAT lacks `repo:write` on the delete endpoints. |
90 | 404 | Cache id unknown or belongs to a different repo. |