신뢰할 수 있는 게시
저장된 토큰 없이 GitHub Actions 또는 GitLab CI에서 AI Game Dev 패키지를 게시하세요: 신뢰할 수 있는 게시자, 워크플로 파일, 출처(provenance)를 설정합니다.
신뢰할 수 있는 게시를 사용하면 CI에 비밀을 저장하지 않고도 CI 작업이 패키지를 게시할 수 있습니다. GitHub Actions 또는 GitLab CI가 어떤 저장소와 워크플로가 실행 중인지 보증하고, ai-game.dev는 그 증명을 하나의 패키지를 업로드할 수 있는 단기 자격 증명으로 교환합니다. 이렇게 게시된 모든 버전은 출처(provenance) 를 기록합니다. 즉 어느 저장소, 커밋, CI 실행에서 빌드되었는지가 남습니다. 이 페이지는 GitHub와 GitLab에서 이를 설정하는 방법과 무엇이 검사되는지 설명합니다.
작동 방식
- 어떤 저장소와 워크플로가 패키지를 게시할 수 있는지 레지스트리에 알려 줍니다. 이것이 신뢰할 수 있는 게시자입니다.
- CI 작업은 게시자 토큰 없이
gamedev pkg publish를 실행합니다. CLI는 자신이 GitHub Actions(ACTIONS_ID_TOKEN_REQUEST_URL) 또는 GitLab CI(AIGD_ID_TOKEN)에서 실행 중임을 감지하고, CI에 대상(audience)이ai-game.dev인 OIDC 신원 토큰을 요청합니다. - CLI는 그 토큰을
POST /api/registry/v1/oidc/token으로 보냅니다. 레지스트리는 토큰을 검증하고(발급자, 서명, 대상ai-game.dev, 만료) 패키지의 신뢰할 수 있는 게시자와 대조합니다. - 일치하면 해당 패키지 하나에 대해 15분 동안 유효한 자격 증명(
agd_oidc_…)을 반환하며, 이는 버전 업로드와 버전 상태 조회에만 허용됩니다. CLI는 이 자격 증명으로 업로드합니다. - 레지스트리는 새 버전에 해당 실행의 출처를 기록합니다. 이 기록은 이후 절대 변경되지 않습니다.
유출될 수 있는 장기 자격 증명은 없습니다. CI 시크릿에 토큰이 없고, 교체할 것도 없습니다. 같은 OIDC 토큰은 두 번 교환될 수 없으며, 모든 교환은 레지스트리의 감사 로그에 기록됩니다.
신뢰할 수 있는 게시자 추가하기
게시자 패널에서 패키지를 열고 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개의 신뢰할 수 있는 게시자를 둘 수 있습니다.
어떤 CLI를 쓸까
신뢰할 수 있는 게시에는 0.32.0보다 새로운 gamedev CLI가 필요하며, 0.32.0 이하에서는 사용할 수 없습니다. 릴리스 빌드가 모르는 사이에 바뀌지 않도록 CI에서는 latest 대신 정확한 버전을 고정하세요. 다음 안정 릴리스 전까지 신뢰할 수 있는 게시를 지원하는 CLI는 beta 채널에 있으므로, 여기의 예시는 @baizor/gamedev@beta를 사용합니다. 해당 릴리스와 함께 latest로 바뀝니다. gamedev pkg publish는 다음 순서로 자격 증명을 선택합니다.
- 게시자 토큰(
--token또는AI_GAME_DEV_PUBLISHER_TOKEN)이 주어진 경우 그것; - GitHub Actions 또는 GitLab CI에서 실행 중인 경우 CI의 OIDC 토큰;
- 로그인된 세션.
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 파일 |
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로 실패하므로, 게시는 짧은 별도 작업에서 하세요.
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을 통해 게시된 버전은 어디서 왔는지 기록합니다:
| 필드 | 예시 |
|---|---|
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, 내 컴퓨터의 스크립트)에는 퍼블리셔 토큰을 사용하세요:
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> 또는 퍼블리셔 패널에서 토큰을 해지할 수 있습니다. 토큰으로 업로드한 버전에는 출처 정보가 포함되지 않습니다.
관련 페이지
- 릴리스 노트, 채널, 지원 중단에 대해서는 패키지 게시를 참고하세요.
- 모든 버전이 통과하는 검사에 대해서는 레지스트리 규칙과 검사를 참고하세요.