Befehlszeile mit Clasp verwenden

Wenn Sie Google Apps Script-Projekte lieber über das Terminal als über den Apps Script-Editor entwickeln und verwalten möchten, verwenden Sie das Open-Source-Tool clasp.

Im clasp Codelab finden Sie eine Übersicht über alle clasp Funktionen.

Funktionen

clasp umfasst die folgenden Funktionen:

Lokal entwickeln

Mit clasp können Sie Ihre Apps Script-Projekte lokal entwickeln. Schreiben Sie Code auf Ihrem eigenen Computer und laden Sie ihn anschließend in Apps Script hoch. Sie können auch vorhandene Apps Script-Projekte herunterladen, um sie offline zu bearbeiten. Verwenden Sie Ihre bevorzugten Entwicklungstools wie git wenn Sie Apps Script Projekte erstellen.

Bereitstellungsversionen verwalten

Sie können mehrere Bereitstellungen Ihres Projekts erstellen, aktualisieren und aufrufen.

Code strukturieren

Mit clasp können Sie Ihren Code in Verzeichnissen organisieren, die beim Hochladen auf script.google.com beibehalten werden. Beispiel:

# On script.google.com:
├── tests/slides.gs
└── tests/sheets.gs

# Locally:
├── tests/
│   ├─ slides.gs
│   └─ sheets.gs

Projekttypen

Mit clasp können Sie sowohl eigenständige als auch containergebundene Skriptprojekte verwalten.

Eigenständige Projekte

Ein eigenständiges Projekt wird als separate Datei in Google Drive angezeigt. Mit dem Befehl clasp create können Sie ein neues eigenständiges Skript erstellen.

Containergebundene Projekte

Ein containergebundenes Projekt ist an eine Google Docs-, Google Sheets-, Google Präsentationen- oder Google Formulare -Datei angehängt. Mit dem Befehl clasp create können Sie ein neues containergebundenes Skript erstellen, das an eine neue Datei angehängt ist. Mit dem Flag --parentId können Sie auch ein neues Skript an eine vorhandene Datei anhängen.

Andere Projekttypen

clasp unterstützt auch das Erstellen von Skripts für Webanwendungen und APIs.

Voraussetzungen

clasp ist in Node.js geschrieben und wird mit dem npm Tool verteilt. Bevor Sie clasp verwenden können, muss Node.js Version 20.0.0 oder höher installiert sein. Für die Installation von Node.js sind Administratorberechtigungen erforderlich.

Installation

Nachdem Sie Node.js installiert haben, verwenden Sie den folgenden npm-Befehl, um clasp zu installieren:

npm install @google/clasp -g

Nach der Installation können Sie den Befehl clasp in einem beliebigen Verzeichnis auf Ihrem Computer verwenden.

clasp verwenden

Mit clasp können Sie eine Vielzahl von Aufgaben über die Befehlszeile ausführen. In diesem Abschnitt werden häufige Vorgänge beschrieben, die Sie bei der Entwicklung mit clasp verwenden können.

Anmelden

Mit diesem Befehl melden Sie sich an und autorisieren die Verwaltung der Apps Script-Projekte Ihres Google-Kontos. Nach der Ausführung werden Sie aufgefordert, sich in einem Google-Konto anzumelden, in dem Ihre Apps Script-Projekte gespeichert sind.

clasp login

Abmelden

Mit diesem Befehl melden Sie sich vom Befehlszeilentool ab. Melden Sie sich mit clasp login noch einmal an, um sich bei Google neu zu authentifizieren, bevor Sie clasp weiter verwenden.

clasp logout

Neues Apps Script-Projekt erstellen

Mit diesem Befehl wird im aktuellen Verzeichnis ein neues Skript mit einem optionalen Skripttitel erstellt.

clasp create [scriptTitle] [--type <projectType>] [--parentId <parentId>]

Dieser Befehl verwendet die folgenden optionalen Parameter:

• scriptTitle: Der Titel des Skriptprojekts.
• --type <projectType>: Der Typ des zu erstellenden Projekts. Zulässige Werte sind standalone, docs, sheets, slides, forms, webapp und api.
• --parentId <parentId>: Die ID der vorhandenen Google Drive-Datei (Google Docs, Google Sheets, Google Präsentationen oder Google Formulare), an die das neue Skriptprojekt gebunden werden soll.

Mit diesem Befehl werden auch zwei Dateien im aktuellen Verzeichnis erstellt:

• Eine .clasp.json-Datei, in der die Skript-ID gespeichert ist.
• Eine appsscript.json-Projektmanifestdatei mit Projektmetadaten.

Vorhandenes Projekt klonen

Mit diesem Befehl wird ein vorhandenes Projekt im aktuellen Verzeichnis geklont. Das Skript muss mit Ihrem Google-Konto erstellt oder für dieses freigegeben worden sein. Sie geben das zu klonende Skript projekt an, indem Sie die Skript-ID angeben. Sie können sowohl eigenständige als auch containergebundene Projekte klonen.

So finden Sie die Skript-ID des Projekts:

1. Öffnen Sie das Apps Script-Projekt.
2. Klicken Sie links auf die Projekteinstellungen settings.

3. Kopieren Sie unter IDs die Skript-ID.

   clasp clone

Skriptprojekt herunterladen

Mit diesem Befehl wird das Apps Script-Projekt von Google Drive in das Dateisystem Ihres Computers heruntergeladen.

clasp pull

Skriptprojekt hochladen

Mit diesem Befehl werden alle Dateien eines Skriptprojekts von Ihrem Computer in Drive hochgeladen.

clasp push

Projektversionen auflisten

Mit diesem Befehl werden die Nummer und die Beschreibung der einzelnen Versionen eines Skriptprojekts aufgelistet.

clasp versions

Veröffentlichtes Projekt bereitstellen

Sie können Skriptprojekte als Webanwendungen, Google Workspace-Add-ons oder ausführbare Dateien bereitstellen. Erstellen Sie Bereitstellungen im Script-Editor, im Projekt Manifest, oder mit clasp.

Wenn Sie ein Projekt mit clasp bereitstellen möchten, erstellen Sie zuerst eine unveränderliche Version des Apps Script-Projekts. Eine Version ist eine „Momentaufnahme“ eines Skriptprojekts und ähnelt einer schreibgeschützten verzweigten Version.

clasp version [description]

Mit diesem Befehl wird die neu erstellte Versionsnummer angezeigt. Mit dieser Nummer können Sie Instanzen Ihres Projekts bereitstellen und die Bereitstellung aufheben:

clasp deploy [version] [description]
clasp undeploy <deploymentId>

Mit diesem Befehl wird eine vorhandene Bereitstellung mit einer neuen Version und Beschreibung aktualisiert:

clasp redeploy <deploymentId> <version> <description>

Deployments auflisten

Mit diesem Befehl werden die Bereitstellungs-IDs, Versionen und Beschreibungen des Skriptprojekts aufgelistet.

clasp deployments

Projekt im Apps Script-Editor öffnen

Mit diesem Befehl wird ein Skriptprojekt im Apps Script-Editor geöffnet. Der Editor wird als neuer Tab in Ihrem Standardwebbrowser gestartet.

clasp open-script

Zum Open-Source-Projekt clasp beitragen

Sie können auf GitHub zu clasp beitragen.

CI/CD für Apps Script mit clasp und GitHub Actions

In dieser Anleitung wird beschrieben, wie Sie die automatisierte Linting-, Test- und Bereitstellung für Google Apps Script-Projekte mit clasp und GitHub Actions einrichten.

1. Vorbereitung

Führen Sie zuerst die Einrichtungsschritte unter Voraussetzungen aus.

Außerdem sind

• Ein GitHub-Repository.
• Die Apps Script API ist unter script.google.com/home/usersettings aktiviert.

2. Authentifizierung in CI

Da CI-Runner keinen Browser für OAuth öffnen können, speichern Sie Anmeldedaten als GitHub-Secrets:

Das Aktualisierungstoken in .clasprc.json gewährt Zugriff auf Ihre Apps Script-Projekte. Behandeln Sie es als vertrauliche Anmeldedaten und rotieren Sie es regelmäßig.

Fügen Sie .clasprc.json und .clasp.json zu Ihrer .gitignore-Datei hinzu. Diese Dateien enthalten Anmeldedaten und sollten niemals committet werden.

3. CI-Workflow – Linting und Tests für Pull-Anfragen

.github/workflows/ci.yml:

name: CI
on:
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6.3
      - uses: actions/setup-node@v6.3
        with:
          node-version: "20"
          cache: npm
      - run: npm ci
      - run: npm run lint

4. CD-Workflow – Bereitstellung beim Zusammenführen

.github/workflows/deploy.yml:

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: npm
      - run: npm ci
      - run: npm run lint && npm test
      - name: Setup clasp credentials
        run: |

          echo '${{ secrets.CLASPRC_JSON }}' > ~/.clasprc.json
          echo '${{ secrets.CLASP_JSON }}' > .clasp.json

      - name: Push and version
        run: |
          npx @google/clasp push --force
          npx @google/clasp version "$(git rev-parse --short HEAD)"

Mit dem Flag --force wird der Remote-Code ohne Bestätigung überschrieben. Sobald diese Pipeline eingerichtet ist, sollten Sie keine manuellen Änderungen mehr im Apps Script-Editor vornehmen. Das Repository wird zur einzigen Quelle der Wahrheit.

5. Bereitstellung in mehreren Umgebungen

Für separate Entwicklungs-, Staging- und Produktionsumgebungen erstellen Sie für jede Umgebung ein eigenes Apps Script-Projekt und speichern die Konfigurationen als separate Secrets (CLASP_JSON_DEV, CLASP_JSON_STAGING, CLASP_JSON_PROD). Schreiben Sie im Workflow das entsprechende Secret basierend auf dem bereitzustellenden Branch in .clasp.json.

Fehlerbehebung

Weiterführende Literatur

• GitHub Actions-Dokumentation