Criar e testar Node.js

Introdução

Este guia mostra como criar um fluxo de trabalho de integração contínua (CI) que cria e testa o código Node.js. Se o seu teste de CI for aprovado, é possível que você deseje publicar seu código ou um pacote.

Pré-requisitos

Recomendamos que você tenha um entendimento básico do Node.js, YAML, 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, consulte:

• "Aprenda GitHub Actions"
• "Começar com Node.js"

Usar executores auto-hospedados no GitHub Enterprise Server

Ao usar ações de configuração (como actions/setup-LANGUAGE) em GitHub Enterprise Server com executores auto-hospedados, você pode precisar configurar o armazenamento de ferramentas em executores que não possuem acesso à internet. Para obter mais informações, consulte "Configurar o cache da ferramenta em executores auto-hospedados sem acesso à internet".

Introdução com o modelo de workflow do Node.js

O GitHub fornece um modelo de fluxo de trabalho do Node.js que funcionará para a maioria dos projetos Node.js. Esse guia inclui exemplos de npm e Yarn que você pode usar para personalizar o modelo. Para obter mais informações, consulte o modelo do fluxo de trabalho do Node.js.

Para iniciar rapidamente, adicione o modelo ao diretório .github/workflows do repositório. O fluxo de trabalho mostrado abaixo pressupõe que o branch padrão para o seu repositório é principal.

name: Node.js CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [10.x, 12.x, 14.x, 15.x]

    steps:
      - uses: actions/checkout@v2
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

Executando em um sistema operacional diferente

O modelo de fluxo de trabalho inicial configura trabalhos para executar no Linux, usando o GitHub-executores hospedados ubuntu-latest. Você pode alterar a tecla runs-on para executar seus trabalhos em um sistema operacional diferente. Por exemplo, você pode usar os GitHub-executores Windows hospedados.

runs-on: windows-latest

Ou, você pode executar nos GitHub-executores do macOS.

runs-on: macos-latest

Você também pode executar tarefas em contêineres Docker, ou você pode fornecer um executor auto-hospedado que funciona na sua própria infraestrutura. Para obter mais informações, consulte "Workflow syntax for GitHub Actions."

Especificar a versão do Node.js

A maneira mais fácil de especificar uma versão do Node.js é usar a ação setup-node fornecida pelo GitHub. Para obter mais informações, consulte setup-node.

A ação setup-node considera uma versão do Node.js como uma entrada e configura essa versão no executor. A ação setup-node localiza uma versão específica do Node.js da cache das ferramentas em casa executor e adiciona os binários necessários ao PATH, que persiste no resto do trabalho. Usar a ação setup-node é a forma recomendada de usar o Node.js com GitHub Actions, pois garante um comportamento consistente nos diferentes executores e nas diferentes versões do Node.js. Se você estiver usando um executor auto-hospedado, você deverá instalar o Node.js e adicioná-lo ao PATH.

O modelo inclui uma estratégia matriz que cria e testa seu código com quatro versões de Node.js: 10.x, 12.x, 14.x e 15.x. O "x" é um caractere curinga que corresponde à última versão menor e à versão do patch disponível para uma versão. Cada versão do Node.js especificada na matriz node-version cria uma tarefa que executa as mesmas etapas.

Cada trabalho pode acessar o valor definido na matriz node-version usando o contexto matriz. A ação setup-node usa o contexto como entrada de node-version. A ação setup-node configura cada tarefa com uma versão diferente de Node.js antes de criar e testar o código. Para obter mais informações sobre estratégias e contextos de matriz, consulte "Sintaxe do Fluxo de trabalho para GitHub Actions" e "Contextos".

strategy:
  matrix:
    node-version: [10.x, 12.x, 14.x, 15.x]

steps:
- uses: actions/checkout@v2
- name: Use Node.js ${{ matrix.node-version }}
  uses: actions/setup-node@v2
  with:
    node-version: ${{ matrix.node-version }}

Como alternativa, você pode criar e fazes testes com versões exatas do Node.js.

estratégia:
  matriz:
    node-version: [8.16.2, 10.17.0]

Você também pode criar e testar usando uma versão única do Node.js.

name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
      - name: Use Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '12.x'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

Se você não especificar uma versão do Node.js, o GitHub usará a versão-padrão do Node.js do ambiente. Para obter mais informações, consulte "Especificações para executores hospedados em GitHub".

Instalar dependências

Executores hospedados em GitHub têm gerenciadores de dependências npm e Yarn instalados. Você pode usar o npm e o Yarn para instalar dependências no seu fluxo de trabalho antes de criar e testar seu código. Os executores do Windows e Linux hospedados em GitHub também têm o Grunt, Gulp, e Bower instalado.

Ao usar executores hospedados em GitHub, você também poderá armazenar em cache dependências para acelerar seu fluxo de trabalho. Para obter mais informações, consulte "Memorizar dependências para acelerar fluxos de trabalho".

Exemplo de uso do npm

Este exemplo instala as dependências definidas no arquivo package.json. Para obter mais informações, consulte instalação do npm.

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v2
  with:
    node-version: '12.x'
- name: Install dependencies
  run: npm install

O uso do npm ci instala as versões no arquivo package-lock.json ou npm-shrinkwrap.json e impede as atualizações do arquivo de bloqueio. Usar npm ci geralmente é mais rápido que executar a instalação do npm. Para obter mais informações, consulte npm ci e "Introduzindo npm para criações mais rápidas e confiáveis".

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v2
  with:
    node-version: '12.x'
- name: Install dependencies
  run: npm ci

Exemplo de uso do Yarn

Este exemplo instala as dependências definidas no arquivo package.json. Para obter mais informações, consulte instalação do yarn.

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v2
  with:
    node-version: '12.x'
- name: Install dependencies
  run: yarn

Como alternativa, você pode aprovar o --frozen-lockfile para instalar as versões no arquivo yarn.lock e impedir atualizações no arquivo yarn.lock.

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v2
  with:
    node-version: '12.x'
- name: Install dependencies
  run: yarn --frozen-lockfile

Exemplo do uso de um registro privado e de criação o arquivo .npmrc

Você pode usar a ação setup-node para criar um arquivo local .npmrc no executor que configura o escopo e registro padrão. A ação setup-node também aceita um token de autenticação como entrada, usada para acessar registros privados ou publicar pacotes de nós. Para obter mais informações, consulte setup-node.

Para efetuar a autenticação com seu registro privado, você precisará armazenar seu token de autenticação npm como um segredo. Por exemplo, crie um repositório secreto denominado NPM_TOKEN. Para obter mais informações, consulte "Criando e usando segredos encriptados".

No exemplo abaixo, o segredo NPM_TOKEN armazena o token de autenticação npm. A ação setup-node configura o arquivo .npmrc para ler o token de autenticação npm a partir da variável de ambiente NODE_AUTH_TOKEN. Ao usar a ação setup-node para criar um arquivo .npmrc, você deverá definir a variável de ambiente NODE_AUTH_TOKEN com o segredo que contém seu token de autenticação npm.

Antes de instalar as dependências, use a ação setup-node para criar o arquivo .npmrc file. A ação tem dois parâmetros de entrada. O parâmetro node-version define a versão do Node.js e o parâmetro registry-url define o registro-padrão. Se o registro do seu pacote usar escopos, você deverá usar o parâmetro escopo. Para obter mais informações, consulte npm-scope.

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v2
  with:
    always-auth: true
    node-version: '12.x'
    registry-url: https://registry.npmjs.org
    scope: '@octocat'
- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

O exemplo acima cria um arquivo .npmrc com o conteúdo a seguir:

//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://registry.npmjs.org/
always-auth=true

Exemplo de memorização de dependências

Ao usar executores hospedados em GitHub, você pode armazenar em cache e restaurar as dependências usando a ação setup-node.

O exemplo a seguir armazena dependências do npm.

steps:
- uses: actions/checkout@v2
- uses: actions/setup-node@v2
  with:
    node-version: '14'
    cache: 'npm'
- run: npm install
- run: npm test

O exemplo a seguir armazena dependências para o Yarn.

steps:
- uses: actions/checkout@v2
- uses: actions/setup-node@v2
  with:
    node-version: '14'
    cache: 'yarn'
- run: yarn
- run: yarn test

O exemplo a seguir armazena dependências para pnpm (v6.10+).

# This workflow uses actions that are not certified by GitHub.
# São fornecidas por terceiros e regidas por
# termos de serviço, política de privacidade e suporte separados
# documentação.

# NOTE: pnpm caching support requires pnpm version >= 6.10.0

steps:
- uses: actions/checkout@v2
- uses: pnpm/action-setup@646cdf48217256a3d0b80361c5a50727664284f2
  with:
    version: 6.10.0
- uses: actions/setup-node@v2
  with:
    node-version: '14'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

Para armazenar dependências de cache, você deve ter um pacote-lock.json, yarn.lock ou um arquivo pnpm-lock.yaml na raiz do repositório. Se você precisar de uma personalização mais flexível, você poderá usar a ação cache. Para obter mais informações, consulte "Dependências de cache para acelerar fluxos de trabalho".

Criar e testar seu código

Você pode usar os mesmos comandos usados localmente para criar e testar seu código. Por exemplo, se você executar criação da execução do npm para executar os passos de compilação definidos no seu arquivo package.json e o teste do npm para executar seu conjunto de testes, você adicionaria esses comandos no seu arquivo de fluxo de trabalho.

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v2
  with:
    node-version: '12.x'
- run: npm install
- run: npm run build --if-present
- run: npm test

Empacotar dados do fluxo de trabalho como artefatos

Você pode salvar artefatos das suas etapas de criação e teste para serem visualizados após a conclusão de um trabalho. Por exemplo, é possível que você precise salvar os arquivos de registro, os despejos de núcleo, os resultados de teste ou capturas de tela. Para obter mais informações, consulte "Dados recorrentes do fluxo de trabalho que usam artefatos".

Publicar nos registros do pacote

Você pode configurar o seu fluxo de trabalho para publicar o seu pacote Node.js em um pacote de registro após os seus testes de CI serem aprovados. Para obter mais informações sobre a publicação no npm e em GitHub Package Registry, consulte "Publicando pacotes do Node.js".