Configuración de la cuenta de publicador

Este runbook configura el lado del publicador de la superficie de lanzamiento. El esquema de distribución tiene un único registro: el paquete npm con alcance @ahmed-g-gad/apothem en npmjs.com, publicado por el flujo de trabajo publish-npm.yml. El flujo de trabajo se ejecuta con el push de la etiqueta v*.*.* junto a release.yml y no espera a que este termine (un despacho manual con una entrada tag es la alternativa de respaldo). La aprobación del entorno release es la puerta: el operador la aprueba después de que los flujos de trabajo de GitHub Release, Pages, CI, conformidad y entornos estén en verde. Todos los demás artefactos se distribuyen en la propia página del GitHub Release y no necesitan ninguna cuenta de publicador externa.

Mapa de identidadesCopy Anchor Link

Se admite que el propietario de GitHub cambie en el futuro. La lógica de los flujos de trabajo y del instalador lee github.repository, github.repository_owner o APOTHEM_GITHUB_REPO donde una plataforma permite la resolución dinámica. El identificador del paquete en el registro permanece estable porque los usuarios instalan el nombre del paquete, no el nombre de la cuenta del mantenedor.

npm (npmjs.com)Copy Anchor Link

1. Inicia sesión en https://www.npmjs.com/ como ahmed-g-gad.

2. Habilita la autenticación de dos factores en la cuenta.

3. Confirma el nombre del paquete con alcance:

   Copy Text

   npm view @ahmed-g-gad/apothem name

   Un 404 significa que el paquete con alcance todavía no se ha publicado. Cualquier otra respuesta de paquete debe coincidir con este repositorio y esta cuenta antes de publicar.

4. Crea el paquete en npm si la interfaz requiere un primer registro del paquete. Mantén el nombre con alcance: @ahmed-g-gad/apothem.

5. Configura Trusted Publishing para @ahmed-g-gad/apothem desde GitHub Actions:

   • Propietario de GitHub: ahmed-g-gad
   • Repositorio: apothem
   • Nombre de archivo del flujo de trabajo: publish-npm.yml
   • Entorno: release (el environment: del trabajo de publicación en publish-npm.yml; ambos deben coincidir)
   • Acción permitida: npm publish.

6. En GitHub, verifica que el entorno release existe en ahmed-g-gad/apothem y que requiere aprobación manual para el despliegue.

7. Limita la superficie de npm a un único paquete de registro público: @ahmed-g-gad/apothem en npmjs.com.

8. Aprueba el trabajo publish GitHub Release de la ejecución de release.yml que inicia el push de la etiqueta. El trabajo espera la aprobación del entorno release, y la comprobación siguiente necesita que esa ejecución esté en verde; el runbook del ciclo de lanzamiento, §2.3, indica cómo. Después, confirma que el lanzamiento está listo:

   Copy Text

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

   La comprobación necesita que GH_TOKEN esté definido y que el sbom.cdx.json publicado esté en dist/release-assets/. El runbook del ciclo de lanzamiento, §2.4, indica el alcance del token y el comando de descarga.

9. Aprueba el despliegue del entorno release para la ejecución de Publish npm (publish-npm.yml) que inicia el push de la etiqueta. Si esa ejecución no se inició, despacha el flujo de trabajo desde la pestaña GitHub Actions con tag=<release-tag>.

10. Verifica el paquete publicado:

    Copy Text

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

No se requiere ningún secreto NPM_TOKEN, de nombre de usuario ni de contraseña. El flujo de trabajo publica mediante npm Trusted Publishing (OIDC), con la versión de Node y la versión mínima de la CLI de npm para OIDC fijadas dentro de .github/workflows/publish-npm.yml. Ejecuta npm publish --provenance --access public contra npmjs.com, de modo que la declaración de procedencia de Sigstore es explícita; npm también emite la procedencia de forma predeterminada para los paquetes públicos publicados desde un flujo de trabajo público de GitHub Actions. Un 404 del registro durante PUT significa que el publicador de confianza del lado de npm, el alcance del paquete o la autorización de la cuenta todavía no están alineados; corrige la configuración del paquete en npm antes de reintentar el flujo de trabajo.

Una vez que una publicación de confianza haya tenido éxito, cierra definitivamente la vía de los tokens: en Settings → Publishing access del paquete en npmjs.com, selecciona Require two-factor authentication and disallow tokens y elimina cualquier secreto de token de npm que quede en el repositorio. El flujo de trabajo ya no lee ninguno.

Referencias: Publicadores de confianza de npm, procedencia de npm y alcances de npm.

Requisitos previos de lanzamiento del lado de GitHubCopy Anchor Link

Las superficies de lanzamiento restantes son nativas de GitHub y se autentican con el GITHUB_TOKEN con alcance de repositorio; no interviene ninguna cuenta externa.

1. GitHub Release. .github/workflows/release.yml se ejecuta con la etiqueta de versión y solo necesita su permiso contents: write, local del trabajo. Confirma que el archivo del flujo de trabajo está presente en main antes de etiquetar.

2. Dominio personalizado de Pages. El sitio de documentación se despliega mediante publish-static-site.yml en el dominio personalizado apothem.ahmedgad.com. El dominio, el DNS y la aplicación obligatoria de HTTPS los establece el runbook de habilitación de Pages; verifica:

   Copy Text

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

3. Instaladores de script. install.sh e install.ps1 se sirven desde el sitio de Pages (https://apothem.ahmedgad.com/install.sh y https://apothem.ahmedgad.com/install.ps1). Se publican con el mismo despliegue de Pages; no se requiere ninguna cuenta ni token aparte.

Matriz de verificaciónCopy Anchor Link

Después de la configuración, cada superficie de publicador responde a su comprobación canónica: