# 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.

_Last updated: 2026-11-19_

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](https://ai-game.dev/publisher), 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.

| Field | On GitHub Actions | On GitLab CI |
| --- | --- | --- |
| Provider | `github` | `gitlab` |
| Repository | `owner/repo` | the project path, `group/subgroup/project` |
| Workflow | the 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 use | a **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.

**Warning**

The workflow is matched by its path, not its contents: anyone who can push a branch can edit that file. On GitHub, set an environment with required reviewers or a deployment branch rule on every trusted publisher; a ref alone protects only when that branch is protected or the tags are covered by a tag ruleset (otherwise anyone with write access can push a tag such as `v9.9.9` on an edited workflow). On GitLab the registry itself requires a pinned environment and a pinned ref to be protected.

## 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`.

```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
```

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.

**Tip**

Every step of a job that may request the token can use it, including install scripts of your dependencies. Install with `npm ci --ignore-scripts` where your build allows it, or build in a separate job without `id-token: write` and pass `dist/` on as an artifact.

**The publish action.** The same steps are a ready action, [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
```

| Input | Default | What it does |
| --- | --- | --- |
| `path` | `.` | The package folder (with `aigd-package.json`) |
| `notes` | empty | A Markdown file with this version's release notes |
| `wait` | `true` | Wait 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-version` | `latest` | The `@baizor/gamedev` version, an exact version (recommended) or a dist-tag |
| `audience` | empty | The OIDC audience, only for a registry other than production |
| `node-version` | `22` | The 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.

```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
```

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:

```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
```

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](https://ai-game.dev/docs/wiki/app/package-registry#checks) like any other upload.

A mismatch is refused, and the CLI says so (see [above](https://ai-game.dev/docs/wiki/app/trusted-publishing#refused)). 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:

| Field | Example |
| --- | --- |
| `provider` | `github` |
| `repository`, `repositoryId` | `acme/level-tools`, its numeric id |
| `commit`, `ref` | the commit SHA and the git ref of the run |
| `workflow` | `.github/workflows/publish.yml` |
| `runId`, `runUrl` | the CI run and a link to it |
| `environment` | when 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:

```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 .
```

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.

## Related pages

- [Publishing packages](https://ai-game.dev/docs/wiki/app/publishing-packages) for release notes, channels and deprecation.
- [Registry rules and checks](https://ai-game.dev/docs/wiki/app/package-registry) for the checks every version passes.

---

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