Einrichtung des Publisher-Kontos

Dieses Runbook konfiguriert die Publisher-Seite der Release-Oberfläche. Die Distributionsgeschichte hat eine einzige Registry: das Scoped-npm-Paket @ahmed-g-gad/apothem auf npmjs.com, veröffentlicht vom Workflow publish-npm.yml. Der Workflow läuft beim Push eines v*.*.*-Tags neben release.yml und wartet nicht auf ihn (ein manueller Dispatch mit einer tag-Eingabe ist der Ausweichweg). Die Genehmigung der Umgebung release ist das Gate: Der Operator erteilt sie, nachdem die Workflows für GitHub Release, Pages, CI, Konformität und Harness grün sind. Jedes andere Artefakt wird auf der GitHub-Release-Seite selbst ausgeliefert und benötigt kein externes Publisher-Konto.

IdentitätszuordnungCopy Anchor Link

Der GitHub-Eigentümer darf sich künftig ändern. Die Workflow- und Installer-Logik liest github.repository, github.repository_owner oder APOTHEM_GITHUB_REPO, wo eine Plattform dynamische Auflösung zulässt. Der Paketbezeichner in der Registry bleibt stabil, weil Benutzer den Paketnamen installieren, nicht den Kontonamen des Maintainers.

npm (npmjs.com)Copy Anchor Link

1. Melden Sie sich bei https://www.npmjs.com/ als ahmed-g-gad an.

2. Aktivieren Sie die Zwei-Faktor-Authentifizierung für das Konto.

3. Bestätigen Sie den Scoped-Paketnamen:

   Copy Text

   npm view @ahmed-g-gad/apothem name

   Ein 404 bedeutet, dass das Scoped-Paket noch nicht veröffentlicht wurde. Jede andere Paketantwort muss vor der Veröffentlichung mit diesem Repository und diesem Konto übereinstimmen.

4. Erstellen Sie das Paket auf npm, falls die Benutzeroberfläche einen ersten Paketeintrag verlangt. Behalten Sie den Namen mit Scope bei: @ahmed-g-gad/apothem.

5. Konfigurieren Sie Trusted Publishing für @ahmed-g-gad/apothem aus GitHub Actions:

   • GitHub-Eigentümer: ahmed-g-gad
   • Repository: apothem
   • Workflow-Dateiname: publish-npm.yml
   • Umgebung: release (das environment: des Publish-Jobs in publish-npm.yml; beide müssen übereinstimmen)
   • Erlaubte Aktion: npm publish.

6. Verifizieren Sie in GitHub, dass die Umgebung release in ahmed-g-gad/apothem existiert und eine manuelle Genehmigung für das Deployment verlangt.

7. Beschränken Sie die npm-Oberfläche auf ein öffentliches Registry-Paket: @ahmed-g-gad/apothem auf npmjs.com.

8. Genehmigen Sie den Job publish GitHub Release im Lauf von release.yml, den der Tag-Push startet. Der Job wartet auf die Genehmigung der Umgebung release, und die Prüfung unten setzt voraus, dass dieser Lauf grün ist; das Runbook zum Release-Zyklus, §2.3, zeigt, wie. Bestätigen Sie danach die Release-Bereitschaft:

   Copy Text

   bash scripts/release/check-release-ready.sh <release-tag>

   Die Prüfung setzt voraus, dass GH_TOKEN gesetzt ist und die veröffentlichte sbom.cdx.json in dist/release-assets/ liegt. Das Runbook zum Release-Zyklus, §2.4, nennt den Geltungsbereich des Tokens und den Download-Befehl.

9. Genehmigen Sie das Deployment der Umgebung release für den Lauf von Publish npm (publish-npm.yml), den der Tag-Push startet. Falls dieser Lauf nicht gestartet wurde, lösen Sie den Workflow über den Tab GitHub Actions mit tag=<release-tag> aus.

10. Verifizieren Sie das Live-Paket:

    Copy Text

    npm view @ahmed-g-gad/apothem version
    npx @ahmed-g-gad/apothem@<version> --version

Es ist kein NPM_TOKEN-, Benutzernamen- oder Passwort-Secret erforderlich. Der Workflow veröffentlicht über npm Trusted Publishing (OIDC), wobei die Node-Version und der OIDC-Mindeststand der npm-CLI in .github/workflows/publish-npm.yml gepinnt sind. Er führt npm publish --provenance --access public gegen npmjs.com aus, sodass die Sigstore-Provenienzaussage ausdrücklich angefordert wird; npm erzeugt außerdem standardmäßig Provenienz für öffentliche Pakete, die aus einem öffentlichen GitHub-Actions-Workflow veröffentlicht werden. Ein Registry-404 während PUT bedeutet, dass der vertrauenswürdige Publisher auf npm-Seite, der Paket-Scope oder die Kontoautorisierung noch nicht abgestimmt ist; korrigieren Sie die npm-Paketeinstellungen, bevor Sie den Workflow erneut versuchen.

Sobald eine vertrauenswürdige Veröffentlichung gelungen ist, schließen Sie den Token-Pfad endgültig: Wählen Sie in den Settings → Publishing access des Pakets auf npmjs.com die Option Require two-factor authentication and disallow tokens, und löschen Sie jedes npm-Token-Secret, das noch im Repository liegt. Der Workflow liest keines mehr.

Referenzen: npm Trusted Publishers, npm-Provenienz und npm-Scopes.

GitHub-seitige Release-VoraussetzungenCopy Anchor Link

Die übrigen Release-Oberflächen sind GitHub-nativ und authentifizieren sich mit dem auf das Repository beschränkten GITHUB_TOKEN; es ist kein externes Konto beteiligt.

1. GitHub Release. .github/workflows/release.yml läuft auf dem Versions-Tag und benötigt nur seine job-lokale Berechtigung contents: write. Bestätigen Sie vor dem Taggen, dass die Workflow-Datei auf main vorhanden ist.

2. Benutzerdefinierte Pages-Domain. Die Dokumentationsseite wird über publish-static-site.yml auf die benutzerdefinierte Domain apothem.ahmedgad.com bereitgestellt. Die Domain, das DNS und die HTTPS-Erzwingung werden durch das Pages-Aktivierungs-Runbook eingerichtet; verifizieren Sie:

   Copy Text

   gh api repos/ahmed-g-gad/apothem/pages --jq '.cname, .https_enforced'
   curl -sSI https://apothem.ahmedgad.com/ | head -n 1

3. Skript-Installer. install.sh und install.ps1 werden von der Pages-Website ausgeliefert (https://apothem.ahmedgad.com/install.sh und https://apothem.ahmedgad.com/install.ps1). Sie werden durch dasselbe Pages-Deployment veröffentlicht; es ist kein separates Konto und kein Token erforderlich.

VerifizierungsmatrixCopy Anchor Link

Nach der Einrichtung beantwortet jede Publisher-Oberfläche ihre kanonische Prüfung: