Extensión de VS Code: crear CI/CD automático con GitHub Actions

Hablemos de cómo crear un pipeline de CI/CD completo para una extensión de VS Code con GitHub Actions.

Mi requisito básico era crear un CI/CD automático que me permitiera hacer lo siguiente al enviar un nuevo commit a la rama master:

• Probar: ejecutar las pruebas en Mac, Windows y Linux.

• Lanzar: crear una nueva versión de GitHub con notas de lanzamiento automáticas basadas en las convenciones de mensajes de commit de Angular.

• Publicar: publicar la nueva versión en el marketplace de Visual Studio.

Una última cosa: quería hacer todo esto únicamente con GitHub Actions :) Así que solo necesito el repositorio de GitHub para configurar y ejecutar todo.

Motivación

Todo comenzó cuando quise escribir una pequeña extensión de VS Code que me permitiera hacer clic derecho en un archivo YAML y aplicarlo a mi clúster local de Kubernetes o eliminarlo.

Muy pronto me di cuenta de que la documentación de VS Code sobre cómo escribir una extensión es muy buena. En poco tiempo ya estaba escribiendo y depurando localmente mi nueva extensión de TypeScript, pero entonces noté que el CI/CD completo que Microsoft recomienda en su documentación se queda un poco corto:

Pruebas

Esta parte está bastante bien en la documentación oficial: mencionan específicamente una Action de GitHub que ejecuta las pruebas en Mac, Windows y Linux, y sin duda la usé.

Lanzamiento y publicación

Todo el proceso de lanzamiento y publicación se basa en la herramienta vsce. Para preparar todo, primero debes seguir la documentación de publicación y, en especial, hacer lo siguiente:

• obtener un token de acceso personal de Azure DevOps

• crear un publisher (el nombre del publisher debe coincidir con la sección publisher en package.json)

Una vez que tengas todo eso, puedes empaquetar, publicar y dejar de publicar tu extensión con vsce. Son pasos manuales que hay que realizar; ¡no es lo ideal!

Además, hay una brecha en la forma de definir la versión de la extensión al publicarla. Hay varias maneras de hacerlo:

• cambiar el campo version en package.json y ejecutar vsce publish

• usar vsce publish minor, por ejemplo (o major/patch, según corresponda), para incrementar la versión automáticamente

• usar vsce publish 2.0.1 para indicar una versión específica

Esto no es muy práctico. Quiero que la versión se defina automáticamente según mis convenciones de commits, con la generación automática de notas de lanzamiento. Spoiler: para eso usaré semantic-release. :)

¡Empecemos! Seguiré los pasos que hice y construiremos nuestro pipeline de CI/CD paso a paso.

Crear una extensión

Seguí la documentación oficial y creé con bastante facilidad un nuevo repositorio con mi nueva extensión de TypeScript basada en una plantilla. Después modifiqué la funcionalidad para que, al hacer clic derecho en un archivo YAML, puedas aplicarlo a mi clúster local de Kubernetes o eliminarlo. ¡Muy genial y útil para mí!

Crear un flujo de trabajo vacío de GitHub Actions

Crea un archivo yaml vacío en .github/workflows/<workflow name>.yaml. Lo llamé ci.yaml.

Indicar que el flujo de trabajo debe ejecutarse al hacer push a master

Modifica tu flujo de trabajo yaml para que quede así:

on:
  push:
    branches:
      - master

jobs:
< to be filled with jobs>

El párrafo superior le indica a GitHub que ejecute esa acción cuando se haga un push a master. La parte inferior contiene los trabajos que deben ejecutarse (los completaremos pronto).

Pruebas automáticas

Como mencioné antes, quiero que las pruebas se ejecuten en Mac, Windows y Linux. La documentación menciona una acción específica que usaré ahora al agregar un trabajo 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 puedes ver, esto agrega un trabajo llamado Test, que se ejecutará en Mac, Windows y Ubuntu. Este trabajo contiene 4 pasos:

• Checkout: usar la acción integrada para obtener una copia del repositorio

• Configurar Node.js: usar la acción integrada para configurar Node 12

• Instalar dependencias: ejecutar npm install

• Ejecutar prueba sin interfaz gráfica: ejecutar las pruebas con la acción GabrielBB/xvfb-action@v1.0, recomendada por la documentación oficial (con algunas mejoras)

Después de este paso, vi lo siguiente en la pestaña Actions:

donde cada prueba tenía los siguientes pasos:

Publicación y lanzamiento

Agreguemos un nuevo paso, que se ve así:

  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 

¡Iremos paso a paso, no te preocupes!

Empezamos con los pasos anteriores: obtener el código, configurar Node 12 y ejecutar npm install. Los siguientes dos pasos son los más importantes y merecen sus propias secciones.

Lanzamiento

El objetivo es crear y publicar una nueva versión de GitHub con las notas de lanzamiento adecuadas. Para hacerlo, simplemente ejecuto semantic-release :) Esta acción revisa los mensajes de commit, crea las notas de lanzamiento y publica una nueva versión de GitHub con una versión semver correspondiente a los commits que agregué. También define esa versión en package.json, un dato útil para la siguiente fase.

Para configurar correctamente semantic-release, debes:

• pasar la variable de entorno GITHUB_TOKEN (como secreto de GitHub): tu token personal de GitHub, con los permisos mínimos de repo
  

  

• pasar la variable de entorno NPM_TOKEN (como secreto de GitHub): tu token de npm para lanzar tu paquete npm. En mi caso, no quería lanzar un paquete npm. Para eso, debes configurar "private": true en tu package.json. Una vez hecho esto, no tienes que pasar esta variable de entorno (encontré este dato aquí)

• instalar @semantic-release/github como dependencia de desarrollo

• configurar lo siguiente en tu package.json:

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

Una vez completado este paso, pude empezar a ver las versiones de GitHub correctamente:

Publicar

El objetivo es subir una nueva versión de la extensión al marketplace de VS Code con la versión correcta. Una de las ventajas de la sección Lanzamiento anterior es que package.json ahora contiene la versión correcta del paquete. Lo único que debo hacer es ejecutar vsce publish -p <my token>.

Encontré una acción de GitHub existente para lanzar un plugin: JCofman/vscodeaction. Solo tienes que pasar tu PUBLISHER_TOKEN como variable de entorno (de nuevo, usando los secretos de GitHub).

Después de este paso, verás un nuevo trabajo Release and publish en la pestaña Actions, que contiene

Resultado

Ya puedes encontrar mi nueva extensión en el marketplace y en la búsqueda de extensiones de VS Code.

Puedes encontrar mi repositorio en https://github.com/shaimendel/vscode-plugin-cicd-github-actions, con el flujo de trabajo configurado en [ci.yaml].

Resumen

Acabamos de crear un CI/CD totalmente automático para una nueva extensión de VS Code. Cada vez que se fusiona un PR nuevo en master:

• se prueba el código en varios sistemas operativos

• se lanza una nueva versión de GitHub con excelentes notas de lanzamiento

• se publica una nueva extensión en el marketplace

¡Hicimos todo esto exclusivamente con GitHub Actions! Todo un éxito. :)