# 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. Forgejo API token (one-time per workstation)

This is **not** the OpenBao backup lane (`bao login` / Nextcloud). Prune uses a
Forgejo **personal access token** with package scopes — same convention as
`railiance-apps` (`FORGEJO_ADMIN_TOKEN`, `/tmp/forgejo-tegwick-api-token`).

1. Log in to https://forgejo.coulomb.social as `tegwick` (or another user with
   org package admin rights on `coulomb`).
2. **Settings → Applications → Generate New Token**
3. Scopes: **`read:package`** and **`write:package`**
4. Store on the workstation (pick one):

```bash
# Option A — token file (matches forgejo-operator-bootstrap, npm smoke, webhooks)
install -m 600 /dev/null /tmp/forgejo-tegwick-api-token
# paste token into the file (single line, no newline required)

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

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

### 2. Run prune

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

## Rollback

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`