Automatisiere Agile-Workflows mit dem gem gitlab-triage

Willkommen zu unserer Serie „Erste Schritte mit GitLab“, in der wir Einsteiger(inne)n helfen, die GitLabs DevSecOps-Plattform kennenzulernen.

In diesem Beitrag geht es um das gem gitlab-triage, ein leistungsstarkes Tool, mit dem du Bots erstellen kannst, um deinen Agile-Workflow zu automatisieren.

Warum solltest du deinen Workflow automatisieren?

Effizienz ist in der Softwareentwicklung ausschlaggebend. Indem du wiederkehrende Aufgaben wie die Triage von Tickets und Merge Requests automatisierst, schaffst du wertvolle Zeit für dein Team, in der es sich auf das Wichtigste konzentrieren kann: tolle Software zu entwickeln.

Mit gitlab-triage kannst du Folgendes tun:

• Konsistenz sicherstellen: Wende Labels an und weise Tickets automatisch anhand vordefinierter Regeln zu.
• Reaktionszeit verbessern: Erhalte sofortiges Feedback zu neuen Tickets und Merge Requests.
• Manuellen Aufwand reduzieren: Mache manuelle Triage und Updates überflüssig.
• Produktivität steigern: Entlaste dein Team, damit es sich auf das Programmieren und auf Innovationen konzentrieren kann.

Wir stellen vor: das gem gitlab-triage

Das gem gitlab-triage ist eine Ruby-Bibliothek, mit der du Bots erstellen kannst, die mit deinen GitLab-Projekten interagieren. Diese Bots können automatisch verschiedenste Aktionen durchführen, darunter:

• Labels zuweisen: Kategorisiere Tickets und Merge Requests automatisch.
• Kommentare verfassen: Gib Neuheiten bekannt, fordere Informationen an oder hinterlasse Feedback.
• Aufgaben zuweisen: Weise Tickets und Merge Request dem passenden Teammitglied zu.
• Abschließen: Schließe veraltete oder gelöste Tickets und Merge Requests.
• Tickets erstellen: Erstelle neue Tickets basierend auf bestimmten Ereignissen oder Bedingungen.
• Und vieles mehr!

Sieh dir das gem-Repository gitlab-triage an.

Einrichtung deines Triage-Bots

Richten wir jetzt deinen ersten Triage-Bot ein und bringen ihn zum Laufen.

1. Installiere das gem. (Hinweis: Der Befehl gem ist verfügbar, wenn die Programmiersprache Ruby installiert ist.)

gem install gitlab-triage

2. Rufe dein GitLab-API-Token ab.

• Gehe zu deinen GitLab-Profileinstellungen.
• Gehe zu Zugriffstoken.
• Erstelle ein neues Token mit dem Geltungsbereich api.
• Bewahre dein Token sicher auf und lege ein Ablaufdatum dafür fest, sodass es abläuft, wenn du diese Anleitung abgeschlossen hast.

3. Definiere deine Triage-Richtlinien.

Erstelle im Root-Verzeichnis deines Projekts eine Datei mit dem Namen .triage-policies.yml. Diese Datei enthält die Regeln, die das Verhalten deines Bots steuern. Hier ist ein einfaches Beispiel:

---
- name: "Apply 'WIP' label"
  condition:
    draft: true
  action:
    labels:
      - status::wip

- name: "Request more information on old issue"
  condition:
   date:
    attribute: updated_at
    condition: older_than
    interval_type: months
    interval: 12
  action:
    comment: |
      {{author}} This issue has been open for more than 12 months, is this still an issue?

Diese Konfiguration definiert zwei Richtlinien:

• Mit der ersten Richtlinie wird das Label status::wip allen Tickets zugewiesen, die im Entwurfsstatus sind.
• Mit der zweiten Richtlinie wird ein Kommentar zu einem Ticket hinzugefügt, in dem angemerkt wird, dass das Ticket in den letzten 12 Monaten nicht aktualisiert wurde.

4. Führe deinen Bot aus.

Du kannst deinen Bot manuell mit dem folgenden Befehl ausführen:

gitlab-triage -t <your_api_token> -p <your_project_id>

Ersetze <your_api_token> mit deinem GitLab-API-Token und <your_project_id> mit der ID deines GitLab-Projekts. Wenn du sehen möchtest, welche Auswirkungen die Aktionen haben, bevor sie tatsächlich ausgeführt hast, kannst du -n oder --dry-run hinzufügen, um die Richtlinien erst einmal zu testen.

Automatisierung mit GitLab CI/CD

Um die Ausführung deines Triage-Bots zu automatisieren, integrierst du ihn in GitLab CI/CD (nur in englischer Sprache verfügbar). Hier ist ein Beispiel für eine .gitlab-ci.yml-Konfiguration:

triage:
  script:
    - gem install gitlab-triage
    - gitlab-triage -t $GITLAB_TOKEN -p $CI_PROJECT_ID
  only:
    - schedules

Diese Konfiguration definiert einen Job mit dem Namen „Triage“, der das gem gitlab-triage installiert und den Bot mit dem $GITLAB_TOKEN (eine vordefinierte CI/CD-Variable; Dokumentation nur in englischer Sprache verfügbar) und der Variable $CI_PROJECT_ID ausführt. Die Klausel only: schedules stellt sicher, dass der Auftrag nur nach einem Zeitplan ausgeführt wird.

Um einen Zeitplan (nur in englischer Sprache verfügbar) zu erstellen, gehe zu den CI/CD-Einstellungen des Projekts und dann zu Zeitpläne. Erstelle einen neuen Zeitplan und lege fest, wie häufig dein Bot ausgeführt werden soll (z. B. täglich, stündlich, usw.).

Erweiterte Triage-Richtlinien

gitlab-triage bietet eine Reihe von erweiterten Funktionen, mit denen du ausgefeiltere Triage-Richtlinien erstellen kannst:

• Reguläre Ausdrücke: Verwende reguläre Ausdrücke für einen leistungsstarken Musterabgleich.
• Zusammenfassungsrichtlinien: Konsolidiere ähnliche Tickets in ein Übersichtsticket.
• Benutzerdefinierte Aktionen: Definiere mit Ruby-Codeblöcken benutzerdefinierte Aktionen, um komplexere Abläufe über die GitLab-API auszuführen.

Hier sind zwei umfassendere Praxisbeispiele aus dem Triage-Bot, der vom Developer Advocacy Team bei GitLab verwendet wird. Die vollständigen Richtlinien findest du in dieser Datei.

- name: Issues where DA team member is an assignee outside DA-Meta project i.e. DevRel-Influenced
  conditions:
    assignee_member:
      source: group
      condition: member_of
      source_id: 1008
    state: opened
    ruby: get_project_id != 18 
    forbidden_labels:
      - developer-advocacy
  actions:   
    labels:
      - developer-advocacy
      - DevRel-Influenced
      - DA-Bot::Skip

Dieses Beispiel zeigt Tickets in einer Gruppe. Dabei werden diejenigen ausgeschlossen, die sich im Projekt mit der ID 18 befinden und die Beauftragte haben, die Mitglieder der Gruppe mit der ID 1008 sind und nicht das Label developer-advocacy aufweisen. Mit dieser Richtlinie kann das Developer Advocacy Team bei GitLab Tickets finden, die Mitgliedern des Teams zugewiesen sind, aber nicht im Projekt des Teams enthalten sind. Indem die Labels der Teams hinzugefügt werden, kann das Team Beiträge identifizieren und nachverfolgen, die von Personen außerhalb des Teams gemacht wurden.

- name: Missing Due Dates
  conditions:
    ruby: missing_due_date
    state: opened
    labels:
      - developer-advocacy
    forbidden_labels:
      - DA-Due::N/A
      - DA-Bot::Skip
      - DA-Status::FYI
      - DA-Status::OnHold
      - CFP
      - DA-Bot::Triage
  actions:
    labels:
      - DA-Bot-Auto-Due-Date
    comment: |
      /due #{get_current_quarter_last_date}

Der Bot in diesem zweiten Beispiel sucht nach allen Tickets mit dem Label developer-advocacy, die keine Labels aus der Liste der verbotenen Labes enthalten und deren Fälligkeitsdatum überschritten wurde. Er aktualisiert die Fälligkeitstermine automatisch, indem er dem Ticket mit einem Slash-Befehl und einem Datum, das über Ruby generiert wird, einen Kommentar hinzufügt.

Die in den Richtlinien verwendeten Ruby-Skripte werden in einer separaten Datei definiert, wie unten gezeigt. Mit dieser Funktion kannst du flexibel mit Filtern und Aktionen arbeiten. Du siehst, dass Funktionen für verschiedene Ruby-Befehle erstellt werden, die wir in unseren Richtlinien verwendet haben.

require 'json'
require 'date'
require "faraday"
require 'dotenv/load'

module DATriagePlugin
  def last_comment_at
    conn = Faraday.new(
      url: notes_url+"?sort=desc&order_by=created_at&pagination=keyset&per_page=1",
      headers: {'PRIVATE-TOKEN' => ENV.fetch("PRIV_KEY"), 'Content-Type' => 'application/json' }
    )

    response = conn.get()
    if response.status == 200
      jsonData = JSON.parse(response.body)
      if jsonData.length > 0
        Date.parse(jsonData[0]['created_at'])
      else
        Date.parse(resource[:created_at])
      end
    else
      Date.parse(resource[:created_at])
    end
  end

  def notes_url
    resource[:_links][:notes]
  end

  def get_project_id
    resource[:project_id]
  end

  def get_current_quarter_last_date()
    yr = Time.now.year
    case Time.now.month
    when 2..4
      lm = 4
    when 5..7
      lm = 7
    when 8..10
      lm = 10
    when 11..12
      lm = 1
      yr = yr + 1
    else
      lm = 1    
    end

    return Date.new(yr, lm, -1) 
  end

  def one_week_to_due_date
    if(resource[:due_date] == nil)
      false
    else
      days_to_due = (Date.parse(resource[:due_date]) - Date.today).to_i
      if(days_to_due > 0 && days_to_due < 7)
        true
      else
        false
      end
    end
  end

  def due_date_past
    if(resource[:due_date] == nil)
      false
    else
      Date.today > Date.parse(resource[:due_date])
    end
  end

  def missing_due_date
    if(resource[:due_date] == nil)
      true
    else
      false
    end
  end

end

Gitlab::Triage::Resource::Context.include DATriagePlugin

Der Triage-Bot wird mit folgendem Befehl ausgeführt:

`gitlab-triage -r ./triage_bot/issue_triage_plugin.rb --debug --token $PRIV_KEY --source-id gitlab-com --source groups`  

• -r: Übergibt eine Datei mit Anforderungen für die Ausführung der Triage. In diesem Fall übergeben wir unsere Ruby-Funktionen.
• --debug: Fügt der Ausgabe Debugging-Informationen hinzu.
• --token: Wird verwendet, um ein gültiges GitLab-API-Token zu übergeben.
• --source: Gibt an, ob die Quellen des Tickets, die durchsucht werden, in einer Gruppe oder einem Projekt liegen.
• --source-id: Übernimmt die ID des ausgewählten Quelltyps – in diesem Fall eine Gruppe.

Das GitLab-Projekt triage-ops ist ein weiteres Praxisbeispiel, das etwas komplexer ist und bei dem du lernen kannst, deinen eigenen Triage-Bot zu erstellen.

Best Practices

• Beginne einfach: Beginne mit grundlegenden Richtlinien und erhöhe die Komplexität schrittweise nach Bedarf.
• Teste gründlich: Teste deine Richtlinien in einer Staging-Umgebung, bevor du sie in der Produktion bereitstellst.
• Überwache regelmäßig: Überwache die Aktivität deines Bots, um sicherzustellen, dass er sich wie erwartet verhält.
• Verwende beschreibende Namen: Gib deinen Richtlinien klare und beschreibende Namen, damit sie einfach gepflegt werden können.
• Achte auf den Umfang deiner Filter: Vielleicht kommst du in Versuchung, Tickets über Gruppen hinweg zu filtern, die Tausende von Tickets enthalten. Dies kann jedoch die Triage verlangsamen und der Prozess kann aufgrund von Ratenbeschränkungen für die GitLab-API auch fehlschlagen.
• Priorisiere die Verwendung von Labels für die Triage: Um unnötige Benachrichtigungen an andere Benuzter(innen) zu vermeiden, sind Labels eine tolle Möglichkeit, eine Triage durchzuführen, ohne Kommentare und Tickets zu überladen.

Übernimm die Kontrolle über deinen Workflow

Mit dem gem gitlab-triage kannst du deinen GitLab-Workflow automatisieren und eine ganz neue Effizienz ermöglichen. Erstelle zunächst einen einfachen Traige-Bot und lerne dann nach und nach die fortschrittlicheren Funktionen kennen. Du wirst erstaunt sein, wie viel Zeit und Aufwand du einsparen kannst!

Serie: Erste Schritte mit GitLab

Weitere Artikel in unserer Serie „Erste Schritte mit GitLab“:

• Benutzerverwaltung

• Projekte in GitLab importieren (nur in englischer Sprache verfügbar)

• Projektmanagement