Dokumentation

Zuerst einmal: Willkommen, und danke, dass Sie Greenkeeper benutzen! Falls Sie nicht finden können, wonach Sie suchen, gibt es auch eine FAQ-Seite, und wenn das auch nicht weiterhilft, können Sie uns direkt kontaktieren.

Übersicht

Wie und warum Greenkeeper funktioniert

Kurz gefasst: Greenkeeper informiert Sie, wenn ein Dependency-Update ihren Code kaputt macht.

Greenkeeper befindet sich zwischen npm und GitHub und überwacht alle Module, von denen Ihr Projekt abhängig ist. Wenn eines aktualisiert wird, öffnet Greenkeeper einen neuen Branch mit diesem Update. Die CI-Tests der Repository starten und Greenkeeper überprüft, ob sie positiv verlaufen oder nicht.

Basierend auf den Testergebnissen und Ihren Versionsdefinitionen öffnet Greenkeeper klare, einfach umzusetzende Pull Requests und Issues in Ihrem Projekt. Wenn alles im grünen Bereich ist, dann macht Greenkeeper nichts. Andernfalls kriegen Sie eine Benachrichtigung: Sie wissen somit sofort, welche Aktualisierung von welchem Modul das Problem verursacht hat, damit Sie es schnell beheben können.

Macht das nicht SemVer? Theoretisch schon, aber nicht zuverlässig. Versionierungsentscheidungen werden immer noch meistens von Menschen getroffen, und Menschen sind manchmal eher irrational. Der einzige Weg, sicher zu gehen, dass Ihre Dependencies Ihr Projekt nicht negativ beeinträchtigen, ist jedes einzelne Update auszuprobieren. Ohne Greenkeeper wäre das sehr zeitraubend und fehleranfällig.

Zum Seitenanfang

Unterschiede zwischen den verschiedenen Plänen

Greenkeeper auf öffentlichen Repositories zu benutzen ist immer kostenlos. Falls Sie vorhaben, es auf privaten Repositories zu installieren, müssen Sie ihre Zahlungsinformationen in dem Account-Dashboard hinzufügen.

Die Preise variieren basierend darauf, auf welchem GitHub-Account Greenkeeper installiert wurde, und für wie viele Repositories es aktiviert ist.

Zum Seitenanfang

Voraussetzungen

Das Repository, auf dem Greenkeeper laufen soll, muss ein paar Anforderungen erfüllen:

Das Repository muss mindestens eine package.json Datei beinhalten
Das Repository muss irgendeine Form von Continuous Integration (CI) haben (z.B. CircleCI, CodeShip oder Travis CI)
Die CI muss auf dem Repository aktiv sein und die Erlaubnis haben, auf einem neuen Branch zu laufen
Issues müssen für das Repository aktiv sein (Achtung: wenn ein Repo ein Fork ist, sind Issues automatisch deaktiviert)
Um Greenkeeper kostenlos nutzen zu können, muss das Repository öffentlich sein

Zum Seitenanfang

Installation

Greenkeeper lässt sich in nur drei Schritten auf einem Repository aktivieren:

Installieren Sie Greenkeeper
Greenkeeper muss nur einmal pro Organisation oder User-Account installiert werden. Danach kann festgelegt werden, auf welche Repos Greenkeeper Zugriff hat.

Sie können Greenkeeper über GitHub Apps installieren. Gehen Sie auf die Greenkeeper-Seite bei GitHub und klicken Sie “Install”. Wenn Sie Greenkeeper bereits irgendwo installiert haben, dann klicken Sie auf “Configure”.

Alternativ können Sie Greenkeeper auch über GitHub Marketplace installieren. In diesem Fall wird die Bezahlung komplett von GitHub abgewickelt, und es gibt eine 14-tägige kostenlose Testphase.
Greenkeeper Zugriff auf Repos erteilen
Gehen Sie auf die Einstellungsseite für Greenkeeper. Die URL zu dieser Seite ist bei jedem Account unterschiedlich. Sie finden sie auf Repository-Ebene in dem Bereich Einstellungen (Integration & services) unter Installed GitHub Apps. Wählen Sie Greenkeeper aus und scrollen Sie zum Abschnitt Repository Access. Hier wählen Sie only selected repositories (wir empfehlen sehr, nicht All repositories auszuwählen) und fügen dann die Repositories hinzu, für die Greenkeeper aktiv sein soll.

Das GitHub-Interface, in dem Sie die Zugriffsrechte von Greenkeeper festlegen können

Einen Link zu diesen Einstellungen finden Sie auch im Account Dashboard am Ende der jeweiligen Repository-Liste
Aktivieren Sie Greenkeeper in den jeweiligen Repositories
Sie aktivieren Greenkeeper in einem Repo, indem sie den initialen Pull Request mergen.

Dieser erste Pull Request hat zum Ziel, alle Abhängigkeiten auf einmal zu aktualisieren, damit Sie auf dem neuesten Stand sind. Zusätzlich wird er das Greenkeeper Badge zur readme.md der Projekts hinzufügen. Beachten Sie, dass Greenkeeper den ersten Pull Request nur senden kann, wenn das Repository alle obigen Voraussetzungen erfüllt.

Wichtig: Greenkeeper wird erst aktiv, nachdem der erste initiale Greenkeeper Pull Request gemerged wurde. Falls dies nicht geschieht, wird Greenkeeper Sie nach einer Weile daran erinnern.

Wichtig: Wenn alle Dependencies auf dem neuesten Stand sind und die readme.md schon einen Greenkeeper Badge hat, dann wird Greenkeeper ohne einen Pull Request aktiviert.

Der Status eines Repositories kann im Greenkeeper Account Dashboard überprüft werden.

Es kann einige Zeit dauern, bis der erste Pull Request gesendet wird. Das hängt davon ab, wie lange es dauert, die einzelnen Abhängigkeiten zu überprüfen und zu testen.

Zum Seitenanfang

Den Status eines Repos überprüfen

Das Greenkeeper Account Dashboard zeigt den Status aller Repositories an die mit Greenkeeper verknüpft sind.

Die Repository-Liste im Account Dashboard

Eine Repo ist rot markiert, wenn der initiale Pull Request (noch) nicht existiert. Wichtig: es kann bis zu 30 Minuten dauern, bis der erste Pull Request erscheint. Falls nach einer halben Stunde noch nichts passiert ist, kann es sein, dass eine oder mehrere Voraussetzungen noch nicht erfüllt worden sind, oder dass Ihr CI einfach noch beschäftigt ist. Falls Sie sich sicher sind, dass alle Voraussetzungen erfüllt sind und ihr CI fertig ist, aber trotzdem kein Pull Request geöffnet wurde, können sie das Repository zurücksetzen.

Es kann in Ausnahmefällen auch sein, dass Sie npm oder Ihre CI auf eine Weise verwenden oder konfiguriert haben, die Greenkeeper noch nicht kennt. Wenn Sie denken, dass ihr individuelles Setup dazu führen könnte, dass Greenkeeper nicht funktioniert, dann freuen wir uns, wenn Sie mit uns in Kontakt treten. Wir helfen Ihnen gern.

Zum Seitenanfang

Wie Greenkeeper funktioniert (Schritt für Schritt)

Nachdem Greenkeeper installiert wurde, automatisiert Greenkeeper die folgenden Arbeitsschritte:

Greenkeeper überprüft Ihre Dependencies auf Updates
Greenkeeper überwacht den Feed von npm auf Updates, die eine der Abhängigkeiten in Ihren package.json-Dateien betreffen. Sie können definieren, welche Dependencies ignoriert werden sollen.
Ein Dependency-Update ist verfügbar
Greenkeeper erstellt einen Branch, in dem Versionsnummer der Dependency in Ihren package.json-Dateien aktualisiert wird. Ihre CI-Tests laufen auf dem Branch und sobald diese fertig sind, passiert eines der folgenden Dinge:
1. Es ist ein in-range Update und die Testdurchläufe sind erfolgreich:
  Greenkeeper löscht den Branch und wird keinen Pull Request schicken. Es passiert also nichts, weil alles in Ordnung ist.
  
  In-range heißt, dass Sie eine Range (eine Versions-Spanne) für die Dependency spezifiziert haben (z.B. ^1.0.0), und die neue Version innerhalb dieser range liegt (z.B. 1.0.1). Um herauszufinden, welche Updates zu Ihren spezifizierten ranges pro Paket passen, können Sie den npm semver calculator nutzen.
2. Es ist ein in-range Update und die Tests sind fehlgeschlagen:
  Greenkeeper benachrichtigt Sie über das Problem, indem es eine Issue öffnet. Es wird Sie außerdem wissen lassen, ob das Pinnen der Dependency an die vorherige Version das Problem vermeiden würde. Greenkeeper wird außerdem bei jeder neuen Version der Dependency wieder prüfen, ob sie das Problem beheben würde und benachrichtigt Sie darüber in dieser Issue.
  
  Beispiel für eine Issue, das geöffnet wird, wenn die Tests mit der neuen Version fehlschlagen.
3. Das Update ist out-of-range:
  Greenkeeper öffnet einen Pull Request. Out-of-range bedeutet, dass Nutzer Ihres Projekts dieses Update nie bekommen würden, weil es mit npm install nicht installiert würde. Aber es könnte sein, dass die Version Änderungen enthält, die für Sie von Interesse sein können (Sicherheitsupdates, Leistungsverbesserung, bessere Kompatibilität usw.). Der Pull Request eignet sich in dem Fall als Basis für die Weiterarbeit an dem Projekt. Falls die Tests alle positiv verlaufen sind und Sie ihnen vertrauen, können Sie den Pull Request natürlich auch gleich mergen.
  
  Beispiel für einen Pull Request, der durch ein out-of-range Update erstellt wurde
  
  Sie bekommen immer nur einen Pull Request pro Dependency. Gibt es weitere Updates für die Dependency und ist bereits ein offener Pull Request vorhanden, wird dieser mit einem Kommentar aktualisiert.
  
  Ein follow-up Update für einen noch offenen PR erscheint als Kommentar
  
  Out-of-range heißt: Wenn Sie eine range von ^1.0.0 spezifizieren und ein Update auf 2.0.0 veröffentlicht wird, dann ist dieses Update out-of-range. Das heißt, die Versionsnummer ist höher als in der Spezifikation angegeben und das neu veröffentlichte Update würde normalerweise ignoriert werden. Mit dem npm semver calculator kann überprüft werden, welche Updates zu den spezifischen ranges passen.
Greenkeeper überprüft den Pull Request
Um zu verhindern, dass sich Schadsoftware als der Greenkeeper-Bot ausgeben kann, wird jedem Pull Request, der von Greenkeeper erstellt wird, ein Status Check (greenkeeper/verify) hinzugefügt. Wenn der Status nicht von Greenkeeper verifiziert wurde, dann ist der Pull Request nicht von uns.

Pull Requests von Greenkeeper sind verifiziert

Wichtig: Dieser Status sollte nicht als required in den Repository-Einstellungen markiert werden, da dieser Status bei jedem Pull Request mit dabei ist, auch bei denen, die Greenkeeper nicht erstellt hat. Bei Pull Requests wird der Status dann für immer als pending angezeigt werden, da Greenkeeper damit nichts zu tun hat. Dies ist leider eine Limitation von GitHub.

Zum Seitenanfang

Ein Repo zurücksetzen

Manchmal muss Greenkeeper auf einem Repo neu gestartet werden, zum Beispiel wenn der initiale Pull Request aus irgendwelchen Gründen nicht geöffnet wird. Wenn das der Fall ist, dann gehen Sie wie folgt vor:

Klicke den 'fix repo' Button in https://account.greenkeeper.io

Was bei einem Reset passiert:

Es werden alle Branches und Issues gelöscht, die Greenkeeper auf ihrem Repository erstellt hat.
Ein neuer initialer Greenkeeper Branch und Pull Request wird erstellt.

Es kann bis zu 30 minuten dauern, bis ein neuer initialer Branch auf ihrem Repository erscheint. Sollte auch nach Ablauf dieser Zeit noch kein neuer Branch von Greenkeeper erstellt worden sein, nehmen Sie bitte Kontakt mit uns auf und lassen Sie uns wissen, um welche Repository es sich handelt. Wir helfen gern.

Zum Seitenanfang

Eine Dependency pinnen

Wenn Ihnen Zeit und Ressourcen fehlen um ein Problem zu lösen, das durch ein Dependency Update aufkommen würde, ist das kein Problem. Greenkeeper bietet Ihnen die Möglichkeit eine früherer Version zu pinnen wenn das Problem in dieser Version noch nicht auftritt. Diese Option wird Ihnen im jeweiligen Issue angeboten.

Wenn nach einem Dependency Update Ihre Tests nicht mehr durchlaufen, lässt Greenkeeper Sie die letzte funktionierende Version im GitHub Issue pinnen

Sobald ein Paket gepinnt wurde, behandelt Greenkeeper jedes nachfolgende Update als out-of-range Update.

Zum Seitenanfang

Private Pakete aktualisieren

Greenkeeper unterstützt Aktualisierungen von privaten Paketen von npm and GitHub. Um Private Scoped Packages zu aktivieren ist ein weiterer Schritt erforderlich, welcher im initialen Pull Request ausführlich beschrieben ist. Die dafür benötigten URLs und Tokens sind für jeden Account und jedes Repository anders. Sie werden nur erstellt, wenn der initiale Pull Request generiert wird. Bitte sehen Sie sich die Anweisungen im initialen Pull Request an um hierzu weitere Informationen zu erhalten. Für Lockfile-Aktualisierungen können die entpsrechenden Zugangs-Tokens können im Greenkeeper Account Dashboard eingerichtet werden.

Verwendung von Greenkeeper mit Lockfiles

Greenkeeper hat eingebaute Unterstützung für Lockfile-Updates mit öffentlichen und/oder privaten Paketen via npm und yarn (package-lock.json und yarn.lock). Jedes Mal, wenn eine Package-Datei aktualisiert wird, wird das dazugehörige Lockfile auch aktualisiert. Lockfiles mit privaten Paketen werden auch verarbeitet, die erforderlichen Zugangs-Tokens für npm oder GitHub können im Greenkeeper Account Dashboard eingerichtet werden.

Greenkeeper unterstützt Shrinkwrap und Lockfiles mit privaten Paketen durch ein zusätzliches Paket namens greenkeeper-lockfile. Details hierzu finden Sie in dessen Dokumentation.

Wenn Sie greenkeeper-lockfile eingerichtet haben, werden die verschiedenen Lockfiles wie folgt behandelt:

Die npm-shrinkwrap.json kann Teil von dem sein, was bei npm in der Registry veröffentlicht wird, und definiert exakt, welche Dependency-Versionen Ihre User bekommen. Wenn ein Update von der bereits in der package.json definierten Range abgedeckt wird und eine npm-shrinkwrap.json existiert, macht Greenkeeper, weil garantiert ist, dass eine potentielle neue Version sowieso nie installiert wird. Wenn es ein out-of-range Update gibt, erhalten Sie aber wie immer trotzdem einen Pull Request.

package-lock.json und yarn.lock funktionieren anders, da sie nie in die npm Registry hochgeladen werden und nicht beinflussen, welche Dependency-Versionen ihre User installieren. Für in-range Updates wird Greenkeeper immer einen Branch öffnen, damit der CI laufen und die Lockfiles aktualisieren kann. Für out-of-range updates bekommen Sie wie immer einen Pull Request.

Wenn Sie keine in-range Updates für Lockfiles bekommen wollen, können sie die bequem in der package.json ausschalten:

// package.json
{
  …
  "greenkeeper": {
    "lockfiles": {
      "outOfRangeUpdatesOnly": true
    }
  }
}

Bei privaten Dependencies können sie Zugriffs-Tokens („nur lesen“) für npm und GitHub in der Greenkeeper Account App konfigurieren.

Zugriffs-Tokens für npm and GitHub konfigurieren.

Zum Seitenanfang

Greenkeeper in einer Monorepo verwenden

Greenkeeper unterstützt Repositories mit mehreren package.json-Dateien (auch Monorepos genannt). Damit das Updaten mehrerer Dateien einfacher wird, können diese gruppiert werden. Alle Module/Dependencies innerhalb einer Gruppe werden in einer Issue/einem Pull Request behandelt.

Der initiale Pull Request wird eine greenkeeper.json-Datei in Ihr Repository hinzufügen. Diese Datei beinhaltet die Konfiguration für diese Gruppierungen; normalerweise werden alle package.json-Dateien in eine Gruppe namens default gesammelt. Sie können jedoch Dateien völlig frei in ihre eigenen Gruppen umverteilen. Oft ist es üblich, jeweils eine Gruppe für Frontend- und Backend-Packages einzurichten. Jede Gruppe bekommt ihre Updates gesammelt in einem Pull Request oder Issue. Die Konfiguration hierfür sieht dann so aus:

// greenkeeper.json
{
  "groups": {
    "frontend": {
      "packages": [
        "admin-dashboard/package.json",
        "frontend/package.json"
      ]
    },
    "backend": {
      "packages": [
        "stats/package.json",
        "api-server/package.json"
      ],
      "ignore": ["hapi"]
    }
  },
  "ignore": ["standard"]
}

In diesem Fall sind die package.json-Dateien des Projekts auf zwei Gruppen verteilt: eine frontend-Gruppe und eine backend-Gruppe. Die Dateien in jeder Gruppe werden immer zusammen aktualisiert. In diesem Beispiel ignoriert die backend-Gruppe die hapi-Dependency, und das gesamte Projekt ignoriert die standard-Dependency.

Wichtig: Wenn es in dem Repo mehrere package.json-Dateien gibt, oder nur eine einzige, diese aber nicht im root-Verzeichnis des Repository ist, wird Greenkeeper nur jene aktualisieren, die auch in der greenkeeper.json-Datei eingetragen sind. Möchten Sie eine bestimmte package.json-Datei ignorieren, löschen Sie sie einfach aus dieser Datei.

Sie können auch einzelne Dependencies in bestimmten Gruppen ignorieren, indem Sie sie in der greenkeeper.json-Datei unter dem ignore-Feld eintragen.

Falls Ihnen beim Ändern dieser Konfigurationsdatei ein Fehler unterläuft, wird Greenkeeper eine Issue öffnen und versuchen zu erklären, was genau schiefgelaufen ist.

Zum Seitenanfang

Greenkeeper mit Monorepo-Dependencies verwenden

Greenkeeper wird Versionsaktualisierungen von Modulen aus populären Dependencies, die selber die Monorepos sind, in Pull Requests und Issues gruppieren, damit Sie weniger Arbeit haben. Dies sind zum Beispiel Angular, Babel, BaseT, Jest, PouchDB, React und Storybook.

Sie können die existierenden Gruppierungen in dem monorepo release definitions-Modul einsehen. Dort können Sie auch neue Gruppierungen hinzufügen oder die bestehenden verändern.

Zum Seitenanfang

Einzelne Dependency Updates ignorieren

Es könnte sein, dass Sie gute Gründe dafür haben, warum eine bestimmte Dependency nicht geupdated werden soll. Sie bekommen für Module die Sie in das `greenkeeper.ignore Feld eintragen, keine Aktualisierungen mehr:

        // package.json
{
  …
  "greenkeeper": {
    "ignore": [
      "package-names",
      "you-want-me-to-ignore"
    ]
  }
}

Sie können auch ignorierte Dependencies in einer separaten greenkeeper.json-Datei konfigurieren, wie es in der Monorepo-Dokumentation beschrieben ist.

Zum Seitenanfang

Benutzerdefinierte Commit Messages einstellen

Greenkeepers Commit-Nachrichten können konfiguriert werden, indem Sie ein greenkeeper.commitMessages-Feld in ihre package.json hinzufügen. Das ist nützlich, wenn ihr Projekt spezifische Commit-Regeln hat, und Sie sichergehen wollen, dass Greenkeeper diesen auch folgt.

Im Folgenden sind alle unterstützten Commit-Strings aufgelistet, sowie alle Variablen, die darin benutzt werden können. Und ja, es gibt Emoji-Unterstützung! 🎉

        // package.json
{
  …
  "greenkeeper": {
    "commitMessages": {
      "initialBadge": ":memo: Docs: Add Greenkeeper badge",
      "initialDependencies": ":gem: Upgrade: Update dependencies",
      "initialBranches": ":tada: Build: Whitelist greenkeeper branches",
      "dependencyUpdate": ":gem: Upgrade: Update ${dependency} to version ${version}",
      "devDependencyUpdate": ":gem: Upgrade: Update ${dependency} to version ${version}",
      "dependencyPin": ":bug: Fix: Pin ${dependency} to ${oldVersion}",
      "devDependencyPin": ":bug: Fix: Pin ${dependency} to ${oldVersion}"
    }
  }
}

Zum Seitenanfang

Benutzerdefinierte Pull Request Titel einstellen

Pull Request Titel können konfiguriert werden, indem Sie ein greenkeeper.prTitles-Feld in ihre package.json hinzufügen.

        // package.json
  {
  …
  "greenkeeper": {
    "prTitles": {
      "initialPR": "Update dependencies to enable Greenkeeper!!!",
      "initialPrBadge": "Add badge to enable Greenkeeper!!!!",
      "initialPrBadgeOnly": "Add Greenkeeper badge!!!",
      "initialSubgroupPR": "Update dependencies for ${group}!!!",
      "basicPR": "Update ${dependency} to the latest!!!",
      "groupPR": "Update ${dependency} in group ${group} to the latest!!!!"
    }
  }
  }

Zum Seitenanfang