Dokumentation

Das Mandat

Eine Seite, die zeigt, was CoRoid ohne menschliches Zutun tun kann, welche Aktionen es bereits ausgeführt hat und wie Sie den Vorgang stoppen können.

Das Mandat ist der Bereich, in dem Sie festlegen, was CoRoid ohne menschliches Eingreifen tun darf. Es hat seinen eigenen Platz in der Navigation neben der Qualitätskontrolle und besteht aus zwei Teilen: Übersicht zeigt Ihnen an, was eingestellt ist, und Einstellungen dient zum Ändern dieser Einstellungen.

Was die Übersicht Ihnen zeigt

Die Übersicht beantwortet eine Frage: Was übernimmt CoRoid von selbst, ohne Sie zu fragen?

Es beginnt mit einem Satz, zum Beispiel: "CoRoid startet automatisch Sicherheitskorrekturen und lernt bereits das Zusammenführen im Hintergrund. Alle anderen Schritte warten auf Ihre Entscheidung." Falls CoRoid auch Pull Requests selbst korrigiert oder blockiert, steht das in einer zweiten Zeile. Darunter folgen die vier Schritte, die das Mandat vorgibt, in der Reihenfolge, in der die Arbeit abläuft:

SchrittBedeutung
Arbeit startenCoRoid beginnt eine Aufgabe, nach der niemand gefragt hat, unter einem Ihrer Ziele.
ZusammenführenCoRoid führt ein pull request zusammen.
DeployCoRoid deployt in eine Umgebung.
RollbackCoRoid hebt einen fehlgeschlagenen Deployment-Vorgang rückgängig.

Jeder Schritt gibt eine dieser Angaben wieder:

  • Fragt Sie. Keine Berechtigung dafür vorhanden – daher übernimmt eine Person diese Aufgabe.
  • Lernt im Hintergrund. Eine Berechtigung existiert, doch es wird nur dokumentiert, was geschehen wäre. Der Schritt gibt den Zeitraum und die geplanten Aktionen an.
  • Erledigt es selbst. Eine aktive Berechtigung gilt – der Schritt gibt an, für welche Arbeit und wie Sie informiert werden.
  • Von CoRoid gestoppt. CoRoid hat die Berechtigung für diesen Schritt selbst deaktiviert. Öffnen Sie den Eintrag, um den Grund zu erfahren.
  • Nur Sicherheitskorrekturen (Arbeit starten): CoRoid beginnt Sicherheitskorrekturen gemäß den Einstellungen unter Sicherheit, während alle anderen Aufgaben von einer Person übernommen werden.

Ein Schritt öffnet seine Berechtigung in den Einstellungen oder erstellt eine neue Berechtigung für diesen Schritt.

Unterhalb der Schritte:

  • Immer eine Entscheidung der Person: die geschützten Pfade sowie die maximal zulässige Anzahl offener Pull Requests von CoRoid in einem Projekt. Änderungen an geschützten Pfaden werden niemals von CoRoid zusammengeführt oder deployt – unabhängig von der jeweiligen Berechtigung.
  • Ziele: Wofür CoRoid arbeitet, welche Ausgaben zulässig sind und was mit dieser Arbeit geschieht.
  • Projekte: Ein Projekt, das pausiert ist oder bei dem eine Berechtigung eingeschränkt wird, hat eine eigene Zeile. Die übrigen folgen der Organisationseinstellung.

Inhaber und Administratoren können die Autonomie ganz oben in der Übersicht pausieren.

Einrichten

  1. Öffnen Sie Mandat → Einstellungen und wählen Sie Von einer Vorlage starten, oder Neue Berechtigung für einen Schritt.
  2. Die Berechtigung startet im Hintergrund. Lassen Sie sie eine Weile an Ihrer realen Arbeit testen.
  3. Öffnen Sie die Berechtigung und lesen Sie, was sie getan hätte. Wenn das Ergebnis Sie überzeugt, wählen Sie Aktivieren.
  4. Wenn Sie darüber in Slack oder Telegram informiert werden möchten, fügen Sie eine Route für Was CoRoid tut unter Einstellungen → Verbindungen → Benachrichtigungsrouten.

Sie können eine Berechtigung jederzeit wieder in den Hintergrund versetzen oder die Autonomie pausieren.

Einstellungen

In den Einstellungen steht zuerst die Organisation und anschließend jedes Projekt. Jede Zeile zeigt die eingestellten Werte; ein Klick darauf öffnet den Editor im Seitenpanel. Direkte Bearbeitungen auf der Seite selbst finden nicht statt.

GruppeZeilen
AutonomiePausieren, inklusive aller Sperren und Aussetzungen; der Wiederherstellungsvorrat
BerechtigungenEine Zeile pro Berechtigung, mit Von einer Vorlage starten und Neue Berechtigung
ZieleEine Zeile pro Ziel, mit Neues Ziel
GrenzenGeschützte Pfade, Deployment-Aktionen, Offene Pull Requests, Agenten
HistorieJede Änderung am Mandat und jede darunter getroffene Entscheidung

Die Seite eines Projekts enthält seine eigene Pause-Einstellung, die jeweiligen Berechtigungen und die Historie. Ziele und Grenzen werden auf Organisationsebene festgelegt.

Berechtigungen

Eine Berechtigung ist eine Aufgabe, die CoRoid ohne menschliches Eingreifen ausführen darf. Die Zeile trägt ihren Namen, zum Beispiel „Zusammenführung von Arbeit, nach der eine Person gefragt hat“, und gibt den Umfang an:

Stufe Niedrig, in jedem Projekt. Maximal 5 pro Tag. Es informiert Sie zuerst und wartet 10 Minuten auf einen Stopp-Befehl.

Im zugehörigen Panel bearbeiten Sie die Einzelteile: den Schritt, auf welche Arbeit sie sich bezieht, wie riskant die Änderungen sind, welche Projekte betroffen sind, die Grenzen, die ausgeschlossenen Pfade und die Informationsweise.

Eine Berechtigung zum Deployment kann auch die Anzahl der zusammengeführten Pull Requests in einem Release begrenzen, die CoRoid deployen darf. Größere Releases werden von einer Person deployt, sodass ein Fehler im gesamten Batch niemals ohne menschliches Eingreifen in die Produktion gelangt.

Ein Grant deckt einen der vier Schritte ab – oder eine der beiden Aufgaben, die CoRoid bei Pull Requests übernimmt:

  • Pull Requests korrigieren. Wenn die Prüfungen bei einem pull request von CoRoid's eigener Arbeit fehlschlagen, startet CoRoid einen Durchlauf zur Korrektur. Ohne einen entsprechenden Grant für diese Arbeit überlässt es die Fehlerbehebung der Person, die die Rezension durchführt. Wenn Sie selbst „Fehlgeschlagene Prüfungen korrigieren“ auswählen, ist kein Grant erforderlich.
  • Pull Requests blockieren. Wenn die CoRoid-Rezension ein Problem feststellt, das behoben werden muss, fordert sie Änderungen an – sodass der pull request auf eine Person wartet. Ohne einen Grant für das Projekt bleibt die Rezension lediglich ein Kommentar und die Prüfung schlägt nicht fehl. Ein Block-Grant deckt alle pull request in seinen Projekten ab – unabhängig davon, wer sie eröffnet hat und wie riskant sie sind – außer wenn sie Pfade betreffen, die vom Grant ausgenommen sind.

Beides waren Aufgaben, die CoRoid bereits vor der Einführung von Grants ausführte. Jede Organisation nutzt sie als aktive Grants – daher ändert sich nichts, wenn sie zu Entscheidungen werden: Beschränken Sie einen auf bestimmte Projekte oder widerrufen Sie ihn – dann stoppt CoRoid die Ausführung. Eine Pause hat denselben Effekt.

Das Panel eines Grants zeigt nur das an, was sein zugehöriger Schritt erfordert. Die Entscheidung über das Starten der Arbeit, die Korrektur und das Zurückrollen wird vor jeder Änderung getroffen – daher haben sie kein Risikoniveau oder ausgenommene Pfade. Ein Block-Grant kennt keinen „Autor der Arbeit“: Er deckt alle pull request-Aufgaben ab.

CoRoid fragt nicht mehr nach der Ausführung von Arbeit: Die Entscheidung zum Starten der Arbeit fällt zu diesem Zeitpunkt. Ein Grant für die Ausführung besagt dies – und kann widerrufen werden.

Ein Grant beginnt im Schatten.

Ein neuer Grant erlaubt nichts. In Schatten zeichnet CoRoid auf, was der Grant erlaubt hätte – damit Sie dies vor der Nutzung einsehen können. Aktivieren setzt ihn in Kraft.

Eine Bearbeitung, die dem Grant mehr Befugnisse gibt, versetzt den aktiven Grant zurück in den Schatten. Eine Bearbeitung, die ihn nur einschränkt, tut dies nicht.

Was er erlaubt hätte

Öffnen Sie einen Grant, um Folgendes zu sehen:

  • wie oft CoRoid ihn angefordert hat und was er im Schatten erlaubt hätte;
  • Für einen Grant, der Zusammenführen ermöglicht: die letzten 30 Tage – wie viele Pull Requests dieser Art zusammengeführt wurden, wie viele der Grant zusammengeführt hätte, warum die restlichen nicht und welche der zusammengeführten Pull Requests später rückgängig gemacht, korrigiert oder nachbearbeitet wurden;
  • was der Grant benötigt, bevor er aktiv werden kann.

Ein Grant für Änderungen mit der Bewertung Niedrig erfordert nichts weiter: Die Regeln legen diese Bewertung fest. Ein Grant für Änderungen mit der Bewertung Mittel hängt von einem Modell ab – daher wird er erst aktiv, wenn bestimmte Kriterien erfüllt sind: mindestens 30 geprüfte Pull Requests seiner Kategorie ohne falsche Genehmigung sowie mindestens 10 fehlerhafte Änderungen, die jeweils blockiert wurden. Bis dahin gibt der Grant an, was noch fehlt.

Von einer Vorlage aus starten

Von einer Vorlage aus starten füllt das Mandat mit einer Reihe von Grants – alle im Schatten:

VorlageWas sie hinzufügt
ReparaturArbeit unter Ihren Zielen starten
ZusammenführenReparieren und die Arbeit bei der Bewertung „Niedrig“ zusammenführen.
VersendenZusammenführen und in eine von Ihnen benannte Umgebung bereitstellen.
Geschlossener KreislaufVersenden und die Umgebung bei einem Bereitstellungsfehler zurücksetzen.
Abhängigkeiten aktuell haltenAbhängigkeitsupdates mit der Bewertung „Niedrig“ zusammenführen.

Eine Vorlage aktiviert niemals einen Grant und fügt nichts hinzu, was Sie bereits haben.

Ein Projekt kann einen Grant einschränken

Die Grants der Organisation gelten standardmäßig für jedes Projekt. Auf der Seite eines Projekts können Sie einen Grant auswählen, um ihn für dieses Projekt zu deaktivieren, sein Niveau zu senken, seine Grenzen zu verkürzen oder ausgenommene Pfade hinzuzufügen. Ein Projekt kann sich niemals mehr Befugnisse verschaffen, als die Organisation gewährt.

Wenn CoRoid einen Grant selbst stoppt

  • Ausgesetzt. Der Reviewer oder der Risikobewerter von CoRoid hat sich geändert – und der Grant wurde noch nicht an der neuen Version gemessen. Er wird automatisch wieder aktiv, sobald dies geschieht.
  • Durch seinen Auslöser ausgesetzt. Die durch den Grant zusammengeführten Pull Requests wurden häufiger rückgängig gemacht, korrigiert oder nachbearbeitet als die Pull Requests, die Personen in denselben Projekten erstellt haben. Ein einzeliger Fehler führt nicht dazu. Der Grant zeigt beide Zahlen an. Eine Person hebt die Aussetzung auf und gibt den Grund an.

Was ein Grant zusammenführen kann

Ein Grant, der Zusammenführen ermöglicht, gibt an, wessen Arbeit er abdeckt. Er umfasst weiterhin nur Änderungen mit seiner Bewertung oder niedrigerer Bewertung.

ArbeitWas er abdeckt
Arbeit, die von Personen angefordert wurdeEin pull request von CoRoid, das für eine von einer Person angeforderte Aufgabe eröffnet wurde
Arbeit unter einem ZielEin pull request von CoRoid, das für Arbeit eröffnet wurde, die unter einem Ihrer Ziele begann
AbhängigkeitsupdatesEin pull request von Dependabot oder Renovate (bei GitLab: ein Merge-Request, den ein Bot mit dem Zugriffstoken des Projekts oder der Gruppe aus einem renovate/ Branch), der npm-Pakete aktualisiert, jeweils auf eine Patch- oder Minor-Version derselben Versionsreihe, die mindestens 7 Tage zuvor veröffentlicht wurde, ohne neues Installationsskript und mit einer Lockdatei, die übereinstimmt package.json, und es gibt keine offene Sicherheitswarnung. Ein solches Update wird nach Ablauf von 7 Tagen als „Niedrig“ eingestuft.
Vertrauenswürdige PersonenEin pull request durch ein Mitglied der Berechtigungsgruppe entsteht, wenn jeder Commit seit dem Basisstand vom zugehörigen GitHub-Konto des Mitglieds verfasst und committet wurde und GitHub dessen Signatur verifiziert hat. Bei GitLab öffnet das Mitglied über sein zugehöriges GitLab-Konto einen Merge-Request, wobei GitLab die Signatur jedes Commits sowie die E-Mail-Adressen des Autors und Kommitters auf ihre Gültigkeit prüft – diese müssen vom Mitglied auf GitLab bestätigt worden sein. Ein über den Web-Editor erstellter oder von einer anderen Person gepushter Commit bleibt einer menschlichen Entscheidung überlassen.

Wie eine Berechtigungsgruppe gemergt wird

Der Merge-Plan in der Factory platziert ein pull request innerhalb einer Berechtigungsgruppe unter CoRoid kann jetzt mergen, und der Merge-Zug führt den Merge durch. Zum Zeitpunkt des Merges fragt CoRoid erneut nach dem Mandat – daher können eine Pause, eine Aussetzung, ein ausgeschöpfter Limitwert oder ein neuer Commit seit Erstellung des Plans den Merge stoppen.

Der Merge-Commit benennt die Berechtigungsgruppe und ihre Version. Der Merge wird der Berechtigungsgruppe zugeordnet – für die vom Mitglied der Gruppe als verantwortlich benannte Person, im Verlauf und innerhalb der Limits der Berechtigungsgruppe.

Im Hintergrund gibt der Merge-Plan an, dass die Berechtigungsgruppe das pull request mergen würde – die endgültige Entscheidung trifft jedoch eine Person.

Ankündigen und Stoppen

Eine Berechtigungsgruppe legt fest, wie sie dich über einen Merge informiert:

  • Zuerst erfolgt die Ankündigung, anschließend wird auf ein Stopp-Signal gewartet. Sobald der Merge-Zug den Pull-Request übernimmt, erhalten die verantwortliche Person der Berechtigungsgruppe sowie die Person, die die Arbeit angefordert hat, eine Benachrichtigung. CoRoid führt den Merge nach Ablauf des Zeitfensters durch – beispielsweise nach 10 Minuten –, sofern niemand auf Stopp in der Benachrichtigung oder im Merge-Plan klickt – oder, bei verknüpftem Konto, auf den entsprechenden Beitrag in Slack oder Telegram. Ein gestopptes pull request wartet anschließend auf eine menschliche Entscheidung.
  • Nach jedem Schritt. Du wirst benachrichtigt, sobald der Merge abgeschlossen ist.

Deine Konten verknüpfen

Eine Berechtigungsgruppe für vertrauenswürdige Personen sowie CoRoid-Freigaben benötigen Kenntnis darüber, welches GitHub- oder GitLab-Konto dir gehört. Für Stopp-Befehle in Slack oder Telegram muss das jeweilige Slack- oder Telegram-Konto identifiziert werden. In Profil → Verknüpfte Konten, werden alle Konten verknüpft; die Plattform bestätigt dies. CoRoid speichert die ID und den Namen des Kontos – niemals ein Token. Bei GitLab wird außerdem ein Digest der dort bestätigten E-Mail-Adressen gespeichert (nicht die Adressen selbst); so erkennt die Plattform, ob ein Commit von dir stammt. Nach Hinzufügen einer neuen E-Mail muss das Konto erneut verknüpft werden. Entkoppeln entfernt alle Verknüpfungen. Wenn deine Organisation eine selbstverwaltete GitLab nutzt, besitzt diese nach Einrichtung durch einen Owner oder Admin eine eigene Zeile (Personenkonten auf deiner GitLab verknüpfen).

Ziele

Ein Ziel gibt an, wofür CoRoid eigenständig arbeitet, in welchen Projekten und wie viel Budget dafür zur Verfügung steht. Frühere Versionen bezeichneten Ziele als Mandate; Ziele werden ausführlich beschrieben.

Ein Ziel setzt CoRoid ein Ziel und ein Budget vor. Anfragen aus deinen Systemen, die von einem Ziel übernommen werden, starten gemäß den Angaben in Wann die Arbeit beginnt. Arbeiten von CoRoid werden eigenständig unter einem Ziel ausgeführt – beispielsweise Nachbesserungen, wenn eine Änderung das gewünschte Ergebnis nicht erzielte. Dafür wird eine aktive Berechtigungsgruppe für Arbeit starten; bis dahin wartet die Aufgabe auf eine menschliche Startfreigabe. Ausnahme sind Sicherheitskorrekturen: Diese starten gemäß den Einstellungen von Sicherheit.

Limits

Was CoRoid niemals eigenständig tun darf – unabhängig von den Vorgaben einer Berechtigungsgruppe:

  • Geschützte Pfade. Jede Änderung an diesen Pfaden entscheidet eine Person. CoRoid schützt Anmeldung und Zugriff, Abrechnung und Zahlungen, Geheimnisse und Zugangsdaten, Kryptografie, Datenbank-Migrationen, Lockfiles, CI-Pipelines sowie Container und Infrastruktur. Du kannst eigene Pfade hinzufügen. Nur ein Owner kann einen von CoRoid festgelegten Pfad entfernen – dabei muss ein Grund dokumentiert werden.
  • Deployment-Aktionen. Das Maximum, was eine Berechtigungsgruppe hier ausführen darf: Mergen, Deployen und Rollback – jeweils erlaubt, angefordert oder verweigert.
  • Offene Pull-Requests. Wie viele eigene Pull-Requests CoRoid in einem Projekt offen hält. Bei Erreichen des Limits warten eigenständig gestartete Arbeiten; Anfragen von Personen werden immer sofort bearbeitet.
  • Agenten. Wie tief ein Agent vordringen darf sowie ob Automatisierungen und Zeitpläne Aufgaben erstellen können. Ob die CoRoid-Rezension einen pull request blockieren darf, wird durch eine Berechtigungsgruppe festgelegt.

Verlauf

Jede Änderung am Mandat und jede unter ihm getroffene Entscheidung – neueste zuerst: wer eine Berechtigungsgruppe veröffentlicht oder geändert hat, was CoRoid erlaubt oder untersagt wurde und warum, sowie die Antworten der Personen auf Anfragen von CoRoid.

Wann CoRoid dich um eine Entscheidung bittet

Einige Aktionen erfordern zuvor eine menschliche Zustimmung. Jede davon wird in Erfordert Ihre Zustimmung in der Factory aufgelistet: Was CoRoid ausführen soll, wo und warum. Einmal genehmigen erlaubt die Ausführung der Aktion einmalig. Ablehnen verhindert die Ausführung. Siehe Die Factory.

Wer es ändern kann

Inhaber und Administratoren können das Mandat ändern. Mitglieder können es vollständig einsehen. Die Agenten sowie Dienstkonten von CoRoid dürfen es hingegen überhaupt nicht verändern.

Jede unter einem Mandat getroffene Entscheidung wird ebenfalls in den Audit-Stream Ihrer Organisation eingetragen – zusammen mit dem Mandat und dessen Version von CoRoid.