# 신뢰할 수 있는 게시 — AI Game Dev 앱 & CLI · AI Game Developer Wiki

저장된 토큰 없이 GitHub Actions 또는 GitLab CI에서 AI Game Dev 패키지를 게시하세요: 신뢰할 수 있는 게시자, 워크플로 파일, 출처(provenance)를 설정합니다.

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

신뢰할 수 있는 게시를 사용하면 CI에 비밀을 저장하지 않고도 CI 작업이 패키지를 게시할 수 있습니다. GitHub Actions 또는 GitLab CI가 어떤 저장소와 워크플로가 실행 중인지 보증하고, ai-game.dev는 그 증명을 하나의 패키지를 업로드할 수 있는 단기 자격 증명으로 교환합니다. 이렇게 게시된 모든 버전은 **출처(provenance)** 를 기록합니다. 즉 어느 저장소, 커밋, CI 실행에서 빌드되었는지가 남습니다. 이 페이지는 GitHub와 GitLab에서 이를 설정하는 방법과 무엇이 검사되는지 설명합니다.

## 작동 방식

1. 어떤 저장소와 워크플로가 패키지를 게시할 수 있는지 레지스트리에 알려 줍니다. 이것이 **신뢰할 수 있는 게시자**입니다.
2. CI 작업은 게시자 토큰 없이 `gamedev pkg publish`를 실행합니다. CLI는 자신이 GitHub Actions(`ACTIONS_ID_TOKEN_REQUEST_URL`) 또는 GitLab CI(`AIGD_ID_TOKEN`)에서 실행 중임을 감지하고, CI에 대상(audience)이 `ai-game.dev`인 OIDC 신원 토큰을 요청합니다.
3. CLI는 그 토큰을 `POST /api/registry/v1/oidc/token`으로 보냅니다. 레지스트리는 토큰을 검증하고(발급자, 서명, 대상 `ai-game.dev`, 만료) 패키지의 신뢰할 수 있는 게시자와 대조합니다.
4. 일치하면 **해당 패키지 하나**에 대해 **15분** 동안 유효한 자격 증명(`agd_oidc_…`)을 반환하며, 이는 버전 업로드와 버전 상태 조회에만 허용됩니다. CLI는 이 자격 증명으로 업로드합니다.
5. 레지스트리는 새 버전에 해당 실행의 출처를 기록합니다. 이 기록은 이후 절대 변경되지 않습니다.

유출될 수 있는 장기 자격 증명은 없습니다. CI 시크릿에 토큰이 없고, 교체할 것도 없습니다. 같은 OIDC 토큰은 두 번 교환될 수 없으며, 모든 교환은 레지스트리의 감사 로그에 기록됩니다.

## 신뢰할 수 있는 게시자 추가하기

[게시자 패널](https://ai-game.dev/publisher)에서 패키지를 열고 **Trusted publishing**로 이동한 뒤 하나를 추가하세요. 패키지의 게시자에 대한 **owner**여야 합니다. 패키지가 아직 존재하지 않아도 됩니다. 새 패키지 id에 대한 신뢰할 수 있는 게시자는 게시자에 보관되므로, 첫 버전조차 CI에서 게시할 수 있습니다. 한 번도 업로드되지 않은 패키지 id는 게시자의 Packages 탭에서 **Set up a new package**를 사용하세요.

| 필드 | GitHub Actions에서 | GitLab CI에서 |
| --- | --- | --- |
| 공급자 | `github` | `gitlab` |
| 저장소 | `owner/repo` | 프로젝트 경로, `group/subgroup/project` |
| 워크플로 | 실행의 워크플로 파일, `.github/workflows` 내(`publish.yml`, 전체 경로도 가능) | CI 구성 파일의 저장소 경로, 기본값은 `.gitlab-ci.yml` |
| 환경(선택 사항) | 작업이 사용해야 하는 GitHub 배포 환경 | 작업이 사용해야 하는 **보호된(protected)** GitLab 환경 |
| Ref(선택 사항) | 실행이 나와야 하는 브랜치 또는 태그: `main`(`refs/heads/main`으로 해석됨), `refs/tags/v1.2.0`, 또는 끝에 `*` 하나가 붙은 접두사(예: `refs/tags/v*`) | 동일하며, 브랜치 또는 태그가 GitLab에서 **보호되어** 있어야 합니다 |

- 워크플로는 실행 자체의 파일입니다(GitHub의 최상위 `workflow_ref`). 재사용 가능한 액션이나 워크플로가 게시를 수행하는 경우, 그것을 호출하는 **본인의** 워크플로를 지정하세요(예: `.github/workflows/release.yml`).
- ref가 브랜치 또는 태그(`refs/heads/…`, `refs/tags/…`)인 실행만 게시할 수 있으며, 풀 리퀘스트 ref(`refs/pull/…`)는 절대 게시할 수 없습니다. 레지스트리는 `pull_request_target` 실행을 거부합니다(포크의 풀 리퀘스트를 대신해 베이스 브랜치의 ref로 실행되기 때문입니다). `workflow_run`은 허용되므로, 이로 인해 시작된 워크플로가 풀 리퀘스트의 코드를 게시하지 않도록 하세요.
- 게시자를 추가하면 레지스트리가 저장소를 조회하여 숫자 저장소 id와 소유자 id를 고정합니다. 같은 이름으로 삭제 후 다시 만들어진 저장소는 새 id를 가지므로 게시할 수 없습니다. 의도적으로 저장소를 다시 만든 경우 신뢰할 수 있는 게시자를 다시 추가하세요.
- 패키지에는 최대 10개의 신뢰할 수 있는 게시자를 둘 수 있습니다.

**경고**

워크플로는 내용이 아니라 경로로 대조됩니다. 즉 브랜치에 푸시할 수 있는 사람은 누구나 그 파일을 편집할 수 있습니다. GitHub에서는 모든 신뢰할 수 있는 게시자에 필수 리뷰어가 있는 환경이나 배포 브랜치 규칙을 설정하세요. ref만으로는 해당 브랜치가 보호되어 있거나 태그가 태그 규칙 세트로 보호되는 경우에만 안전합니다. 그렇지 않으면 쓰기 권한이 있는 사람이 편집된 워크플로에서 `v9.9.9` 같은 태그를 푸시할 수 있습니다. GitLab에서는 레지스트리 자체가 고정된 환경과 고정된 ref가 보호되어 있을 것을 요구합니다.

## 어떤 CLI를 쓸까

신뢰할 수 있는 게시에는 0.32.0보다 새로운 `gamedev` CLI가 필요하며, 0.32.0 이하에서는 사용할 수 없습니다. 릴리스 빌드가 모르는 사이에 바뀌지 않도록 CI에서는 `latest` 대신 정확한 버전을 고정하세요. 다음 안정 릴리스 전까지 신뢰할 수 있는 게시를 지원하는 CLI는 `beta` 채널에 있으므로, 여기의 예시는 `@baizor/gamedev@beta`를 사용합니다. 해당 릴리스와 함께 `latest`로 바뀝니다. `gamedev pkg publish`는 다음 순서로 자격 증명을 선택합니다.

1. 게시자 토큰(`--token` 또는 `AI_GAME_DEV_PUBLISHER_TOKEN`)이 주어진 경우 그것;
2. GitHub Actions 또는 GitLab CI에서 실행 중인 경우 CI의 OIDC 토큰;
3. 로그인된 세션.

GitHub Actions 내에서, 또는 `AIGD_ID_TOKEN`이 있는 GitLab 작업에서 OIDC 설정이 빠져 있으면 추가해야 할 줄을 알려주는 오류가 발생하며, 해당 위치에서는 세션을 시도하지 않습니다. `--json`을 사용하면 결과의 `auth` 필드에 사용된 자격 증명이 표시됩니다. Trusted Publishing의 경우 `oidc-github` 또는 `oidc-gitlab`입니다. 토큰의 audience는 레지스트리의 것과 정확히 일치해야 합니다. 프로덕션은 `ai-game.dev`이며, 다른 레지스트리의 경우 CLI가 호스트 이름을 도출합니다. `--oidc-audience <aud>`(또는 `AIGD_OIDC_AUDIENCE`)가 이를 재정의하며, GitLab에서는 audience가 작업이 선언한 `aud`이고 CLI는 이를 확인만 합니다.

## GitHub Actions에서 게시

작업에는 `permissions: id-token: write`가 필요합니다. 이것이 audience `ai-game.dev`로 토큰을 요청할 수 있게 해줍니다.

```yaml
name: Publish package
on:
  push:
    tags: ["v*"]

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: registry            # the trusted publisher requires it (reviewers, branch rules)
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci --ignore-scripts && npm run build   # whatever builds dist/; see the tip below
      - run: npx --yes @baizor/gamedev@beta pkg publish . --notes RELEASE_NOTES.md   # pin an exact version newer than 0.32.0
```

신뢰할 수 있는 게시자에서 지정한 워크플로 파일로 저장하세요. 게시자 패널에는 패키지 값이 채워진 동일한 스니펫이 표시됩니다.

**팁**

토큰을 요청할 수 있는 작업의 모든 단계에서 토큰을 사용할 수 있으며, 의존성의 설치 스크립트도 포함됩니다. 빌드가 허용하는 경우 `npm ci --ignore-scripts`로 설치하거나, `id-token: write` 없이 별도 작업에서 빌드하고 `dist/`를 아티팩트로 전달하세요.

**게시 액션.** 동일한 단계를 바로 사용할 수 있는 액션으로 만든 것이 [IvanMurzak/gamedev-publish-action](https://github.com/IvanMurzak/gamedev-publish-action)입니다:

```yaml
      - run: npm ci --ignore-scripts && npm run build
      - id: publish
        uses: IvanMurzak/gamedev-publish-action@v1
        with:
          path: .
          notes: RELEASE_NOTES.md        # optional; default: the version's section of CHANGELOG.md
          cli-version: beta              # pin an exact version newer than 0.32.0
```

| 입력 | 기본값 | 하는 일 |
| --- | --- | --- |
| `path` | `.` | 패키지 폴더(`aigd-package.json` 포함) |
| `notes` | 비어 있음 | 이 버전의 릴리스 노트가 담긴 Markdown 파일 |
| `wait` | `true` | 레지스트리의 검사를 기다리고 거부되면 단계를 실패시킵니다(대기가 끝날 때 여전히 실행 중인 검사는 실패로 처리하지 않음). `false`이면 업로드 후 바로 반환합니다 |
| `cli-version` | `latest` | `@baizor/gamedev` 버전, 정확한 버전(권장) 또는 dist-tag |
| `audience` | 비어 있음 | OIDC audience, 프로덕션이 아닌 레지스트리에만 해당 |
| `node-version` | `22` | CLI를 실행하는 Node.js |

출력 `result`는 CLI의 JSON 출력입니다. 업로드 시에는 id, 버전, 상태, 무결성, auth, 그리고 (대기한 경우) 검사 보고서가 포함됩니다. 업로드 전에 실행이 실패하면 비어 있습니다.

CI의 모든 줄을 자체 저장소에 유지하려면 액션의 `action.yml`을 `.github/actions/publish-package/`에 복사하고 대신 `uses: ./.github/actions/publish-package`를 사용하세요. GitHub에서 참조하는 경우 액션을 커밋 SHA에 고정하세요.

## GitLab CI에서 게시

작업은 `ai-game.dev`를 audience로 하는 `AIGD_ID_TOKEN`이라는 ID 토큰을 선언합니다. 목록이 아닌 하나의 일반 문자열입니다. GitLab은 이를 작업의 환경에 넣고, CLI가 거기서 읽습니다. GitLab은 작업이 시작될 때 토큰을 발급하며, 레지스트리는 발급 후 1시간 동안만 ID 토큰을 받습니다. 시작 후 1시간이 넘어서 게시하는 작업은 `OIDC_TOKEN_TOO_OLD`로 실패하므로, 게시는 짧은 별도 작업에서 하세요.

```yaml
publish-package:
  image: node:22
  id_tokens:
    AIGD_ID_TOKEN:
      aud: ai-game.dev                 # one audience, a plain string
  environment: registry                # the trusted publisher requires it
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - npm ci --ignore-scripts && npm run build   # whatever builds dist/
    - npx --yes @baizor/gamedev@beta pkg publish .   # pin an exact version newer than 0.32.0
```

이 작업은 신뢰할 수 있는 게시자에서 지정한 CI 구성 파일(기본값은 `.gitlab-ci.yml`)에 위치합니다. GitLab에서 `registry` 환경과 릴리스 태그를 보호하세요. 레지스트리는 보호되지 않은 고정 환경이나 ref를 거부합니다. GitLab.com이 지원됩니다.

**템플릿.** 같은 저장소에 숨겨진 작업 `.aigd-publish-package`가 있는 GitLab CI 템플릿이 있습니다. 이를 포함하고 작업을 확장하세요:

```yaml
include:
  - remote: https://raw.githubusercontent.com/IvanMurzak/gamedev-publish-action/v1/gitlab/publish-package.gitlab-ci.yml

publish-package:
  extends: .aigd-publish-package
  before_script:
    - npm ci --ignore-scripts && npm run build
  variables:
    AIGD_PACKAGE_PATH: "."
    AIGD_RELEASE_NOTES: ""             # optional Markdown file
    AIGD_CLI_VERSION: beta             # pin an exact version newer than 0.32.0
  environment: registry
  rules:
    - if: $CI_COMMIT_TAG
```

템플릿을 프로젝트에 복사하여(예: `ci/publish-package.gitlab-ci.yml`) 대신 `local:`로 포함할 수도 있습니다.

## 실행이 거부될 때

`publish`는 레지스트리의 사유와 신뢰할 수 있는 게시자가 일치해야 하는 항목을 출력하고, 아무것도 업로드하지 않고 종료 코드 1로 종료합니다. `id-token: write`나 `id_tokens` 항목이 없고 게시자 토큰도 없는 작업에는 추가해야 할 줄을 알려줍니다. 업로드 자격 증명은 15분 동안 유효합니다. 검사가 더 오래 걸리면 해당 단계는 판정 없이 종료됩니다. 게시자 패널에서, 또는 새 CI 실행이나 로그인한 컴퓨터에서 `gamedev pkg publish`로 결과를 확인하세요(같은 버전을 두 번 업로드하지 않으며, 동일한 CI 토큰은 두 번 사용할 수 없습니다).

## 레지스트리가 확인하는 항목

- **토큰:** `https://token.actions.githubusercontent.com` 또는 `https://gitlab.com`에서 발급되고, 공급자의 현재 키로 서명되었으며, audience가 정확히 `ai-game.dev`이고, 유효 시간 내에 있으며(약간의 시계 오차 허용), 이전에 사용된 적이 없어야 합니다. 또한 교환 전 1시간 이내에 발급된 것이어야 합니다.
- **일치 항목:** 고정된 저장소 및 소유자 id, 워크플로 파일(GitHub의 최상위 워크플로 ref, GitLab의 CI 구성 ref), 브랜치 또는 태그 실행, 그리고 신뢰할 수 있는 게시자가 설정한 경우 환경과 ref입니다.
- **업로드:** 자격 증명은 해당 패키지 하나에만 유효하며 15분 후 만료됩니다. 버전은 다른 업로드와 마찬가지로 모든 [자동 검사](https://ai-game.dev/ko/docs/wiki/app/package-registry#checks)를 통과해야 합니다.

일치하지 않으면 거부되며 CLI가 그 사실을 알려줍니다([위](https://ai-game.dev/ko/docs/wiki/app/trusted-publishing#refused) 참조). 저장소, 워크플로 파일, 그리고 실행에 사용된 환경이나 ref를 확인하세요.

## 출처

Trusted Publishing을 통해 게시된 버전은 어디서 왔는지 기록합니다:

| 필드 | 예시 |
| --- | --- |
| `provider` | `github` |
| `repository`, `repositoryId` | `acme/level-tools`, 해당 숫자 id |
| `commit`, `ref` | 실행의 커밋 SHA와 git ref |
| `workflow` | `.github/workflows/publish.yml` |
| `runId`, `runUrl` | CI 실행과 그 링크 |
| `environment` | 작업이 환경을 사용한 경우 |

출처 정보는 패키지가 아니라 검증된 토큰에서 나오며 변경할 수 없습니다. 서명된 커뮤니티 인덱스에는 각 버전의 제공자, 저장소, 커밋, 워크플로와 실행 링크가 담기고, 앱은 해당 버전이 어디에서 빌드되었는지(예: 저장소, 커밋, 워크플로와 실행 링크를 포함한 "built on GitHub Actions")를 보여 주므로, 사용자는 패키지를 그것을 빌드한 정확한 커밋과 CI 실행까지 거슬러 추적할 수 있습니다.

## 대신 퍼블리셔 토큰 사용하기

Trusted Publishing을 사용할 수 없는 경우(다른 CI, 자체 호스팅 GitLab, 내 컴퓨터의 스크립트)에는 퍼블리셔 토큰을 사용하세요:

```bash
gamedev pkg publisher token create acme --label ci --days 90
# in CI, with the token stored as a secret:
AI_GAME_DEV_PUBLISHER_TOKEN=$AIGD_PUBLISHER_TOKEN gamedev pkg publish .
```

토큰(`agd_pub_…`)은 하나의 퍼블리셔에 속하고, 한 번만 표시되며, 최대 365일 후 만료되고, 업로드와 버전 상태 읽기, yank만 할 수 있습니다. 퍼블리셔는 활성 토큰을 최대 10개까지 가질 수 있으며, `gamedev pkg publisher token revoke acme <token id>` 또는 퍼블리셔 패널에서 토큰을 해지할 수 있습니다. 토큰으로 업로드한 버전에는 출처 정보가 포함되지 않습니다.

## 관련 페이지

- 릴리스 노트, 채널, 지원 중단에 대해서는 [패키지 게시](https://ai-game.dev/ko/docs/wiki/app/publishing-packages)를 참고하세요.
- 모든 버전이 통과하는 검사에 대해서는 [레지스트리 규칙과 검사](https://ai-game.dev/ko/docs/wiki/app/package-registry)를 참고하세요.

---

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

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