Releases & Tags

A release in ProxifAI is a row in the Release table tied to a git tag, optionally with binary assets and a release-notes body. The full surface — list/get/create/update/delete plus per-asset upload/download — is available at /api/v1/forge/{owner}/{repo}/releases/.... The integrated OCI registry is a separate but co-located concern, mounted at /v2/ on the same host.

Creating a release

pfai release create v1.2.3 \
  --target main \
  --title "v1.2.3 — Auth & analytics improvements" \
  --body "$(cat CHANGELOG-v1.2.3.md)" \
  --prerelease

curl -X POST http://localhost:3000/api/v1/forge/{owner}/{repo}/releases \
  -H "Authorization: Bearer $PFAI_TOKEN" \
  -d '{
    "tagName":"v1.2.3",
    "targetCommit":"main",
    "name":"v1.2.3",
    "body":"…",
    "draft":false,
    "prerelease":true
  }'

curl -X POST http://localhost:3000/api/v1/forge/{owner}/{repo}/releases/v1.2.3/assets \
  -H "Authorization: Bearer $PFAI_TOKEN" \
  -F "file=@dist/proxifai-linux-amd64.tar.gz"

Release schema

Release
├── id            int64
├── tagName       string         (the git tag this release points at)
├── name          string         (display title)
├── body          string         (Markdown release notes)
├── draft         bool           (not visible to non-maintainers)
├── prerelease    bool           (won't be marked "Latest")
├── author        ForgeUser
├── targetCommit  string         (resolved when tagName didn't pre-exist)
├── publishedAt   timestamp?
└── assets        []ReleaseAsset
                    ├── id, name, label, contentType, size
                    ├── downloadUrl
                    └── downloadCount

PATCH /releases/{tag} updates name, body, draft, prerelease (each is nullable in the input — only fields you pass change). Deleting the release does not delete the underlying git tag — tag deletion is a separate operation and is gated by tag protection.

Asset storage

Assets are written to the storage backend defined by internal/storage/:

Asset rows reference a stable internal id (text like ast_xxx); the API serializes IDs as int64 for backward compatibility, so the canonical handle is the downloadUrl field. To delete:

pfai release delete-asset v1.2.3 dist-linux-amd64.tar.gz
# or
curl -X DELETE http://localhost:3000/api/v1/forge/{owner}/{repo}/releases/v1.2.3/assets/{assetId} \
  -H "Authorization: Bearer $PFAI_TOKEN"

Tags

Both work as anchors for releases. Use annotated tags when the tag itself should carry release notes independent of a Release row.

Protected tags

Configure protection patterns at Repository Settings → Tag Protection or via pfai protected-tag. Each rule is a glob (v*, release-*, …); matching tags can only be deleted by users with admin access on the repo. This guards against accidental deletes that would orphan releases.

OCI container registry

A full OCI Distribution Spec implementation is mounted at /v2/* on the same host as the rest of the platform (internal/registry). There is no separate registry hostname.

# Auth uses your pfai token as both username and password
echo $PFAI_TOKEN | docker login http://localhost:3000 -u <user> --password-stdin

# Push
docker tag my-image:v1 localhost:3000/my-org/my-repo/my-image:v1.0.0
docker push localhost:3000/my-org/my-repo/my-image:v1.0.0

# Pull
docker pull localhost:3000/my-org/my-repo/my-image:v1.0.0

Behind the scenes, every blob upload (POST /v2/<repo>/blobs/uploads/), manifest push (PUT /v2/<repo>/manifests/<tag>), and pull goes through the in-process handler. Tags and manifests are queryable via OCIQuerier, which also powers the Packages tab in the repo UI.

For production, front the registry with TLS via your reverse proxy (Cloudflare tunnel, nginx, Caddy) and tell Docker to trust the host. For development, --insecure-registry flags work against localhost.

Versioning

Semantic versioning (MAJOR.MINOR.PATCH) is convention, not enforcement. The releases list sorts by publishedAt descending; the topmost non-draft non-prerelease release is highlighted as Latest in the UI.

Pre-releases (prerelease=true) participate in the list but never become the Latest badge holder, so you can ship v1.2.3-rc.1 alongside v1.2.2 without confusing consumers.

REST endpoint reference

See also