Configuração da conta de publicador

Este runbook configura o lado do publicador da superfície de lançamento. A distribuição tem um único registro: o pacote npm com escopo @ahmed-g-gad/apothem no npmjs.com, publicado pelo fluxo de trabalho publish-npm.yml. O fluxo de trabalho é executado no push da tag v*.*.*, ao lado de release.yml, e não espera por ele (um despacho manual com uma entrada tag é a alternativa). A aprovação do ambiente release é o portão: o operador a aprova depois que os fluxos de trabalho de GitHub Release, Pages, CI, conformidade e harness estiverem verdes. Todos os demais artefatos são distribuídos na própria página do GitHub Release e não precisam de nenhuma conta de publicador externa.

Mapa de identidadeCopy Anchor Link

O proprietário do GitHub pode mudar no futuro. A lógica dos fluxos de trabalho e do instalador lê github.repository, github.repository_owner ou APOTHEM_GITHUB_REPO onde uma plataforma permite a resolução dinâmica. O identificador do pacote no registro permanece estável porque os usuários instalam o nome do pacote, não o nome da conta do mantenedor.

npm (npmjs.com)Copy Anchor Link

1. Faça login em https://www.npmjs.com/ como ahmed-g-gad.

2. Habilite a autenticação de dois fatores na conta.

3. Confirme o nome do pacote com escopo:

   Copy Text

   npm view @ahmed-g-gad/apothem name

   Um 404 significa que o pacote com escopo ainda não foi publicado. Qualquer outra resposta de pacote deve corresponder a este repositório e a esta conta antes da publicação.

4. Crie o pacote no npm se a interface exigir um primeiro registro de pacote. Mantenha o nome com escopo: @ahmed-g-gad/apothem.

5. Configure o Trusted Publishing para @ahmed-g-gad/apothem a partir do GitHub Actions:

   • Proprietário do GitHub: ahmed-g-gad
   • Repositório: apothem
   • Nome do arquivo do fluxo de trabalho: publish-npm.yml
   • Ambiente: release (o environment: do job de publicação em publish-npm.yml; os dois devem corresponder)
   • Ação permitida: npm publish.

6. No GitHub, verifique se o ambiente release existe em ahmed-g-gad/apothem e se exige aprovação manual para a implantação.

7. Mantenha a superfície do npm em um único pacote de registro público: @ahmed-g-gad/apothem no npmjs.com.

8. Aprove o job publish GitHub Release da execução de release.yml que o push da tag inicia. Ele aguarda a aprovação do ambiente release, e a verificação abaixo exige que essa execução esteja verde; o runbook do ciclo de lançamento, §2.3, indica como. Depois, confirme a prontidão para o lançamento:

   Copy Text

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

   A verificação exige que GH_TOKEN esteja definido e que o sbom.cdx.json publicado esteja em dist/release-assets/. O runbook do ciclo de lançamento, §2.4, indica o escopo do token e o comando de download.

9. Aprove a implantação do ambiente release para a execução de Publish npm (publish-npm.yml) que o push da tag inicia. Se essa execução não foi iniciada, despache o fluxo de trabalho na aba GitHub Actions com tag=<release-tag>.

10. Verifique o pacote publicado:

    Copy Text

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

Nenhum segredo NPM_TOKEN, de nome de usuário ou de senha é necessário. O fluxo de trabalho publica por meio do npm Trusted Publishing (OIDC), com a versão do Node e o piso de OIDC da CLI do npm fixados dentro de .github/workflows/publish-npm.yml. Ele executa npm publish --provenance --access public no npmjs.com, de modo que a declaração de procedência do Sigstore é explícita; o npm também emite procedência por padrão para pacotes públicos publicados a partir de um fluxo de trabalho público do GitHub Actions. Um 404 do registro durante o PUT significa que o publicador confiável do lado do npm, o escopo do pacote ou a autorização da conta ainda não estão alinhados; corrija as configurações do pacote no npm antes de tentar o fluxo de trabalho novamente.

Depois que uma publicação confiável tiver sido bem-sucedida, feche o caminho dos tokens de vez: em Settings → Publishing access do pacote no npmjs.com, selecione Require two-factor authentication and disallow tokens e exclua qualquer segredo de token do npm que tenha ficado no repositório. O fluxo de trabalho não lê mais nenhum.

Referências: Publicadores confiáveis do npm, procedência do npm e escopos do npm.

Pré-requisitos de lançamento do lado do GitHubCopy Anchor Link

As superfícies de lançamento restantes são nativas do GitHub e se autenticam com o GITHUB_TOKEN com escopo de repositório; nenhuma conta externa está envolvida.

1. GitHub Release. .github/workflows/release.yml é executado na tag de versão e precisa apenas da sua permissão contents: write, local ao job. Confirme que o arquivo do fluxo de trabalho está presente em main antes de marcar a tag.

2. Domínio personalizado do Pages. O site de documentação é implantado por meio de publish-static-site.yml no domínio personalizado apothem.ahmedgad.com. O domínio, o DNS e a imposição de HTTPS são estabelecidos pelo runbook de habilitação do Pages; verifique:

   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 são servidos a partir do site do Pages (https://apothem.ahmedgad.com/install.sh e https://apothem.ahmedgad.com/install.ps1). Eles são publicados pela mesma implantação do Pages; nenhuma conta ou token separado é necessário.

Matriz de verificaçãoCopy Anchor Link

Após a configuração, cada superfície de publicador responde à sua verificação canônica: