robertoachar.dev

GitHub Package Registry + GitHub Actions

Como utilizar GitHub Actions para publicar um pacote do npm no GitHub Package Registry.

Foto de Janko Ferlič
  • Introdução
  • O que é GitHub Actions?
  • O que é GitHub Package Registry?
  • Definindo o workflow
  • Criando um workflow para publicar pacotes no GitHub Package Registry usando o GitHub Actions
  • Enviando o workflow para o GitHub
  • Acompanhando a execução do workflow
  • Conclusão
  • Solução de problemas

Introdução

As práticas de Continuous Integration e Continuous Delivery, também conhecidas com CI/CD, tem se tornado cada vez mais presentes no workflow dos desenvolvedores. Essas técnicas consistem em integrar código com mais frequência ao repositório, permitindo que os desenvolvedores descubram erros mais rapidamente, por exemplo. Existe outros benefícios, é claro.

Existem serviços de CI/CD disponíveis na Internet que permitem que os desenvolvedores construam seus workflows de CI/CD. Os mais conhecidos e utilizados são: CircleCI e Travis CI.

Um workflow muito utilizado pelos desenvolvedores JavaScript é utilizar o GitHub para gerenciar o código, CircleCI ou Travis CI para gerenciar o CI/CD e o npm para publicar os pacotes.

O que é GitHub Actions?

GitHub Actions é uma das novas funcionalidades que o GitHub lançou recentemente. A proposta é disponibilizar um serviço de CI/CD dentro do GitHub. 👀

Para utilizar o GitHub Actions é necessário criar um arquivo YAML no diretório .github/workflows. Assim que o arquivo for criado no repositório, o GitHub identifica esse arquivo e executa o workflow.

No workflow podemos configurar a execução de testes, build e deploy, por exemplo.

Essa funcionalidade ainda está em fase beta. Caso você queira se inscrever para participar, acesse a página do GitHub Actions.

O que é GitHub Package Registry?

O GitHub Package Registry é um serviço de hospedagem de pacotes, semelhante ao npm, que permite que você hospede seus códigos e pacotes em um único lugar. Ele suporta pacotes do Node.js, Ruby, Java, .NET e imagens Docker.

Esse tutorial é a continuação do tutorial anterior Como utilizar o GitHub Package Registry com o npm.

Definindo o workflow

Nosso objetivo é simples: publicar um pacote automaticamente sempre que houver uma alteração na branch master. Os passos necessários para isso são:

  • Identificar uma alteração na branch master seja através de push ou Pull Request
  • Executar algumas ações para publicar o pacote

Criando um workflow para publicar pacotes no GitHub Package Registry usando o GitHub Actions

O primeiro passo para criar um workflow no GitHub Actions é criar um arquivo no diretório .github/workflows. O nome do arquivo pode ser qualquer coisa, desde que tenha a extensão .yml. Eu vou utilizar gpr-publish.yml. Eu vou apresentar o arquivo completo e comentar todas as etapas detalhadamente.

name: GPR Publish
on:
pull_request:
branches:
- master
push:
branches:
- master
jobs:
publish-gpr:
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
- uses: actions/setup-[email protected]
with:
node-version: 12
registry-url: https://npm.pkg.github.com/
scope: '@robertoachar'
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

Nome do workflow

Esse é o nome que será exibido no GitHub para identificar o workflow.

name: GPR Publish

Definindo a condição para a execução do workflow

Essa configuração instrui o workflow a ser executado apenas quando houver um Pull Request ou um Push na branch master.

on:
pull_request:
branches:
- master
push:
branches:
- master

Definindo o job

Todo workflow precisa ter pelo menos um job e podemos definir mais de um job por workflow. Nesse caso estamos definindo apenas um job: publish-gpr. Esse job será executado sempre que a condição acima for atendida.

jobs: publish-gpr:

Escolhendo o ambiente de execução

Os workflows podem ser executados em uma máquina virtual ou em um container Docker. Nesse caso iremos executar o workflow em uma máquina virtual com a última versão do sistema operacional Ubuntu.

runs-on: ubuntu-latest

Passos da execução

Um job contém um mais passos a serem executados. Os passos podem ser a execução de comandos ou utilizar uma ação.

steps:

Ação checkout

A ação checkout é uma ação padrão e precisa ser incluída antes das outras ações. Ela é responsável por requisitar uma cópia do código do repositório.

- uses: actions/[email protected]

Ação setup-node

Essa ação é responsável por configurar o Node no ambiente de execução. Solicitamos a instalação da versão 12 do Node.js, informamos qual é a url do registry e informamos qual é o scope (leia nome de usuário ou organização do GitHub).

- uses: actions/setup-[email protected]
with:
node-version: 12
registry-url: https://npm.pkg.github.com/
scope: '@robertoachar'

Publicando o pacote

Informamos ao workflow para executar o comando npm publish e configuramos a variável de ambiente NODE_AUTH_TOKEN com o valor de GITHUB_TOKEN. O GitHub cria GITHUB_TOKEN por padrão, mas precisamos incluí-lo nas configurações para que as ações possam usá-lo.

- run: npm publish
env:
NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

Enviando o workflow para o GitHub

Como o workflow é apenas um arquivo no repositório, para enviar o workflow para o GitHub, basta realizar o commit desse arquivo no repositório. Se esse arquivo for enviado para a branch master através de push ou Pull Request, o job será executado e seu pacote será publicado automaticamente.

Acompanhando a execução do workflow

  1. Acesse a página do seu repositório no GitHub

  2. Clique em Actions

Tela do repositório dando ênfase no link Actions

  1. Visualize todos os workflows disponíveis

Tela do repositório exibindo os workflows

  1. Clique em um workflow para ver os detalhes

Tela do repositório exibindo um workflow específico

  1. Clique em uma etapa para visualizar o log de execução

Tela do repositório exibindo o detalhe de execução de um workflow

Conclusão

O GitHub vem se tornando cada vez mais uma ferramenta indispensável para os desenvolvedores. Essas duas novas funcionalidades, GitHub Actions e GitHub Package Registry, agregam muito valor ao ciclo de desenvolvimento.

Solução de problemas

Recebi o erro EPUBLISHCONFLICT na hora de publicar o pacote

$ npm publish
npm ERR! code EPUBLISHCONFLICT
npm ERR! publish fail Cannot publish over existing version.
npm ERR! publish fail Update the 'version' field in package.json and try again.
npm ERR! publish fail
npm ERR! publish fail To automatically increment version numbers, see:
npm ERR! publish fail npm help version

Solução: você não pode publicar um pacote com a mesma versão que já foi publicada. Altere a versão do seu pacote e tente publicar novamente.