godot-asset-library

A private Godot asset library backed by Forgejo. It finds addon repositories in your Forgejo orgs and serves them to the Godot editor. Two protocols are served from the same base URL:

• Godot 4.7+ uses the Asset Store API: /, /tags/, /licenses/, /search/query/, /assets/{pub}/{slug}/ and /releases/{pub}/{slug}/.
• Godot 3.x–4.6 uses the legacy Asset Library API: /configure, /asset and /asset/{id}.

Downloads come straight from Forgejo, so repos and release attachments must be readable by whoever runs the editor.

Publishing an addon

1. Add the repo topic godot-addon (configurable with FORGEJO_TOPIC) to a repo in one of the FORGEJO_ORGS orgs.

2. Commit a godot-asset.toml at the repo root:

   name = "Dialog Kit"
   slug = "dialog-kit"            # optional; default: repo name (lowercased)
   category = "tools"             # becomes a category/tag; created automatically
   license = "MIT"                # SPDX id
   license_url = "https://opensource.org/license/mit"   # optional; default: SPDX page
   min_godot = "4.2"
   max_godot = "4.6.99"           # optional; see "Version bounds" below
   description = "[b]BBCode[/b] shown in the editor"   # or: description_file = "DESCRIPTION.bbcode"
   icon = "icon.png"              # repo path or absolute URL; PNG/JPEG/WebP only (no SVG)
   previews = ["screens/1.png"]   # same rules as icon
   artifact = "dialog-kit-*.zip"  # glob for the release attachment to serve
   type = "addon"                 # addon | project (project = Project Manager templates)
   

3. Publish a Forgejo release. The manifest is read at the release tag, so each release carries its own Godot version range.

   • The release body becomes the changelog.
   • Releases marked as pre-release are served as unstable.
   • If you don't set artifact, the service uses the single .zip attachment, or the tag's source archive when there isn't exactly one.
   • The ZIP should contain addons/<name>/…, either at the top level or inside one wrapper folder.

Asset metadata (name, icon, description and so on) comes from the newest stable release. Releases without a valid manifest are skipped and listed in the admin sync log.

Version bounds

The editor pads versions with zeros before comparing them, so max_godot = "4.6" means 4.6.0 and excludes 4.6.1. To cover the whole 4.6 branch, use max_godot = "4.6.99". The server applies the same rule when it filters.

Integrity

• Legacy (≤4.6): each artifact's SHA-256 is computed once at sync and served as download_hash. The editor rejects a download whose hash doesn't match.
• 4.7+: the protocol has no hash check.

Editor setup

Godot	Editor Settings key	Value
4.7+	asset_store/available_urls	add "Friends": "https://godot-assets.example.com"
≤4.6	asset_library/available_urls	add "Friends": "https://godot-assets.example.com"

Running

All configuration comes from environment variables:

Var	Required	Meaning
PUBLIC_URL	yes	External base URL. https:// makes the admin cookie Secure
DATABASE_URL	yes	PostgreSQL URL. Migrations run on startup
FORGEJO_URL	yes	e.g. https://git.example.com
FORGEJO_ORGS	yes	Comma-separated orgs to scan
FORGEJO_TOKEN		Token with read:repository and read:organization
FORGEJO_TOPIC		Default godot-addon
WEBHOOK_SECRET		Enables POST /hooks/forgejo
ADMIN_PASSWORD		Enables /admin/, protected by a login page with this password. Changing it logs out all sessions
SYNC_INTERVAL		Optional periodic full sync, e.g. 1h
LISTEN_ADDR		Default :8080

• godot-assets -sync-once runs one full sync and exits.
• A full sync also runs at startup.
• The sync log is visible in the admin UI.

Webhook: in Forgejo, add an org-level webhook of type Forgejo.

• URL: PUBLIC_URL/hooks/forgejo
• Content type: JSON
• Secret: the value of WEBHOOK_SECRET
• Events: Release and Push

Changing a repo's topic doesn't fire a webhook. Use Sync all in the admin UI, or set SYNC_INTERVAL.

Deploy: see the Dockerfile (distroless, about 17 MB) and deploy/k8s/godot-assets.yaml. Run a single replica, because the sync worker runs in-process.

Development

go test ./...
# store integration test:
TEST_DATABASE_URL=postgres://... go test ./internal/store/