# 패키지 게시 — AI Game Dev 앱 & CLI · AI Game Developer Wiki

AI Game Dev 커뮤니티 레지스트리에 패키지를 게시하세요: 퍼블리셔 등록, 업로드, 릴리스 노트, 베타 채널, 지원 중단, yank, 기타 소스.

이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/app/publishing-packages).

커뮤니티 레지스트리는 사용자가 id로 패키지를 찾아 설치하는 곳입니다: `gamedev pkg add acme.level-tools`, 또는 Packages 창의 **Browse**에서 자동 업데이트와 1~5점 별점을 함께 이용할 수 있습니다. 등록된 ai-game.dev 계정이면 누구나 게시할 수 있고, 패키지는 무료이며, 모든 버전은 수동 검토 대신 자동 검사를 통과합니다. 이 페이지는 퍼블리셔, 첫 업로드, 릴리스 노트, 사전 릴리스 채널, 지원 중단, yank, 그리고 패키지를 공유하는 다른 방법까지 전체 과정을 다룹니다.

![ai-game.dev의 패키지 카탈로그: 추천 엔진 패키지, 카테고리 필터, 공식 및 커뮤니티 패키지 행](https://ai-game.dev/images/wiki/app/catalog-packages.webp)

패키지 카탈로그: 공식 패키지와 커뮤니티 패키지, 각각의 설치 명령어가 표시됩니다.

## 퍼블리셔 등록하기

퍼블리셔 id는 게시하는 모든 패키지 id의 앞부분입니다(`acme.level-tools`에서 `acme`). 한 번만 등록하면 되며, 선착순입니다:

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

퍼블리셔 id는 2~40자의 소문자, 숫자, 단일 하이픈으로 구성됩니다. AI Game Dev 자체 id(`aigd`), 엔진 이름(`unity`, `godot`, `unreal`, `brutal`, `bevy`, `threejs`), 상표 및 `un1ty`나 `unity-tools` 같은 유사 이름은 예약되어 있습니다. 계정은 이메일 인증이 필요하며 최대 3개의 퍼블리셔를 보유할 수 있습니다.

퍼블리셔를 등록한 계정이 해당 퍼블리셔의 **소유자**입니다. 소유자는 이메일로 **메인테이너**를 추가할 수 있으며, 메인테이너는 업로드, yank, 지원 중단, 릴리스 노트 편집, 채널 이동, 토큰 발급을 할 수 있습니다. 멤버 관리와 [신뢰할 수 있는 퍼블리셔](https://ai-game.dev/ko/docs/wiki/app/trusted-publishing)는 소유자만 할 수 있습니다.

## 버전 게시

`aigd-package.json`에 `"publisher": "acme"`를 넣고, `version`을 올린 뒤 빌드하고 다음을 실행하세요:

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

CLI는 폴더를 팩으로 묶고(`gamedev pkg pack`과 동일한 검사와 바이트), 업로드한 뒤 검사 결과를 기다립니다. 버전은 다음 상태를 거칩니다:

| 상태 | 의미 |
| --- | --- |
| `uploaded`, `checking` | 자동 검사를 기다리는 중이거나 실행 중 |
| `published` | 모든 검사를 통과함; 약 1분 이내에 서명된 인덱스에 포함 |
| `rejected` | 검사 실패; 보고서에 각 실패가 명시됩니다. 수정한 뒤 같은 버전을 다시 업로드하세요 |
| `yanked` | 퍼블리셔가 철회함: 범위(range)는 건너뛰고, 기존 설치본은 유지됩니다 |
| `revoked` | AI Game Dev가 제거함(멀웨어, 탈취된 계정): 모든 앱에서 비활성화됩니다 |

**버전은 불변입니다.** published, yanked 또는 revoked된 버전 번호는 다시 업로드할 수 없으며, rejected된 버전만 다시 업로드할 수 있습니다. 수정 사항은 새 버전으로 배포하세요.

![카탈로그의 패키지 페이지: 이름, 퍼블리셔, 버전, 설치 버튼과 명령어, 스타터 미리보기, About 패널, 최신 릴리스](https://ai-game.dev/images/wiki/app/catalog-package-page.webp)

카탈로그의 커뮤니티 패키지 페이지. 클릭 한 번 또는 명령어 한 줄로 설치할 수 있습니다.

## 릴리스 노트

모든 버전은 Markdown 형식의 릴리스 노트를 포함할 수 있습니다. 사용자는 Packages 창(**Versions**)과 퍼블리셔 패널에서 버전별 릴리스 노트를 볼 수 있습니다. 업로드할 때 함께 지정하세요:

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

`--notes`가 없으면 레지스트리는 패키지 폴더에 있고 아카이브에 포함되는 `CHANGELOG.md`에서 해당 버전의 제목(`## 1.2.0`, `## [1.2.0]`, `## v1.2.0`)부터 같은 수준 또는 더 높은 수준의 다음 제목 전까지의 섹션을 20KB로 잘라 사용합니다:

```text
# Changelog

## [1.2.0]

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

릴리스 노트는 최대 20KB의 Markdown이며, README처럼 정제되고 패키지의 다른 모든 텍스트와 마찬가지로 프롬프트 인젝션 검사를 받습니다. 멤버는 나중에 퍼블리셔 패널에서 편집할 수 있습니다. 서명된 인덱스에는 처음 4KB가 포함되며 나머지는 링크로 제공됩니다.

## 채널: latest, beta 그리고 그 외

채널(dist-tag)은 사용자가 이름으로 요청할 때 받는 버전을 지정합니다:

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

- 사전 릴리스(`1.3.0-beta.1`)는 기본적으로 설치되지 않습니다. `latest`는 직접 설정하지 않는 한 게시된 안정 버전 중 가장 높은 버전이며, 사전 릴리스를 가리킬 수 없습니다.
- 그 외 채널 이름은 직접 정할 수 있습니다(`beta`, `next`, `nightly`). 소문자로 시작하는 문자로 시작하고 최대 16자입니다. 패키지당 채널은 `latest`를 포함해 최대 5개입니다.
- yanked 또는 revoked된 버전에는 태그를 붙일 수 없으며, yanked된 버전을 가리키던 채널은 제거됩니다.
- 사전 릴리스는 semver 사전 릴리스로 게시하세요(`1.3.0-beta.2`). 이름이 `alpha`, `beta`, `rc`, `next`, `preview`, `canary`, `nightly`, `dev`, `experimental`인 사전 릴리스는 멤버가 채널을 직접 설정하지 않은 경우 해당 채널을 자동으로 자신으로 이동시킵니다. 채널은 퍼블리셔 패널(**Channels**)에서도 이동할 수 있습니다.
- `gamedev pkg add acme.level-tools@beta`는 채널을 `packages.json`에 기록합니다: `{ "source": "^1.3.0-beta.1", "channel": "beta" }`. 테스터는 해당 채널의 버전이 최신 안정 버전보다 새로운 동안 그 버전을 받고, 안정 버전이 출시되면 다음 업데이트 때 안정 릴리스로 이동합니다.

## 패키지 또는 버전 사용 중단(deprecate)하기

사용 중단은 설치된 것을 깨뜨리지 않으면서 사용자에게 다른 것으로 옮기라고 알리는 것입니다:

- **패키지:** 메시지(최대 300자)와 선택적으로 대체 패키지의 id를 지정합니다. 앱과 CLI는 메시지와 대체 패키지를 표시하며, 이미 설치된 사본은 계속 작동하고 해당 패키지는 여전히 추가할 수 있습니다.
- **버전:** "중첩된 씬을 내보낼 때 데이터가 손실됩니다. 1.2.1로 업데이트하세요"와 같은 메시지입니다.

버전을 선택할 때 앱은 사용 중단되지 않은 버전을 선호합니다. 두 종류 모두 되돌릴 수 있으며 레지스트리의 감사 로그에 기록됩니다. 게시자 패널에서 설정하세요.

## Yank와 Revoke

실수로 게시한 버전은 Yank하세요: 이후 버전 범위에서 제외되며, 이미 해당 버전이 설치된 곳은 그대로 유지됩니다. Yank는 되돌릴 수 있고, 게시자 토큰으로도 Yank할 수 있습니다. Revoke는 악성 또는 도난된 버전에 대한 AI Game Dev의 킬 스위치입니다: 인덱스에서 제거되고, 해당 버전을 가진 모든 앱이 다음 인덱스 읽기 시 이를 끕니다.

## CI에서 게시하기

두 가지 방법이 있으며, 둘 다 [Trusted Publishing](https://ai-game.dev/ko/docs/wiki/app/trusted-publishing)에 설명되어 있습니다:

- **Trusted Publishing(권장):** GitHub Actions 또는 GitLab CI가 어느 저장소와 워크플로가 게시하는지 증명합니다. 시크릿은 어디에도 저장되지 않으며 모든 버전이 출처를 기록합니다. 바로 사용할 수 있는 GitHub Action과 GitLab CI 템플릿인 [IvanMurzak/gamedev-publish-action](https://github.com/IvanMurzak/gamedev-publish-action)이 그곳에 설명되어 있습니다.
- **게시자 토큰:** `gamedev pkg publisher token create acme --label ci --days 90`을 실행하고, CI 시크릿으로 저장한 뒤 `AI_GAME_DEV_PUBLISHER_TOKEN`으로 전달합니다.

## 게시자 패널

첫 업로드 후 게시자가 관리하는 모든 것은 [ai-game.dev/publisher](https://ai-game.dev/publisher)의 게시자 패널에 있으며, 로그인한 소유자와 관리자가 사용할 수 있습니다: 게시자와 패키지, 상태와 검사 보고서가 포함된 모든 버전, 릴리스 노트, 채널, 사용 중단과 Yank, 멤버와 역할, 게시자 토큰, 그리고 복사할 수 있는 워크플로 스니펫이 있는 trusted publisher까지 모두 포함됩니다. [Registry rules and checks](https://ai-game.dev/ko/docs/wiki/app/package-registry#panel)를 참고하세요.

## 기타 소스: GitHub, npm 및 폴더

레지스트리만 패키지를 공유하는 방법은 아닙니다. 다음 소스들은 레지스트리의 검사 없이 설치되므로 `gamedev pkg validate`를 직접 실행해야 하며, 제안된 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:** 태그가 있으면 앱이 이름이 `.aigd.tgz`로 끝나는 릴리스 에셋을 다운로드합니다(`gamedev pkg pack`이 만든 파일을 첨부하세요). 그렇지 않으면 해당 커밋의 저장소를 사용하므로 `aigd-package.json`이 루트에 있어야 하고 `dist/`가 커밋되어 있어야 합니다.
- **npm:** 패키지 폴더를 `npm publish`하세요. npm 아카이브에는 `aigd-package.json`과 `dist/`가 포함되어야 하며, `package.json`에 `"engines": { "aigd": "<range>" }`도 추가하세요. 그러면 앱이 실행할 수 없는 버전은 다운로드하지 않고 건너뜁니다.
- **팀:** 패키지를 Project 수준에서 추가하면 `.ai-game-dev/packages.json`에 커밋되어 프로젝트의 잠금 파일로 고정된 동일한 버전을 모든 팀원이 받습니다.

## 관련 페이지

- 저장된 시크릿 없이 CI를 구성하려면 [Trusted Publishing](https://ai-game.dev/ko/docs/wiki/app/trusted-publishing)을 참고하세요.
- 검사가 무엇을 거부하는지 알아보려면 [Registry rules and checks](https://ai-game.dev/ko/docs/wiki/app/package-registry)를 참고하세요.
- 모든 `publish` 옵션은 [Package CLI reference](https://ai-game.dev/ko/docs/wiki/app/package-cli#publish)를 참고하세요.

---

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

Machine-translated (ko) from the English page: https://ai-game.dev/docs/wiki/app/publishing-packages
