VS-Code-Erweiterung: Automatisierte CI/CD mit GitHub Actions erstellen

Sehen wir uns an, wie Sie mit GitHub Actions eine vollständige CI/CD-Pipeline für eine VS-Code-Erweiterung erstellen.

Meine grundlegende Anforderung war eine automatisierte CI/CD-Pipeline, die beim Push eines neuen Commits in den Branch master Folgendes ermöglicht:

• Testen: Tests auf Mac, Windows und Linux ausführen.

• Veröffentlichen: Ein neues GitHub-Release mit automatischen Release Notes auf Grundlage der Angular Commit Message Conventions erstellen.

• Publizieren: Die neue Version im Marketplace von Visual Studio veröffentlichen.

Noch eine letzte Sache: Ich wollte all das ausschließlich mit GitHub Actions erledigen :) Ich brauche also nur das GitHub-Repository, um alles zu konfigurieren und auszuführen.

Motivation

Alles begann damit, dass ich eine kleine VS-Code-Erweiterung schreiben wollte, mit der ich per Rechtsklick eine YAML-Datei auf meinem lokalen Kubernetes-Cluster anwenden oder löschen kann.

Schon bald stellte ich fest, dass die Dokumentation von VS Code zum Schreiben einer Erweiterung wirklich gut ist. Ich konnte meine neue TypeScript-Erweiterung im Handumdrehen schreiben und lokal debuggen. Dann fiel mir jedoch auf, dass der vollständige CI/CD-Prozess, den Microsoft in der Dokumentation vorschlägt, etwas zu kurz greift:

Tests

Dieser Teil ist in der offiziellen Dokumentation tatsächlich relativ gut beschrieben. Dort wird ausdrücklich eine GitHub-Action erwähnt, die die Tests auf Mac, Windows und Linux ausführt. Ich habe sie natürlich verwendet.

Release und Publikation

Der gesamte Release- und Publikationsprozess basiert auf dem Tool vsce. Um die Grundlagen zu schaffen, müssen Sie zunächst der Dokumentation zur Veröffentlichung folgen und insbesondere Folgendes tun:

• ein persönliches Zugriffstoken abrufen – von Azure DevOps

• einen Publisher erstellen (der Publisher-Name muss dem Abschnitt publisher in package.json entsprechen)

Sobald Sie all das eingerichtet haben, können Sie Ihre Erweiterung mit vsce paketieren, veröffentlichen und zurückziehen. Das sind manuelle Schritte, die erforderlich sind – alles andere als ideal!

Außerdem ist nicht klar geregelt, wie die Version der Erweiterung bei der Veröffentlichung festgelegt wird. Dafür gibt es mehrere Möglichkeiten:

• das Feld version in package.json ändern und vsce publish aufrufen

• beispielsweise vsce publish minor verwenden (oder entsprechend major/patch), um die Version automatisch hochzuzählen

• vsce publish 2.0.1 verwenden, um eine bestimmte Version anzugeben

Das ist wirklich umständlich. Ich möchte, dass die Version automatisch anhand meiner Commit-Konventionen festgelegt wird, inklusive automatischer Erstellung der Release Notes. Spoiler: Dafür verwende ich semantic-release. :)

Legen wir los! Ich führe Sie durch die Schritte, die ich selbst durchlaufen habe, und wir erstellen unsere CI/CD-Pipeline Schritt für Schritt.

Eine Erweiterung erstellen

Ich bin der offiziellen Dokumentation gefolgt und habe relativ einfach ein neues Repository mit meiner frisch generierten TypeScript-Erweiterung erstellt. Anschließend habe ich die Funktionalität so angepasst, dass ich durch einen Rechtsklick auf eine YAML-Datei diese auf meinem lokalen Kubernetes-Cluster anwenden oder dort löschen kann. Richtig cool und für mich sehr nützlich!

Einen leeren GitHub-Actions-Workflow erstellen

Erstellen Sie eine leere YAML-Datei unter .github/workflows/<workflow name>.yaml. Ich habe sie ci.yaml genannt.

Festlegen, dass der Workflow bei einem Push in den Branch master ausgeführt wird

Ändern Sie Ihren YAML-Workflow wie folgt:

on:
  push:
    branches:
      - master

jobs:
< to be filled with jobs>

Der obere Abschnitt weist GitHub an, die Action auszuführen, wenn ein Push in den Branch master erfolgt. Im unteren Abschnitt stehen die auszuführenden Jobs (die wir gleich ergänzen).

Automatisierte Tests

Wie oben erwähnt, möchte ich die Tests auf Mac, Windows und Linux ausführen. In der Dokumentation wird tatsächlich eine bestimmte Action erwähnt, die ich jetzt verwende, indem ich einen eigenen Job hinzufüge:

  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

Wie Sie sehen, wird damit ein Job namens Test hinzugefügt, der auf Mac, Windows und Ubuntu ausgeführt wird. Dieser Job umfasst vier Schritte:

• Checkout: Die integrierte Action verwenden, um das Repository auszuchecken

• Node.js einrichten: Die integrierte Action verwenden, um Node 12 einzurichten

• Abhängigkeiten installieren: npm install ausführen

• Headless-Test ausführen: Die Tests mit der Action GabrielBB/xvfb-action@v1.0 ausführen, wie in der offiziellen Dokumentation empfohlen (mit einigen Verbesserungen)

Nach diesem Schritt habe ich im Tab „Actions“ Folgendes gesehen:

Dabei hatte jeder Test die folgenden Schritte:

Publizieren und Release

Fügen wir einen neuen Schritt hinzu, der wie folgt aussieht:

  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 

Wir gehen das ganz in Ruhe durch, keine Sorge!

Zunächst folgen die vorherigen Schritte: den Code auschecken, Node 12 einrichten und npm install ausführen. Die nächsten beiden Schritte sind besonders wichtig und verdienen jeweils einen eigenen Abschnitt.

Release

Ziel ist es, ein neues GitHub-Release mit passenden Release Notes zu erstellen und zu veröffentlichen. Dazu rufe ich einfach semantic-release auf :) Diese Action geht die Commit-Nachrichten durch, erstellt Release Notes und legt ein neues GitHub-Release mit einer Semver-Version an, die den hinzugefügten Commits entspricht. Außerdem trägt sie diese Release-Version in package.json ein – ein nützlicher Punkt für die nächste Phase.

Um semantic-release korrekt zu konfigurieren, müssen Sie:

• die Umgebungsvariable GITHUB_TOKEN (als GitHub Secret) übergeben: Ihr persönliches GitHub-Token mit den minimal erforderlichen repo-Berechtigungen
  

  

• die Umgebungsvariable NPM_TOKEN (als GitHub Secret) übergeben: Ihr npm-Token zum Veröffentlichen Ihres npm-Pakets. In meinem Fall wollte ich kein npm-Paket veröffentlichen. Dazu müssen Sie "private": true in Ihrer package.json konfigurieren. Danach müssen Sie diese Umgebungsvariable nicht übergeben (diesen Hinweis habe ich hier gefunden).

• @semantic-release/github als Dev-Abhängigkeit installieren

• Folgendes in Ihrer package.json konfigurieren:

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

Nach diesem Schritt wurden die GitHub-Releases korrekt angezeigt:

Publizieren

Ziel ist es, eine neue Version der Erweiterung mit der richtigen Versionsnummer in den VS-Code-Marketplace hochzuladen. Einer der Vorteile des vorherigen Abschnitts „Release“ ist, dass package.json jetzt die richtige Paketversion enthält. Jetzt müssen Sie nur noch vsce publish -p <my token> aufrufen.

Ich habe eine bestehende GitHub Action gefunden, um ein Plugin zu veröffentlichen: JCofman/vscodeaction. Sie müssen lediglich Ihr PUBLISHER_TOKEN als Umgebungsvariable übergeben (wieder mithilfe von GitHub Secrets).

Nach diesem Schritt sehen Sie im Tab „Actions“ einen neuen Job namens Release and publish, der Folgendes enthält:

Ergebnis

Sie finden meine neue Erweiterung jetzt im Marketplace und in der Suche nach VS-Code-Erweiterungen!

Mein Repository finden Sie unter https://github.com/shaimendel/vscode-plugin-cicd-github-actions. Der Workflow ist unter [ci.yaml]. konfiguriert.

Zusammenfassung

Wir haben gerade eine vollständig automatisierte CI/CD-Pipeline für eine neue VS-Code-Erweiterung erstellt. Jedes Mal, wenn ein neuer PR in master gemergt wird, erledigen wir Folgendes:

• den Code auf mehreren Betriebssystemen testen

• ein neues GitHub-Release mit besonders gelungenen Release Notes erstellen

• eine neue Erweiterung im Marketplace veröffentlichen

Das alles haben wir ausschließlich mit GitHub Actions erledigt! Ein voller Erfolg. :)