Trusted Publishing

Publish AI Game Dev packages from GitHub Actions or GitLab CI without a stored token: set up a trusted publisher, the workflow files, and provenance.

Updated November 19, 2026 View as Markdown

Trusted Publishing lets a CI job publish your package without any secret stored in the CI: GitHub Actions or GitLab CI vouches for which repository and workflow is running, and ai-game.dev exchanges that proof for a short-lived credential that can upload one package. Every version published this way records its provenance: the repository, commit and CI run it was built from. This page shows how to set it up for GitHub and GitLab, and what is checked.

How it works

  1. You tell the registry which repository and workflow may publish a package: a trusted publisher.
  2. Your CI job runs gamedev pkg publish with no publisher token. The CLI sees it runs in GitHub Actions (ACTIONS_ID_TOKEN_REQUEST_URL) or GitLab CI (AIGD_ID_TOKEN) and asks the CI for an OIDC identity token with the audience ai-game.dev.
  3. The CLI sends that token to POST /api/registry/v1/oidc/token. The registry verifies it (issuer, signature, audience ai-game.dev, expiry) and matches it against the package's trusted publishers.
  4. On a match it returns a credential (agd_oidc_…) valid for 15 minutes, for that one package, accepted only for uploading and reading a version's status. The CLI uploads with it.
  5. The registry records the run's provenance on the new version. It never changes afterwards.

Nothing long-lived exists to leak: no token in CI secrets, nothing to rotate. The same OIDC token cannot be exchanged twice, and every exchange is recorded in the registry's audit log.

Add a trusted publisher

In the publisher panel, open the package, then Trusted publishing, and add one. You need to be an owner of the package's publisher. The package does not have to exist yet: a trusted publisher for a new package id is kept for your publisher, so even the first version can come from CI. For a package id that was never uploaded, use Set up a new package on the publisher's Packages tab.

FieldOn GitHub ActionsOn GitLab CI
Providergithubgitlab
Repositoryowner/repothe project path, group/subgroup/project
Workflowthe workflow file of the run, in .github/workflows (publish.yml; the full path works too)the CI configuration file's repository path, .gitlab-ci.yml by default
Environment (optional)a GitHub deployment environment the job must usea protected GitLab environment the job must use
Ref (optional)the branch or tag the run must come from: main (read as refs/heads/main), refs/tags/v1.2.0, or a prefix with one trailing *, such as refs/tags/v*the same, and the branch or tag must be protected in GitLab
  • The workflow is the file of the run itself (GitHub's top-level workflow_ref). When a reusable action or workflow does the publishing, name your workflow that calls it, such as .github/workflows/release.yml.
  • Only runs whose ref is a branch or a tag (refs/heads/…, refs/tags/…) can publish; a pull request ref (refs/pull/…) never can. The registry refuses pull_request_target runs (they run with the base branch's ref on behalf of a fork's pull request). workflow_run is allowed: do not let a workflow it starts publish code from a pull request.
  • When you add it, the registry looks up the repository and pins its numeric repository and owner ids. A repository deleted and re-created under the same name has new ids and cannot publish: add the trusted publisher again if you re-create a repository on purpose.
  • A package has at most 10 trusted publishers.

Which CLI

Trusted Publishing needs a gamedev CLI newer than 0.32.0; 0.32.0 and older cannot do it. Pin an exact version in CI rather than latest, so a release build never changes under you. Until the next stable release, the CLI with Trusted Publishing is on the beta channel, so the examples here use @baizor/gamedev@beta; they move to latest with that release. gamedev pkg publish picks its credential in this order:

  1. a publisher token (--token or AI_GAME_DEV_PUBLISHER_TOKEN), when one is given;
  2. the CI's OIDC token, when it runs in GitHub Actions or GitLab CI;
  3. your signed-in session.

Inside GitHub Actions, or a GitLab job with AIGD_ID_TOKEN, a missing OIDC setup is an error naming the line to add; the session is not tried there. With --json, the result's auth field names the credential that was used: oidc-github or oidc-gitlab for Trusted Publishing. The token's audience must be exactly the registry's: ai-game.dev for production, and for another registry the CLI derives its host name. --oidc-audience <aud> (or AIGD_OIDC_AUDIENCE) overrides that; on GitLab the audience is the aud the job declares, and the CLI only checks it.

Publish from GitHub Actions

The job needs permissions: id-token: write; that is what lets it request a token with the 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

Save it as the workflow file you named on the trusted publisher. The publisher panel shows the same snippet with your package's values filled in.

The publish action. The same steps are a ready action, 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
InputDefaultWhat it does
path.The package folder (with aigd-package.json)
notesemptyA Markdown file with this version's release notes
waittrueWait for the registry's checks and fail the step on a rejection (checks still running when the wait ends do not fail it); false returns after the upload
cli-versionlatestThe @baizor/gamedev version, an exact version (recommended) or a dist-tag
audienceemptyThe OIDC audience, only for a registry other than production
node-version22The Node.js that runs the CLI

Its output result is the CLI's JSON output: on an upload, id, version, state, integrity, auth and (when it waited) the check report; empty when the run failed before uploading.

To keep every line of your CI in your own repository, copy the action's action.yml into .github/actions/publish-package/ and use uses: ./.github/actions/publish-package instead; pin the action to a commit SHA if you reference it from GitHub.

Publish from GitLab CI

The job declares an ID token named AIGD_ID_TOKEN with the audience ai-game.dev, one plain string, not a list. GitLab puts it in the job's environment, where the CLI reads it. GitLab issues it when the job starts, and the registry accepts an ID token for one hour after it was issued: a job that publishes more than an hour after it started fails with OIDC_TOKEN_TOO_OLD, so keep publishing in a short job of its own.

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

This job lives in the CI configuration file you named on the trusted publisher (.gitlab-ci.yml by default). Protect the registry environment and your release tags in GitLab: the registry refuses an unprotected pinned environment or ref. GitLab.com is supported.

A template. The same repository holds a GitLab CI template with a hidden job, .aigd-publish-package. Include it and extend the job:

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

You can also copy the template into your project (for example as ci/publish-package.gitlab-ci.yml) and include it with local: instead.

When a run is refused

publish prints the registry's reason and what the trusted publisher must match, uploads nothing and exits 1. A job without id-token: write or the id_tokens entry, and without a publisher token, is told which line to add. The upload credential lasts 15 minutes: if the checks take longer, the step ends without their verdict; read it in the publisher panel, or with gamedev pkg publish from a new CI run or your signed-in computer (it never uploads the same version twice; the same CI token cannot be used twice).

What the registry checks

  • The token: issued by https://token.actions.githubusercontent.com or https://gitlab.com, signed with the provider's current keys, audience exactly ai-game.dev, within its validity time (a small clock skew allowed), never seen before. It must have been issued less than an hour before the exchange.
  • The match: the pinned repository and owner ids, the workflow file (GitHub's top-level workflow ref, GitLab's CI config ref), a branch or tag run, and the environment and ref when the trusted publisher sets them.
  • The upload: the credential works for its one package and expires after 15 minutes. The version still passes every automatic check like any other upload.

A mismatch is refused, and the CLI says so (see above). Check the repository, the workflow file, and the environment or ref the run used.

Provenance

A version published through Trusted Publishing records where it came from:

FieldExample
providergithub
repository, repositoryIdacme/level-tools, its numeric id
commit, refthe commit SHA and the git ref of the run
workflow.github/workflows/publish.yml
runId, runUrlthe CI run and a link to it
environmentwhen the job used one

Provenance comes from the verified token, never from the package, and is immutable. The signed community index carries the provider, repository, commit, workflow and run link for each version, and the app shows where such a version was built (for example "built on GitHub Actions", with the repository, commit, workflow and a link to the run), so users can follow a package back to the exact commit and CI run that built it.

Publisher tokens instead

Where Trusted Publishing is not available (another CI, a self-hosted GitLab, a script on your computer), use a publisher token:

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 .

A token (agd_pub_…) belongs to one publisher, is shown once, expires after at most 365 days and can only upload, read a version's status and yank. A publisher has at most 10 active tokens; revoke one with gamedev pkg publisher token revoke acme <token id> or in the publisher panel. Versions uploaded with a token carry no provenance.