Publisher Account Setup

This runbook configures the publisher side of the release surface. The distribution story has one registry: the scoped npm package @ahmed-g-gad/apothem on npmjs.com, published by the publish-npm.yml workflow. The workflow runs on the v*.*.* tag push beside release.yml and does not wait for it (a manual dispatch with a tag input is the fallback). The release environment approval is the gate: the operator approves it after the GitHub Release, Pages, CI, conformity, and harness workflows are green. Every other artifact ships on the GitHub Release page itself and needs no external publisher account.

Identity MapCopy Anchor Link

The GitHub owner is allowed to drift in the future. Workflow and installer logic reads github.repository, github.repository_owner, or APOTHEM_GITHUB_REPO where a platform permits dynamic resolution. The registry package identifier remains stable because users install the package name, not the maintainer account name.

npm (npmjs.com)Copy Anchor Link

1. Sign in to https://www.npmjs.com/ as ahmed-g-gad.

2. Enable two-factor authentication on the account.

3. Confirm the scoped package name:

   Copy Text

   npm view @ahmed-g-gad/apothem name

   A 404 means the scoped package has not been published yet. Any other package response must match this repository and account before publishing.

4. Create the package on npm if the UI requires a first package record. Keep the name scoped: @ahmed-g-gad/apothem.

5. Configure Trusted Publishing for @ahmed-g-gad/apothem from GitHub Actions:

   • GitHub owner: ahmed-g-gad
   • Repository: apothem
   • Workflow filename: publish-npm.yml
   • Environment: release (the environment: of the publish job in publish-npm.yml; the two must match)
   • Allowed action: npm publish.

6. In GitHub, verify the release environment exists on ahmed-g-gad/apothem and requires manual approval for deployment.

7. Keep the npm surface to one public registry package: @ahmed-g-gad/apothem on npmjs.com.

8. Approve the publish GitHub Release job of the release.yml run that the tag push starts. It waits for the release environment approval, and the check below needs that run green; the release-cycle runbook, §2.3, shows how. Then confirm release readiness:

   Copy Text

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

   The check needs GH_TOKEN set and the published sbom.cdx.json in dist/release-assets/. The release-cycle runbook, §2.4, gives the token scope and the download command.

9. Approve the release environment deployment for the Publish npm (publish-npm.yml) run that the tag push starts. If that run did not start, dispatch the workflow from the GitHub Actions tab with tag=<release-tag>.

10. Verify the live package:

    Copy Text

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

No NPM_TOKEN, username, or password secret is required. The workflow publishes through npm Trusted Publishing (OIDC) with the Node version and the npm CLI OIDC floor pinned inside .github/workflows/publish-npm.yml. It runs npm publish --provenance --access public against npmjs.com, so the Sigstore provenance statement is explicit; npm also emits provenance by default for public packages published from a public GitHub Actions workflow. A registry 404 during PUT means the npm-side trusted publisher, package scope, or account authorization is not aligned yet; fix the npm package settings before retrying the workflow.

Once a trusted publish has succeeded, close the token path for good: in the package's Settings → Publishing access on npmjs.com, select Require two-factor authentication and disallow tokens, and delete any npm token secret left in the repository. The workflow no longer reads one.

References: npm Trusted Publishers, npm provenance, and npm scopes.

GitHub-side release prerequisitesCopy Anchor Link

The remaining release surfaces are GitHub-native and authenticate with the repository-scoped GITHUB_TOKEN; no external account is involved.

1. GitHub Release. .github/workflows/release.yml runs on the version tag and needs only its job-local contents: write permission. Confirm the workflow file is present on main before tagging.

2. Pages custom domain. The documentation site deploys through publish-static-site.yml to the custom domain apothem.ahmedgad.com. The domain, DNS, and HTTPS enforcement are established by the Pages-enablement runbook; verify:

   Copy Text

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

3. Script installers. install.sh and install.ps1 are served from the Pages site (https://apothem.ahmedgad.com/install.sh and https://apothem.ahmedgad.com/install.ps1). They are published by the same Pages deployment; no separate account or token is required.

Verification matrixCopy Anchor Link

After setup, each publisher surface answers its canonical check: