npm Trusted Publishing

npm Trusted Publishers je doporučený způsob publikování balíčků na npm od července 2025 (GA). Místo dlouhodobých tokenů využívá OIDC (OpenID Connect) — GitHub Actions se automaticky prokáže npm registru svou identitou, žádné tajné tokeny nejsou potřeba. Od prosince 2025 jsou klasické tokeny pro CI/CD prakticky mrtvé.

Jak to funguje

Na npmjs.com jednorázově nakonfigurujete „důvěryhodného vydavatele” — určíte, že konkrétní workflow v konkrétním repozitáři smí daný balíček publikovat. Při běhu workflow GitHub Actions automaticky vygeneruje krátkodobý OIDC token (JWT), npm ověří shodu s konfigurací a vydá jednorázový publikační credential. Žádný tajný klíč nikdy neopustí GitHub infrastrukturu.

Bonus: automaticky se generuje provenance attestation — kryptograficky podepsaný záznam přes Sigstore, který propojuje publikovaný balíček se zdrojovým kódem a konkrétním workflow runem. Na npmjs.com se u balíčku zobrazí zelená značka s odkazem na commit.

Aspekt	Klasické tokeny	Trusted Publishing (OIDC)
Životnost credentials	Max 90 dní	Jednorázové, minuty
Správa secrets	Ruční ukládání + rotace	Žádné secrets
Bezpečnostní riziko	Únik z logů, krádež	Nelze extrahovat
Provenance	Volitelné	Automaticky
Lokální publikování	Ano	Ne — pouze z CI/CD

Setup ve 3 krocích

1. `package.json` — pole `repository` musí sedět

Pole repository musí přesně odpovídat (case-sensitive) vašemu GitHub repozitáři. npm a Sigstore tuto URL validují — při neshodě dostanete chybu 422 Unprocessable Entity.

{
  "name": "muj-balicek",
  "version": "1.0.0",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/vas-username/muj-balicek.git"
  },
  "publishConfig": {
    "access": "public"
  }
}

"access": "public" je nutné pro scoped balíčky (@org/package) při prvním publikování.

2. Konfigurace trusted publisheru na npmjs.com

Balíček musí na npm už existovat — pro dosud nepublikovaný balíček nelze trusted publisher nastavit. Pokud publikujete poprvé, udělejte úvodní verzi ručně (npm publish lokálně).

Jděte na https://www.npmjs.com/package/VAS-BALICEK/access
V sekci Trusted Publisher vyberte GitHub Actions
Vyplňte (vše case-sensitive!):
- Organization or user: váš GitHub username nebo organizace
- Repository: název repozitáře (bez username předpony)
- Workflow filename: přesný název souboru, např. publish.yml
- Environment (volitelné): název GitHub Actions environment

3. GitHub Actions workflow

Uložte jako .github/workflows/publish.yml (název musí odpovídat tomu, co jste zadali na npmjs.com):

name: Publish to npm & Create Release

on:
  push:
    tags:
      - "v*.*.*"
  workflow_dispatch:

permissions: {}

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: write      # pro vytvoření GitHub Release
      id-token: write      # POVINNÉ pro OIDC trusted publishing
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: "24"
          registry-url: "https://registry.npmjs.org"

      - run: npm ci

      - run: npm test

      - run: npm run build --if-present

      - name: Publish to npm
        run: npm publish --provenance --access public

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          tag_name: ${{ github.ref_name }}
          name: Release ${{ github.ref_name }}
          generate_release_notes: true

Jak publikovat:

npm version patch   # nebo minor / major
git push origin main --tags

Proč je workflow napsaný právě takhle

id-token: write — nejdůležitější řádek. Bez něj GitHub Actions nevygeneruje OIDC token a npm se nedokáže autentizovat.
registry-url v setup-node — povinný, přestože registry.npmjs.org je výchozí. Bez explicitního nastavení akce nevytvoří .npmrc soubor potřebný pro autentizaci.
Node 24 — obsahuje npm ≥ 11.5.1, minimální verzi s podporou OIDC. Pro Node 22 přidejte npm install -g npm@latest před publikováním.
--provenance flag — technicky volitelný, ale doporučený. Někteří uživatelé hlásí problémy bez něj při prvním publikování.
Žádný NODE_AUTH_TOKEN — nenastavujte ho ani prázdný. Pokud ho npm CLI detekuje, pokusí se o tokenovou autentizaci místo OIDC.

Alternativní trigger: GitHub Release

Pokud preferujete vytvářet release ručně v GitHub UI:

on:
  release:
    types: [published]

permissions: {}

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "24"
          registry-url: "https://registry.npmjs.org"
      - run: npm ci
      - run: npm publish --provenance --access public

Nejčastější chyby

NODE_AUTH_TOKEN nastaven — pokud ho máte z dřívějšího setupu, smažte ho. I prázdná proměnná způsobí selhání OIDC autentizace.
Chybějící id-token: write — bez tohoto oprávnění GitHub nevygeneruje OIDC token. Chybová hláška bývá zavádějící.
Case sensitivity — username, název repozitáře i název workflow souboru musí přesně odpovídat. Organizace s velkými písmeny (např. FrontEndDev-org) mohou způsobit selhání provenance verifikace.
Self-hosted runnery nefungují — trusted publishing vyžaduje GitHub-hosted runnery.
Jeden trusted publisher na balíček — pro více workflow (prod + beta) použijte jeden vstupní workflow, který deleguje na reusable workflows.
Reusable workflows — id-token: write musí být nastaveno jak na volajícím, tak na volaném workflow.
Privátní repozitáře — provenance se negeneruje, samotná OIDC autentizace ale funguje.

Ověření

Po úspěšném publikování zkontrolujte provenance na stránce balíčku na npmjs.com — měla by být vidět zelená značka s odkazem na zdrojový commit. Lokálně ověříte podpisy příkazem:

npm audit signatures

Pro maximální zabezpečení nastavte na npmjs.com „Require two-factor authentication and disallow tokens” — tím zablokujete jakékoli tokenové publikování a povolíte pouze nakonfigurovaný trusted publisher.

Sources

Vlastní průvodce (interní zdroj) — kompletní setup s detaily a úskalími, ověřeno v praxi 2025–2026