이 페이지는 영어에서 기계 번역되었습니다. 영어 원문 읽기.

신뢰할 수 있는 게시

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

2026년 11월 19일 업데이트 Markdown으로 보기

신뢰할 수 있는 게시를 사용하면 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 토큰은 두 번 교환될 수 없으며, 모든 교환은 레지스트리의 감사 로그에 기록됩니다.

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

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

필드GitHub Actions에서GitLab CI에서
공급자githubgitlab
저장소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개의 신뢰할 수 있는 게시자를 둘 수 있습니다.

어떤 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로 토큰을 요청할 수 있게 해줍니다.

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

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

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

      - 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 파일
waittrue레지스트리의 검사를 기다리고 거부되면 단계를 실패시킵니다(대기가 끝날 때 여전히 실행 중인 검사는 실패로 처리하지 않음). false이면 업로드 후 바로 반환합니다
cli-versionlatest@baizor/gamedev 버전, 정확한 버전(권장) 또는 dist-tag
audience비어 있음OIDC audience, 프로덕션이 아닌 레지스트리에만 해당
node-version22CLI를 실행하는 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로 실패하므로, 게시는 짧은 별도 작업에서 하세요.

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 템플릿이 있습니다. 이를 포함하고 작업을 확장하세요:

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분 후 만료됩니다. 버전은 다른 업로드와 마찬가지로 모든 자동 검사를 통과해야 합니다.

일치하지 않으면 거부되며 CLI가 그 사실을 알려줍니다(위 참조). 저장소, 워크플로 파일, 그리고 실행에 사용된 환경이나 ref를 확인하세요.

출처

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

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

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

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

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

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> 또는 퍼블리셔 패널에서 토큰을 해지할 수 있습니다. 토큰으로 업로드한 버전에는 출처 정보가 포함되지 않습니다.