repomatic.github.caches module

GitHub Actions caches of a repository, and the pruning of superseded ones.

A cache step keyed on the run or the commit, with a prefix in its restore-keys, saves a fresh entry on every run and restores the newest previous one. Each older entry is never read again, yet it stays until GitHub evicts it a week after its last access, and counts against the repository’s cache quota of 10 GB. Past the quota GitHub evicts the least recently used entry, live caches included, so an accumulation of dead snapshots is what evicts the tool and compile caches a job depends on.

prune_caches() keeps the newest entries of a prefix and deletes the rest.

Note

actions/cache saves at the end of the job, once every step ran, so a prune step inside the job sees the entries of the previous runs only: keeping one leaves two once the job saves its own.

repomatic.github.caches.CACHES_ENDPOINT = 'repos/{repo}/actions/caches'

REST endpoint listing the caches of a repository, and deleting one by ID.

repomatic.github.caches.PRUNE_CACHES_HEADER_DEFS: tuple[ColumnSpec, ...] = (ColumnSpec(id='key', label='Key', description='', max_width=None, optional=False, sortable=True), ColumnSpec(id='ref', label='Ref', description='', max_width=None, optional=False, sortable=True), ColumnSpec(id='size', label='Size', description='', max_width=None, optional=False, sortable=True), ColumnSpec(id='created', label='Created', description='', max_width=None, optional=False, sortable=True), ColumnSpec(id='outcome', label='Outcome', description='', max_width=None, optional=False, sortable=True))

Column definitions for the repomatic prune-caches table.

class repomatic.github.caches.ActionsCache(id, key, ref, size, created_at)[source]

Bases: object

One cache entry of a repository, as the REST API lists it.

id: int

Identifier the delete endpoint takes.

key: str

The key the saving step wrote.

ref: str

The git ref the entry is scoped to, like refs/heads/main.

size: int

Size in bytes.

created_at: str

ISO 8601 timestamp of the save, which sorts as text.

classmethod from_api(item)[source]

Build an entry from one item of the listing endpoint.

Return type:

ActionsCache

class repomatic.github.caches.PruneReport(prefix, kept, deleted, refused)[source]

Bases: object

What a prune of one prefix kept, deleted and could not delete.

prefix: str

The key prefix pruned.

kept: tuple[ActionsCache, ...]

The newest entries, left in place.

deleted: tuple[ActionsCache, ...]

The superseded entries deleted, or that a dry run would delete.

refused: tuple[ActionsCache, ...]

The superseded entries the API refused to delete.

property freed: int

Bytes the deleted entries held.

rows(*, dry_run=False)[source]

One table row per entry, in the order of the listing.

Return type:

list[list[str]]

repomatic.github.caches.list_caches(repo, prefix)[source]

Caches of repo whose key starts with prefix, newest first.

The API filters on the prefix itself, and the result is filtered again here, so a prefix the query string decodes differently matches no more than it names.

Parameters:

  • repo (str) – Repository in owner/name form.

  • prefix (str) – Key prefix, as a cache step’s restore-keys names it.

Raises:
Return type:

list[ActionsCache]

repomatic.github.caches.delete_cache(repo, cache)[source]

Delete one cache entry of repo.

Raises:

GhCommandError – The deletion failed, as when the token lacks actions: write.

Return type:

None

repomatic.github.caches.prune_caches(repo, prefix, *, keep=1, dry_run=False)[source]

Delete every cache of prefix but the newest keep.

A deletion the API refuses is logged and reported, never raised: housekeeping must not fail the job it runs in. The listing itself raises, and the caller decides.

Parameters:

  • repo (str) – Repository in owner/name form.

  • prefix (str) – Key prefix whose entries to prune.

  • keep (int) – How many of the newest entries to leave in place.

  • dry_run (bool) – Report the entries to delete without deleting them.

Raises:
Return type:

PruneReport