Extensão do VS Code: criando CI/CD automático com GitHub Actions

Vamos falar sobre como criar um pipeline de CI/CD completo para uma extensão do VS Code usando o GitHub Actions.

Meu requisito básico era criar um CI/CD automático que me permitisse fazer o seguinte sempre que eu enviasse um novo commit para a branch master:

• Testar: executar os testes no Mac, Windows e Linux.

• Lançar: criar uma nova versão no GitHub com notas de lançamento geradas automaticamente com base nas convenções de mensagens de commit do Angular.

• Publicar: publicar a nova versão no marketplace do Visual Studio.

Só mais uma coisa: eu queria fazer tudo isso usando apenas o GitHub Actions :) Ou seja, preciso somente do repositório do GitHub para configurar e executar tudo.

Motivação

Tudo começou quando quis criar uma pequena extensão do VS Code que me permitisse clicar com o botão direito em um arquivo Yaml e aplicá-lo ao meu cluster local do Kubernetes ou removê-lo dele.

Logo percebi que a documentação do VS Code sobre como criar uma extensão é muito boa: em pouco tempo, eu já estava criando e depurando localmente minha nova extensão em Typescript. Mas então me dei conta de que o CI/CD completo sugerido pela Microsoft na documentação deixa um pouco a desejar:

Testes

Essa parte é relativamente boa na documentação oficial: ela menciona especificamente uma Action do GitHub que executa os testes no Mac, Windows e Linux, e foi exatamente o que usei.

Lançamento e publicação

Todo o processo de lançamento e publicação é baseado na ferramenta vsce. Para começar, siga a documentação de publicação e, em especial, faça o seguinte:

• obtenha um token de acesso pessoal do Azure DevOps

• crie um publisher (o nome do publisher precisa corresponder à seção publisher em package.json)

Depois de fazer tudo isso, você pode empacotar, publicar e retirar a publicação da sua extensão usando o vsce. São etapas manuais que precisam ser realizadas — nada ideal!

Além disso, há uma lacuna na forma como a versão da extensão é definida durante a publicação. Existem algumas maneiras de fazer isso:

• alterar o campo version em package.json e executar vsce publish

• usar vsce publish minor, por exemplo (ou major/patch, conforme necessário), para incrementar a versão automaticamente

• usar vsce publish 2.0.1 para especificar uma versão

Isso não é nada prático. Quero que a versão seja definida automaticamente de acordo com minhas convenções de commit, com geração automática das notas de lançamento. Spoiler: vou usar o semantic-release para isso. :)

Vamos começar! Vou seguir as etapas que percorri para criar nosso pipeline de CI/CD, passo a passo.

Crie uma extensão

Segui a documentação oficial e criei com relativa facilidade um novo repositório com minha extensão Typescript recém-gerada a partir de um modelo. Depois, ajustei a funcionalidade para que, ao clicar com o botão direito em um arquivo YAML, fosse possível aplicá-lo ao meu cluster local do Kubernetes ou removê-lo dele. Muito legal e útil para mim!

Crie um workflow vazio do GitHub Actions

Crie um arquivo yaml vazio em .github/workflows/<workflow name>.yaml. Dei a ele o nome ci.yaml.

Indique que o workflow deve ser executado quando houver um push para master

Altere seu workflow yaml para que fique assim:

on:
  push:
    branches:
      - master

jobs:
< to be filled with jobs>

O parágrafo superior instrui o GitHub a executar essa Action quando houver um push para master. A parte inferior contém os jobs que devem ser executados (vamos preenchê-los em breve).

Testes automáticos

Como mencionei acima, quero que os testes sejam executados no Mac, Windows e Linux. A documentação também menciona uma Action específica que vou usar agora, adicionando um job dedicado:

  test:
    name: Test
    strategy:
      matrix:
        os: [macos-latest, ubuntu-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 12
      - name: Install dependencies
        run: npm install
      - name: Run headless test
        uses: GabrielBB/xvfb-action@v1.0
        with:
          run: npm test

Como você pode ver, isso adiciona um job chamado Test, que será executado no Mac, Windows e Ubuntu. Esse job tem quatro etapas:

• Checkout: usa a Action integrada para fazer checkout do repositório

• Configurar Node.js: usa a Action integrada para configurar o Node 12

• Instalar dependências: executa npm install

• Executar teste headless: executa os testes usando a Action GabrielBB/xvfb-action@v1.0, conforme recomendado pela documentação oficial (com algumas melhorias)

Depois dessa etapa, vi o seguinte na aba Actions:

em que cada teste tinha as seguintes etapas:

Publicação e lançamento

Vamos adicionar uma nova etapa, que ficará assim:

  publish:
    name: Release and publish
    needs: test
    runs-on: ubuntu-18.04
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 12
      - name: Install dependencies
        run: npm install
      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.PERSONAL_GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release
      - name: Vscode release plugin
        uses: JCofman/vscodeaction@master
        env:
          PUBLISHER_TOKEN: ${{ secrets.PUBLISHER_TOKEN }}
        with:
          args: publish -p $PUBLISHER_TOKEN 

Vamos por partes, sem preocupação!

Começamos com as etapas anteriores: fazer checkout do código, configurar o Node 12 e executar npm install. As duas próximas etapas são as mais importantes e merecem seções próprias.

Lançamento

O objetivo aqui é criar e publicar uma nova versão no GitHub com notas de lançamento adequadas. Para isso, basta executar semantic-release :) Essa Action analisa as mensagens de commit, cria as notas de lançamento e publica uma nova versão no GitHub com uma versão semver correspondente aos commits que adicionei. Ela também atualiza essa versão em package.json, o que será útil na próxima etapa.

Para configurar corretamente o semantic-release, você precisa:

• passar a variável de ambiente GITHUB_TOKEN (como um segredo do GitHub): seu token pessoal do GitHub, com permissões mínimas de repo
  

  

• passar a variável de ambiente NPM_TOKEN (como um segredo do GitHub): seu token do npm para publicar seu pacote npm. No meu caso, eu não queria publicar um pacote npm. Para isso, configure "private": true em package.json. Depois, não será necessário passar essa variável de ambiente (encontrei essa informação aqui)

• instalar @semantic-release/github como dependência de desenvolvimento

• configurar o seguinte em seu package.json:

  "release": {"branches": "master","verifyConditions": ,"publish": ,"success": ,"fail": },

Depois de concluir essa etapa, comecei a ver versões do GitHub criadas corretamente:

Publicação

O objetivo aqui é enviar uma nova versão da extensão para o marketplace do VS Code com a versão correta. Uma das vantagens da seção Lançamento anterior é que package.json agora contém a versão correta do pacote. Tudo o que preciso fazer é executar vsce publish -p <my token>.

Encontrei uma Action existente do GitHub para lançar um plugin, JCofman/vscodeaction. Basta passar seu PUBLISHER_TOKEN como variável de ambiente (usando novamente os segredos do GitHub).

Depois dessa etapa, você verá um novo job Release and publish na aba Actions, que contém

Resultado

Agora você pode encontrar minha nova extensão no marketplace e na busca de extensões do VS Code!

Você encontra meu repositório em https://github.com/shaimendel/vscode-plugin-cicd-github-actions, com o workflow configurado em [ci.yaml].

Resumo

Acabamos de criar um CI/CD totalmente automático para uma nova extensão do VS Code. Sempre que um novo PR for integrado à branch master, nós:

• testamos o código em vários sistemas operacionais

• criamos uma nova versão no GitHub com notas de lançamento excelentes

• publicamos uma nova extensão no marketplace

Fizemos tudo isso usando apenas o GitHub Actions! Sucesso total. :)