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:

Zum Seitenanfang

Installation

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

  1. 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.

  2. 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

  3. 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:

  1. 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.

  2. 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.

  3. 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 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.

Back to top Zum Seitenanfang

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