railiance-platform/docs/forgejo-package-prune.md

Forgejo package prune (retention)

Workplan: ACTIVITY-WP-0020 · complements docs/forgejo-backup.md

Policy

Rule	Value
Versions kept per package	3 (newest by created_at)
Package types (phase 1)	container, pypi, npm, generic
Org scope	coulomb
Protected versions	Image tags referenced in railiance-apps production Helm values / chart defaults
Default mode	dry-run (no deletes)
Schedule	Weekly Sunday 03:30 UTC via activity-core (weekly-forgejo-package-prune)

OCI container layers dominate forgejo dump size (~80% of blob zip). Pruning old tags slows backup growth and shortens chunked-copy duration.

Operator commands

1. Authenticate to the approved token lane

The steady-state credential path is CCR-2026-0006: OpenBao lane platform/workloads/forgejo/forgejo-admin, field API_TOKEN.

1. Confirm the sanctioned route first:

warden plan "forgejo admin api token" --json

2. Login with an identity allowed to read the lane:

bao login -method=oidc -path=netkingdom role=forgejo-admin-workload-kv-read

3. Run prune normally. If FORGEJO_TOKEN, FORGEJO_ADMIN_TOKEN, FORGEJO_TOKEN_FILE, and FORGEJO_ADMIN_TOKEN_FILE are unset, the loader now resolves the PAT directly from OpenBao.

Do not commit the token or paste it into workplans, State Hub, chat, or shell history.

2. Break-glass overrides

Short-lived overrides are still supported when the lane is unavailable or when an attended operator session needs an explicit handoff:

# Option A — token env for one shell session
export FORGEJO_TOKEN='<pat>'
# alias: export FORGEJO_ADMIN_TOKEN='<pat>'

# Option B — explicit file path for one invocation
warden access forgejo-admin-api-token --out "$XDG_RUNTIME_DIR/forgejo-admin.token" --field API_TOKEN
FORGEJO_TOKEN_FILE="$XDG_RUNTIME_DIR/forgejo-admin.token" make forgejo-package-prune-dry-run
rm -f "$XDG_RUNTIME_DIR/forgejo-admin.token"

The retired /tmp/forgejo-tegwick-api-token drop is no longer the default. Use it only while unwinding legacy local state:

FORGEJO_ALLOW_LEGACY_FILE_FALLBACK=1 make forgejo-package-prune-dry-run

3. Run prune

cd ~/railiance-platform
make forgejo-package-prune-dry-run   # list would-delete candidates
make forgejo-package-prune           # delete beyond retention depth

Durable multi-cluster image inventory

The inventory belongs outside the platform checkout. On the production worker host, use /home/tegwick/.local/state/railiance-platform/live-images/all.txt. make live-images-refresh LIVE_IMAGES_SOURCES="/path/railiance01.txt /path/coulombcore.txt" merges complete, nonempty exports with the prior inventory under a writer lock, then atomically publishes sorted image references and a count/hash receipt. Set LIVE_IMAGES_OUTPUT when publishing for a different host user. Missing, empty, or malformed input fails without replacing the previous file. The prune CLI also refuses --apply before credential retrieval if any explicit --live-images-file is missing, unreadable, empty, or comment-only. Dry-run keeps reporting those files as warnings. This guard supplements the activity-core worker guard; it does not require exports for callers that have not configured any. Refresh only adds protection: removal of obsolete tags requires a separate review of every production cluster and rollback requirement.

Migration and rollout sequence:

1. Seed from the restored docs/evidence/live-images-all.txt plus fresh exports from railiance01 and coulombcore; retain the restored multi-cluster entries.
2. Project the durable directory read-only into the activity-core worker and configure its inventory argument to all.txt in that directory. Do not mount the single file: atomic replacement must be visible to the worker.
3. Verify the worker reads a nonempty inventory and retains the existing hard refusal of apply when that file is missing or empty. Use only its dry-run verification; do not manually trigger prune.
4. After each cluster image rollout, export pod regular, init, and ephemeral container images to a temporary file. Require successful kubectl exit and nonempty output, then invoke this refresh target with that export. Keep other clusters' prior entries during outages. Run the hook on the durable host, or transfer the complete export there before invoking it.

tools/cmd/refresh-live-images captures regular, init and ephemeral container images with a bounded kubectl call and publishes only after all requested contexts succeed. CONTEXTS selects contexts; EXTRA_LIVE_FILES supplies saved exports. Bare image names are accepted. Failed captures preserve the inventory. The host installation exposes ~/.local/bin/railiance-live-images-refresh; invoke it after cluster image rollouts. Activity-core's make refresh-live-images delegates to the same implementation. Live installation evidence is tracked in RPF-WP-0028.

Rollback procedure

If a needed tag was removed, restore from the latest Nextcloud forgejo-dump-*.zip.age (make forgejo-backup evidence) using railiance-infra/tools/forgejo-restore-drill.sh, or re-push the image from CI.

Evidence

activity-core posts forgejo_package_prune progress to State Hub with non-secret counts (deleted_count, candidate_count, skipped_protected_count, errors).

Related

• railiance-apps/docs/forgejo-package-registry.md
• docs/forgejo-backup.md
• docs/workload-kv-access-lanes.md