# Publishing packages

Publish a package to the AI Game Dev community registry: claim a publisher, upload, release notes, beta channels, deprecation, yanking, other sources.

_Last updated: 2026-11-19_

The community registry is where users find and install packages by id: `gamedev pkg add acme.level-tools`, or **Browse** in the Packages window, with automatic updates and 1 to 5 star ratings. Any registered ai-game.dev account can publish, packages are free, and every version passes automatic checks instead of a manual review. This page covers the whole path: your publisher, the first upload, release notes, pre-release channels, deprecation, yanking, and the other ways to share a package.

![The package catalog on ai-game.dev: a featured engine package, category filters and rows of official and community packages](https://ai-game.dev/images/wiki/app/catalog-packages.webp)

The package catalog: official packages and community packages, each with its install command.

## Claim a publisher

Your publisher id is the first half of every package id you publish (`acme` in `acme.level-tools`). Claim it once; it is first come, first served:

```bash
gamedev login
gamedev pkg publisher claim acme --name "Acme Tools"
```

A publisher id is 2 to 40 lowercase letters, digits and single hyphens. AI Game Dev's own id (`aigd`), engine names (`unity`, `godot`, `unreal`, `brutal`, `bevy`, `threejs`), trademarks and look-alikes such as `un1ty` or `unity-tools` are reserved. An account needs a verified email and may hold up to 3 publishers.

The account that claims a publisher is its **owner**. An owner can add **maintainers** by email; maintainers may upload, yank, deprecate, edit release notes, move channels and mint tokens. Only an owner manages members and [trusted publishers](https://ai-game.dev/docs/wiki/app/trusted-publishing).

## Publish a version

Put `"publisher": "acme"` in `aigd-package.json`, raise `version`, build, then:

```bash
gamedev pkg publish level-tools
```

The CLI packs the folder (the same checks and bytes as `gamedev pkg pack`), uploads it and waits for the checks. A version moves through these states:

| State | Meaning |
| --- | --- |
| `uploaded`, `checking` | Waiting for or running the automatic checks |
| `published` | Passed every check; in the signed index within about a minute |
| `rejected` | A check failed; the report names each failure. Fix it and upload the same version again |
| `yanked` | Withdrawn by its publisher: ranges skip it, existing installs keep it |
| `revoked` | Removed by AI Game Dev (malware, a stolen account): every app turns it off |

**Versions are immutable.** A published, yanked or revoked version number can never be uploaded again; only a rejected one can. Ship a fix as a new version.

![A package's page in the catalog: name, publisher, version, install button and command, starter previews, an About panel and the latest release](https://ai-game.dev/images/wiki/app/catalog-package-page.webp)

A community package's page in the catalog. Users install it with one click or one command.

## Release notes

Every version can carry release notes in Markdown. Users see them per version in the Packages window (**Versions**), and in the publisher panel. Give them with the upload:

```bash
gamedev pkg publish level-tools --notes RELEASE_NOTES.md
```

Without `--notes`, the registry takes the section of your `CHANGELOG.md` (in the package folder, shipped in the archive) from the heading of the version (`## 1.2.0`, `## [1.2.0]` or `## v1.2.0`) up to the next heading of the same or a higher level, clipped to 20 KB:

```text
# Changelog

## [1.2.0]

- Export levels as glTF.
- Fix the collectible count in nested scenes.
```

Notes are at most 20 KB of Markdown, sanitized like a README and checked for prompt injection like every other text in a package. A member can edit them later in the publisher panel. The signed index carries the first 4 KB, with a link to the rest.

## Channels: latest, beta and others

A channel (a dist-tag) names the version users get when they ask for it by name:

```bash
gamedev pkg add acme.level-tools          # the latest channel
gamedev pkg add acme.level-tools@beta     # whatever beta points to
```

- A prerelease (`1.3.0-beta.1`) is never installed by default: `latest` is the highest published stable version unless you set it, and it can never point at a prerelease.
- Other channels are yours to name (`beta`, `next`, `nightly`): lowercase, starting with a letter, up to 16 characters. A package has at most 5 channels, `latest` included.
- A yanked or revoked version cannot be tagged; a channel pointing at a version that gets yanked is removed.
- Publish a prerelease as a semver prerelease (`1.3.0-beta.2`). A prerelease named `alpha`, `beta`, `rc`, `next`, `preview`, `canary`, `nightly`, `dev` or `experimental` moves that channel to itself automatically, unless a member set the channel by hand; any channel can also be moved in the publisher panel (**Channels**).
- `gamedev pkg add acme.level-tools@beta` writes the channel into `packages.json`, `{ "source": "^1.3.0-beta.1", "channel": "beta" }`. Testers get the channel's version while it is newer than the newest stable one, and move to the stable release once it is out, on their next update.

## Deprecate a package or a version

Deprecation tells users to move on without breaking anything that is installed:

- **A package:** a message (up to 300 characters) and, optionally, the id of a replacement package. The app and the CLI show the message and the replacement; installed copies keep working and the package can still be added.
- **A version:** a message such as "data loss when exporting nested scenes, update to 1.2.1".

When choosing a version, the app prefers one that is not deprecated. Both kinds are reversible and recorded in the registry's audit log. Set them in the publisher panel.

## Yank and revoke

Yank a version you published by mistake: version ranges skip it from then on, and installs that already have it keep it. Yanking is reversible, and a publisher token may yank. Revocation is AI Game Dev's kill switch for a malicious or stolen version: it leaves the index and every app that has it turns it off on its next index read.

## Publish from CI

Two ways, both shown in [Trusted Publishing](https://ai-game.dev/docs/wiki/app/trusted-publishing):

- **Trusted Publishing (recommended):** GitHub Actions or GitLab CI proves which repository and workflow is publishing; no secret is stored anywhere and every version records its provenance. A ready GitHub Action and GitLab CI template, [IvanMurzak/gamedev-publish-action](https://github.com/IvanMurzak/gamedev-publish-action), are described there.
- **A publisher token:** `gamedev pkg publisher token create acme --label ci --days 90`, stored as a CI secret and passed as `AI_GAME_DEV_PUBLISHER_TOKEN`.

## The publisher panel

Everything a publisher manages after the first upload is in the publisher panel at [ai-game.dev/publisher](https://ai-game.dev/publisher), for signed-in owners and maintainers: your publishers and packages, every version with its state and check report, release notes, channels, deprecation and yanking, members and roles, publisher tokens, and trusted publishers with copyable workflow snippets. See [Registry rules and checks](https://ai-game.dev/docs/wiki/app/package-registry#panel).

## Other sources: GitHub, npm and folders

The registry is not the only way to share a package. These sources install without the registry's checks, so run `gamedev pkg validate` yourself, and they are the way to share a package that uses proposed API:

```bash
gamedev pkg add github:acme/level-tools           # the default branch: moves with each push
gamedev pkg add github:acme/level-tools@v1.2.0    # a tag: pinned, never auto-updated
gamedev pkg add npm:acme-level-tools@^1.2.0       # an npm package and range
gamedev pkg add file:../level-tools               # a folder
```

- **GitHub:** with a tag, the app downloads a release asset whose name ends in `.aigd.tgz` (attach the file `gamedev pkg pack` wrote); otherwise the repository at that commit, so `aigd-package.json` must be at the root and `dist/` committed.
- **npm:** `npm publish` the package folder. The npm archive must contain `aigd-package.json` and `dist/`; add `"engines": { "aigd": "<range>" }` to `package.json` too, so the app skips versions it cannot run without downloading them.
- **Teams:** add the package at the Project level so it is committed in `.ai-game-dev/packages.json` and every teammate gets the same version, pinned by the project's lock file.

## Related pages

- [Trusted Publishing](https://ai-game.dev/docs/wiki/app/trusted-publishing) for CI without a stored secret.
- [Registry rules and checks](https://ai-game.dev/docs/wiki/app/package-registry) for what the checks refuse.
- [Package CLI reference](https://ai-game.dev/docs/wiki/app/package-cli#publish) for every `publish` option.

---

Source (HTML): https://ai-game.dev/docs/wiki/app/publishing-packages
