Observação: no momento, não há suporte para os executores hospedados no GitHub no GitHub Enterprise Server. Você pode ver mais informações sobre o suporte futuro planejado no GitHub public roadmap.
Introdução
Este guia mostra como criar um fluxo de trabalho que publica pacotes do Node.js em GitHub Packages e nos registros npm após os testes de integração contínua (CI) serem aprovados.
Pré-requisitos
Recomendamos que você tenha um entendimento básico das opções de configuração do fluxo de trabalho e de como criar um arquivo do fluxo de trabalho. Para obter mais informações, confira "Escrevendo fluxos de trabalho".
Para obter mais informações sobre como criar um fluxo de trabalho de CI para seu projeto do Node.js, confira "Criar e testar Node.js".
Você também pode achar útil ter um entendimento básico do seguinte:
- "Trabalhando com o registro npm"
- "Store information in variables"
- "Usar segredos em ações do GitHub"
- "Autenticação automática de token"
Sobre a configuração do pacote
Os campos name
e version
no arquivo package.json
criam um identificador exclusivo usados pelos registros para vincular pacotes a registros. Você pode adicionar um resumo para a página de listagem de pacotes ao incluir um campo de description
no arquivo package.json
. Para obter mais informações, confira "Criar um arquivo package.json" e "Criar módulos Node.js" na documentação npm.
Quando um arquivo .npmrc
local existe e possui um valor especificado para registry
, o comando npm publish
utiliza o registro configurado no arquivo .npmrc
. Você pode usar a ação setup-node
para criar um arquivo .npmrc local no executor que configura o registro e o escopo padrão. A ação setup-node
também aceita um token de autenticação como entrada, usado para acessar registros privados ou publicar pacotes de nós. Para obter mais informações, confira setup-node
.
Você pode especificar a versão do Node.js instalada no executor usando a ação setup-node
.
Se você adicionar etapas ao seu fluxo de trabalho para configurar os campos publishConfig
no arquivo package.json
, você não precisará especificar a URL do registro usando a ação setup-node
, mas não poderá publicar o pacote em mais de um registro. Para obter mais informações, confira "publishConfig" na documentação do npm.
Publicar pacotes no registro npm
Cada vez que você publicar uma nova versão, poderá acionar um fluxo de trabalho para publicar o seu pacote. O processo no exemplo a seguir é executado quando o evento de lançamento do tipo published
é disparado. Se os testes de CI forem aprovados, o processo carregará o pacote no registro npm. Para obter mais informações, confira "Gerenciar versões em repositórios".
Para executar operações autenticadas para o registro npm em seu fluxo de trabalho, você precisará armazenar seu token de autenticação npm como um segredo. Por exemplo, crie um segredo do repositório chamado NPM_TOKEN
. Para obter mais informações, confira "Usar segredos em ações do GitHub".
Por padrão, o npm usa o campo name
do arquivo package.json
para determinar o nome do pacote publicado. Ao publicar em um namespace global, você precisa incluir apenas o nome do pacote. Por exemplo, você publicaria um pacote nomeado my-package
para https://www.npmjs.com/package/my-package
.
Se você estiver publicando um pacote que inclui um prefixo de escopo, inclua o escopo no nome do arquivo package.json
. Por exemplo, se o prefixo do escopo do npm for "octocat" e o nome do pacote for "hello-world", o campo name
no seu arquivo package.json
deverá ser @octocat/hello-world
. Se o seu pacote npm usar um prefixo de escopo e for público, você deverá usar a opção npm publish --access public
. Essa é uma opção que o npm requer para impedir que alguém publique um pacote privado de forma não intencional.
Este exemplo armazena o segredo NPM_TOKEN
na variável de ambiente NODE_AUTH_TOKEN
. Quando a ação setup-node
cria um arquivo .npmrc
, ele faz referência ao token da variável de ambiente NODE_AUTH_TOKEN
.
name: Publish Package to npmjs on: release: types: [published] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 # Setup .npmrc file to publish to npm - uses: actions/setup-node@v4 with: node-version: '20.x' registry-url: 'https://registry.npmjs.org' - run: npm ci - run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
name: Publish Package to npmjs
on:
release:
types: [published]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Setup .npmrc file to publish to npm
- uses: actions/setup-node@v4
with:
node-version: '20.x'
registry-url: 'https://registry.npmjs.org'
- run: npm ci
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
No exemplo acima, a ação setup-node
cria um arquivo .npmrc
no executor com os seguintes tipos de conteúdo:
//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
registry=https://registry.npmjs.org/
always-auth=true
Observe que você precisa definir o registry-url
para https://registry.npmjs.org/
no setup-node
para configurar corretamente suas credenciais.
Publicar pacotes em GitHub Packages
Cada vez que você publicar uma nova versão, poderá acionar um fluxo de trabalho para publicar o seu pacote. O processo no exemplo a seguir é executado quando o evento de lançamento do tipo published
é disparado. Se os testes de CI forem aprovados, o processo carregará o pacote para GitHub Packages. Para obter mais informações, confira "Gerenciar versões em repositórios".
Configurar o repositório de destino
Vincular seu pacote a GitHub Packages usando a chave repository
é opcional. Se você optar por não fornecer a chave repository
no arquivo package.json
, então GitHub Packages publica um pacote no repositório GitHub que você especifica no campo name
do arquivo package.json
. Por exemplo, você publicará um pacote chamado @my-org/test
no repositório my-org/test
do GitHub. Se a url
especificada na chave repository
for inválida, seu pacote ainda poderá ser publicado, porém não será vinculado à fonte do repositório, conforme pretendido.
Se você fornecer a chave repository
no arquivo package.json
, o repositório nessa chave será usado como o registro de npm de destino para GitHub Packages. Por exemplo, publicar o package.json
a seguir resulta em um pacote chamado my-package
publicado no octocat/my-other-repo
GitHub. Uma vez publicado, apenas a fonte do repositório é atualizada, e o pacote não herda nenhuma permissão do repositório de destino.
{
"name": "@octocat/my-package",
"repository": {
"type": "git",
"url": "https://github.com/octocat/my-other-repo.git"
},
Efetuar a autenticação no repositório de destino
Para realizar operações autenticadas no registro do GitHub Packages em seu fluxo de trabalho, você pode usar o GITHUB_TOKEN
. O segredo GITHUB_TOKEN
é definido como um token de acesso para o repositório sempre que um trabalho em um fluxo de trabalho é iniciado. Você deve definir as permissões desse token de acesso no arquivo de fluxo de trabalho para permitir acesso de leitura à permissão contents
e acesso de gravação à permissão packages
. Para obter mais informações, confira "Autenticação automática de token".
Se quiser publicar seu pacote em um repositório diferente, você deverá usar um personal access token (classic) que tenha permissão para gravar em pacotes do repositório de destino. Para obter mais informações, confira "Gerenciar seus tokens de acesso pessoal" e "Usar segredos em ações do GitHub."
Fluxo de trabalho de exemplo
Este exemplo armazena o segredo GITHUB_TOKEN
na variável de ambiente NODE_AUTH_TOKEN
. Quando a ação setup-node
cria um arquivo .npmrc
, ele faz referência ao token da variável de ambiente NODE_AUTH_TOKEN
.
name: Publish package to GitHub Packages on: release: types: [published] jobs: build: runs-on: ubuntu-latest permissions: contents: read packages: write steps: - uses: actions/checkout@v4 # Setup .npmrc file to publish to GitHub Packages - uses: actions/setup-node@v4 with: node-version: '20.x' registry-url: 'https://npm.pkg.github.com' # Defaults to the user or organization that owns the workflow file scope: '@octocat' - run: npm ci - run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
name: Publish package to GitHub Packages
on:
release:
types: [published]
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
# Setup .npmrc file to publish to GitHub Packages
- uses: actions/setup-node@v4
with:
node-version: '20.x'
registry-url: 'https://npm.pkg.github.com'
# Defaults to the user or organization that owns the workflow file
scope: '@octocat'
- run: npm ci
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
A ação setup-node
cria um arquivo .npmrc
no executor. Quando você usa a entrada scope
para a ação setup-node
, o arquivo .npmrc
inclui o prefixo de escopo. Por padrão, a ação setup-node
define o escopo no arquivo .npmrc
para a conta que contém esse arquivo de fluxo de trabalho.
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://npm.pkg.github.com
always-auth=true
Publicar pacotes usando o Yarn
Se você usar o gerenciador de pacotes Yarn, você poderá instalar e publicar pacotes usando o Yarn.
name: Publish Package to npmjs on: release: types: [published] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 # Setup .npmrc file to publish to npm - uses: actions/setup-node@v4 with: node-version: '20.x' registry-url: 'https://registry.npmjs.org' # Defaults to the user or organization that owns the workflow file scope: '@octocat' - run: yarn - run: yarn npm publish // for Yarn version 1, use `yarn publish` instead env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
name: Publish Package to npmjs
on:
release:
types: [published]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Setup .npmrc file to publish to npm
- uses: actions/setup-node@v4
with:
node-version: '20.x'
registry-url: 'https://registry.npmjs.org'
# Defaults to the user or organization that owns the workflow file
scope: '@octocat'
- run: yarn
- run: yarn npm publish // for Yarn version 1, use `yarn publish` instead
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
Para autenticar com o registro durante a publicação, verifique se o token de autenticação também está definido no arquivo yarnrc.yml
. Para obter mais informações, confira o artigo Configurações na documentação do Yarn.