# Automationen in Entwicklungsprojekten

> **Zielgruppe & Rolle**
>
> **Rolle**: Verantwortliche eines Entwicklungsprojekts | **Voraussetzung**: Rolle **Pflege** oder **Verwaltung** im
> Projekt oder die Berechtigung „Entwicklungsprojekte verwalten“; für Automationen im Hintergrund zusätzlich „Flows
> erstellen“ oder „Flows verwalten“

# Automationen in Entwicklungsprojekten

Jedes Entwicklungsprojekt hat eigene **Automationen**: Sie reagieren auf ein Ereignis im Projekt – ein Vorgang wird
angelegt, ein Label gesetzt, ein Pull Request gemergt –, prüfen optional eine Bedingung und führen dann einen oder
mehrere Schritte aus. Gebaut werden sie im selben Editor wie [Flows](/knowledge/docs/products/portal/user-docs/automatisierung/flows-bauen.md), als Diagramm oder YAML.

> [!NOTE] Vorgang und Element
> Im Editor heißen die Ereignisse und Aktionen der Entwicklung „Element …“ (etwa **Element angelegt**). Gemeint sind
> die Vorgänge des Projekts.

## Der Bereich Automationen

Unter **Projekteinstellungen › Automationen** stehen in einer Liste

- die **Sofort**-Automationen des Projekts – sie laufen direkt bei der Änderung, in der Reihenfolge der Liste –, und
- die **Flows des Projekts** mit dem Kennzeichen **Im Hintergrund** (siehe
  [Flows eines Bereichs oder Projekts](/knowledge/docs/products/portal/user-docs/automatisierung/flows-bauen.md#flows-eines-bereichs-oder-projekts)).

Jede Zeile zeigt Name, Schlüssel, Auslöser („Bei: …“) und die letzte Ausführung; ein Schalter schaltet die Automation
ein oder aus. Über **⋯** ändern Sie die Reihenfolge (**Nach oben**, **Nach unten**), öffnen **Letzte Ausführungen**
oder löschen die Automation.

Sehen kann die Automationen, wer das Projekt sieht. Ändern dürfen sie Mitglieder mit der Rolle **Pflege** oder
**Verwaltung** und alle mit dem Recht „Entwicklungsprojekte verwalten“; in einem archivierten Projekt lässt sich nichts
ändern, und seine Automationen ruhen.

### Die beiden mitgelieferten Automationen

Jedes neue Projekt aus einer der Projektvorlagen (**Kanban**, **Scrum**, **Fehlerverfolgung**) bringt zwei Automationen
mit – **ausgeschaltet**, bis Sie sie einschalten:

| Automation | Auslöser | Was sie tut |
|---|---|---|
| **Unteraufgaben erledigt → Eltern erledigt** | Alle Unteraufgaben erledigt | Setzt einen Vorgang auf einen Status der Gruppe „Erledigt“, sobald seine letzte offene Unteraufgabe erledigt oder verworfen ist. |
| **PR gemergt → Erledigt** | Pull Request zum Element gemergt | Setzt einen Vorgang auf „Erledigt“, sobald sein Pull Request gemergt ist. |

Eine Projektvorlage, die Sie später unter **Projektvorlage** übernehmen, ergänzt nur Automationen, die dem Projekt noch
fehlen; bestehende ändert sie nicht.

## Eine Automation bauen

**Automation hinzufügen** fragt nach einem Namen und der **Ausführung** – **Sofort** oder **Im Hintergrund** – und
öffnet die Automation im Editor. Eine neue Sofort-Automation beginnt mit einem Ereignis-Auslöser, dessen Ereignis Sie
gleich wählen.

### Ereignisse

Eine Automation eines Projekts startet immer bei einem **Ereignis** des Projekts; von Hand lässt sie sich nicht
starten.

| Gruppe | Ereignisse |
|---|---|
| Vorgang | Element angelegt · Element geändert · Elementstatus geändert (auch geschlossen, wieder geöffnet) · Element geschlossen · Element wieder geöffnet · Element zugewiesen · Label an Element gesetzt · Label von Element entfernt · Element kommentiert · Abschnitt eines Elements geschrieben · Element verschoben (Rang oder Projekt) · Alle Unteraufgaben erledigt |
| Code | Pull Request zum Element geöffnet · bereit zur Prüfung · gemergt · geschlossen (ohne Merge) · Checks des Pull Requests fehlgeschlagen · Element ausgeliefert (Deployment) · Element veröffentlicht (Release) |
| Übergabe | Übergabe erhalten · Übergabe zurückgegeben · Übergabe zurückbekommen · Gegenstück der Übergabe geändert · Hinweis zur Übergabe (Kundennachricht) |

Das Ereignis bringt die Angaben des Vorgangs mit (`trigger.data`): Referenz, Typ, Status und Statusgruppe, Labels,
Zuständige und – je nach Ereignis – den vorherigen Status, die hinzugefügten und entfernten Labels oder die Umgebung
einer Auslieferung. Titel und Texte sind nicht dabei.

Der **Filter** des Auslösers grenzt ein – als Bedingungszeilen oder Ausdruck (siehe
[Bedingungen](/knowledge/docs/products/portal/user-docs/automatisierung/flows-bauen.md#bedingungen)):

| Gemeint | Als Ausdruck |
|---|---|
| neuer Vorgang vom Typ „fehler“ | `trigger.data.typeKey == "fehler"` |
| das Label „bug“ wurde gerade hinzugefügt | `"bug" in trigger.data.addedLabels` |
| Status wechselt aus einer anderen Gruppe nach „Erledigt“ | `trigger.data.fromStatusCategory != trigger.data.statusCategory && trigger.data.statusCategory == "done"` |
| Auslieferung in die Produktion | `trigger.data.environment == "production"` |

### Schritte

Sofort ausführen lassen sich:

| Baustein | Was er tut |
|---|---|
| **Bedingung**, **Verzweigung**, **Werte setzen**, **Ende** | Ablauf steuern, wie in Flows |
| **Status wechseln** | in einen bestimmten Status oder in eine Statusgruppe (z. B. „Erledigt“) – nach den Regeln des Ablaufs |
| **Label hinzufügen**, **Label entfernen** | ein einzelnes Label setzen oder entfernen |
| **Zuständige Person hinzufügen** | eine Person, die meldende Person oder die Person, der die [Zuständigkeit](/knowledge/docs/base/forge-zustaendigkeiten.md) des Vorgangs gehört |
| **Kommentar hinzufügen** | einen Kommentar am Vorgang schreiben |
| **E-Mail** | eine Nachricht mit eigenem Betreff und Text an Adressen und Kanäle senden |

Fügen Sie eine Aktion hinzu, ist der Vorgang des Auslösers schon eingetragen.

> [!IMPORTANT] Eine Automation handelt nur in ihrem eigenen Projekt
> Zielt eine Aktion auf einen Vorgang eines anderen Projekts, scheitert sie („Die Aktion zielt auf etwas außerhalb
> dieses Bereichs.“). Was mehrere Projekte oder andere Module betrifft, läuft im Hintergrund.

Was außerdem gilt:

- Eine Automation handelt als sie selbst („Automatik: Name“ im Verlauf), nicht als die Person, die die Änderung gemacht
  hat; die Rollen der Mitglieder werden dabei nicht geprüft, die Regeln des Ablaufs schon.
- **Auch Änderungen durch Automatisierungen:** Ohne diese Option am Auslöser reagiert eine Automation nicht auf
  Änderungen anderer Automationen oder Flows. Mit ihr lösen Automationen einander aus – höchstens vier Stufen tief,
  jede je Vorgang nur einmal je Änderung, höchstens 20 je Ereignis.
- **E-Mail:** Empfänger sind Adressen (auch aus dem Ereignis, etwa `{{ trigger.data.assignees }}`) und Teams- oder
  Webhook-Kanäle; Gruppen, Rollen und Vorgesetzte erreicht eine Automation im Hintergrund.
- Der Aufbau speichert sich selbst; eine Automation hat keine Versionen und wird nicht veröffentlicht. Mit Fehlern lässt
  sie sich nicht einschalten.

Ein Beispiel – jeder neue Fehler bekommt das Label „bug“:

```yaml
schemaVersion: 1
key: fehler-kennzeichnen
name: Neue Fehler kennzeichnen
triggers:
  - { id: angelegt, kind: event, event: forge.item.created, filter: 'trigger.data.typeKey == "fehler"' }
nodes:
  kennzeichnen:
    kind: action
    name: Label setzen
    action: forge.item.add_label
    params:
      key: "{{ trigger.data.projectKey }}"
      number: "{{ trigger.data.number }}"
      label: bug
edges:
  - angelegt -> kennzeichnen
```

## Im Hintergrund ausführen

Eine Sofort-Automation wirkt in derselben Änderung wie ihr Auslöser – wer einen Vorgang speichert, sieht ihn schon mit
Label, Status oder Zuweisung. Was nicht sofort laufen kann – **Warten**, **Aufgabe für Menschen**, Schleifen, parallele
Zweige, KI, Zeitpläne, Aktionen und Ereignisse anderer Module, Gruppen oder Rollen als Empfänger –, meldet die Prüfung
als „… läuft nur im Hintergrund“ und bietet **Im Hintergrund ausführen** an (auch über **⋯ › Im Hintergrund ausführen
…**):

1. Der Aufbau wird als **Flow des Projekts** übernommen.
2. Die Sofort-Automation wird entfernt.
3. Der Flow läuft erst, nachdem Sie ihn geprüft und veröffentlicht haben.

Dafür wählen Sie ein Service-Konto, mit dessen Berechtigungen der Flow handelt. Das kann, wer Flows anlegen und ändern
darf und das Projekt verwaltet.

> [!NOTE]
> Ein Flow hört die Ereignisse **aller** Projekte, die sein Service-Konto sieht. Nennen Sie das Projekt deshalb im
> Filter des Auslösers (`trigger.data.projectKey == "APP"`) – die fertigen Automationen im Hintergrund tun das von
> selbst.

## Wenn eine Automation scheitert

Scheitert ein Schritt – ein Statuswechsel ist nicht erlaubt, ein Label gibt es nicht mehr –, wird die ganze Automation
zurückgenommen und der Grund steht bei den Ausführungen; **die auslösende Änderung bleibt**. Mit **Wenn sie scheitert
› Änderung abbrechen** wird stattdessen die Änderung abgelehnt, und die Person sieht „Die Automation „…“ hat die
Änderung abgelehnt: …“. Änderungen, die aus GitHub kommen (Merge, Checks, Auslieferung) oder die das System selbst
macht, werden nie abgelehnt.

Der Bereich **Ausführungen** zeigt die letzten 50 Ausführungen mit Ergebnis, Zeitpunkt, Auslöser, betroffenem Vorgang,
Dauer und Fehler samt Schritt. Labels, Status und Vorgangsarten, die eine Automation nennt, lassen sich löschen oder
umbenennen – die Automation meldet dann einen Fehler bei ihren Ausführungen.

## Fertige Automationen

Unter der Liste stehen für Personen, die das Projekt pflegen, die **Fertigen Automationen**. Sie wählen eine aus,
geben ihr einen Namen und füllen ihre **Angaben** aus – mit den Typen, Labels und Status des Projekts zur Auswahl; das
Projekt selbst ist schon eingetragen. Danach öffnet sich die Automation im Editor.

| Fertige Automation | Läuft | Was sie tut | Angaben |
|---|---|---|---|
| **Neue Elemente eines Typs kennzeichnen** | Sofort | Jeder neue Vorgang des gewählten Typs bekommt ein Label. | Typ, Label |
| **Zuständige automatisch zuweisen** | Sofort | Trägt ein Vorgang ein `owner::`-Label, wird er der Person zugewiesen, der diese Zuständigkeit gehört. | – |
| **Wieder geöffnet – kommentieren** | Sofort | Schreibt einen Kommentar, wenn ein Vorgang wieder geöffnet wird. | Kommentar |
| **Bei Statuswechsel Label entfernen** | Sofort | Wechselt ein Vorgang in den gewählten Status, verliert er ein Label. | Status, Label |
| **Erinnerung, wenn ein Element lange in Arbeit ist** | Im Hintergrund | Werktags um 8 Uhr eine Mail mit den Vorgängen, die in Arbeit sind und seit Tagen nicht geändert wurden. | Tage ohne Änderung, Empfängerinnen und Empfänger |
| **Fehlgeschlagene Checks melden** | Im Hintergrund | Schlagen die Checks eines Pull Requests fehl, bekommen die Zuständigen des Vorgangs eine Mail. | – |

Eine fertige Automation unter **Im Hintergrund** wird ein Flow des Projekts und erst mit dem Veröffentlichen aktiv.
