Semaphore mit Ihren Tools verbinden

Verwenden Sie eine Webhook-Integration, wenn ein externes Ereignis ein vordefiniertes Task Template auswählen und Anfragewerte auf akzeptierte Eingaben abbilden soll. Verwenden Sie die REST API, wenn Ihre Anwendung einen ausdrücklich gesteuerten Ressourcen- und Ausführungsablauf benötigt, etwa Task-Start und Statusabfrage. In beiden Fällen läuft die Automatisierung über das konfigurierte Semaphore-Ausführungsmodell. Wählen Sie danach, was der Aufrufer senden und verfolgen muss.

Ein Projekt-Alias prüft die konfigurierten Matcher seiner Integrationen und kann diejenigen starten, die zur Anfrage passen. Ein integrationsspezifischer Alias spricht eine Integration direkt an, ohne ihre Matcher auszuwerten. Das ist wichtig, wenn eine Branch- oder Ereignistyp-Regel die Ausführung steuern soll. Wählen Sie den Endpunkt bewusst und testen Sie passende sowie nicht passende Payloads. Gehen Sie nicht davon aus, dass derselbe Filter für jeden Alias-Pfad gilt.

Konfigurieren Sie Extraktoren so, dass sie die relevanten Anfrageheader oder Body-Felder lesen und dokumentierten Umgebungswerten oder Aufgabenparametern zuordnen. Die Parameterziele müssen zu den erlaubten Eingabeabfragen der Vorlage passen. Begrenzen Sie das Mapping gezielt: Eine Release-Version sollte die vorgesehene Eingabe ergeben, keinen beliebigen Befehlsbaustein. Prüfen Sie den Wert in Ihrer Automatisierung, wenn seine Bedeutung eine Prüfung erfordert, und testen Sie fehlende oder unerwartete Felder vor dem Produktiveinsatz.

Ein API-Token handelt mit den Berechtigungen seines Semaphore-Benutzers. Verwenden Sie eine Identität, deren Projektzugriff zu den vorgesehenen Integrationsvorgängen passt, und schützen Sie das Token überall, wo der aufrufende Dienst es speichert. Die API umgeht keine Projektberechtigungen. Konfigurieren Sie bei Webhook-Integrationen außerdem die dokumentierte Anfrageauthentifizierung und die Erreichbarkeit des Endpunkts bewusst. Trennen Sie die Authentifizierung des Aufrufers von den Zugangsdaten, mit denen die entstandene Aufgabe auf Infrastruktur zugreift.

Speichern Sie bei einem REST-API-Ablauf die von der dokumentierten Operation zurückgegebene Task-Kennung und prüfen Sie Status und Ausgabe über die entsprechenden API-Methoden. Eine erfolgreiche Anfrage bedeutet, dass die Ausführung angefordert wurde, nicht dass die Infrastrukturarbeit erfolgreich abgeschlossen ist. Ihr Dienst sollte zwischen Anfragefehlern, wartenden oder laufenden Tasks und abgeschlossenen Ergebnissen unterscheiden. Verlinken Sie auf den Task, wenn Verantwortliche die tatsächlichen Ausführungsnachweise untersuchen müssen.

Gehen Sie weder von einer genau einmaligen Ausführung noch von garantierter dauerhafter Zustellung aus. Ein externer Dienst kann eine Anfrage nach einer Zeitüberschreitung wiederholen, obwohl die erste Anfrage Semaphore erreicht hat. Richten Sie den Umgang mit Duplikaten und Wiederholungen nach den Folgen des Vorgangs aus und gestalten Sie die zugrunde liegende Automatisierung gegebenenfalls idempotent. Halten Sie die Zuordnung zwischen dem ursprünglichen Ereignis und der von Ihrem Dienst verfolgten Ausführung fest, damit sich wiederholte oder unklare Zustellungen nachvollziehen lassen.

Die Referenz dieser Website stellt das mit dem Semaphore-Release veröffentlichte Swagger-/OpenAPI-Dokument dar. Die angezeigten Operationen, Pfade und Schemas entsprechen damit einer bestimmten Version statt einer manuell geschriebenen Zusammenfassung. Durchsuchen Sie es unter /api-docs/ nach Ressourcen oder lesen Sie das Rohdokument, wenn Sie daraus einen Client erzeugen. Prüfen Sie stets die Spezifikation Ihrer tatsächlich eingesetzten Version, da sich Endpunkte und Anfrageschemas zwischen Releases ändern können.

Das aufrufende System muss Ihre Semaphore-Instanz erreichen; dafür ist nicht zwingend das öffentliche Internet erforderlich. Ein privates Netzwerk, VPN oder interner Load Balancer genügt, wenn der Aufrufer darin läuft. Unsere eigene Prüfung von Abgleich und Extraktoren nutzte einen nur über Loopback erreichbaren Listener ohne Authentifizierung. Das ist kein Vorbild für einen öffentlich erreichbaren Endpunkt. Sobald der Alias von außerhalb Ihres vertrauenswürdigen Netzwerks erreichbar ist, konfigurieren Sie eine unterstützte Authentifizierung und beschränken Sie die Erreichbarkeit zusätzlich auf Netzwerkebene.

Richten Sie die Integration zunächst auf ein ungefährliches Task Template und senden Sie die Nutzdaten selbst mit curl oder einem anderen HTTP-Client. Senden Sie zuerst einen nicht passenden Inhalt und prüfen Sie, dass kein Task erscheint. Senden Sie dann einen passenden Inhalt und prüfen Sie, dass genau ein Task startet. Öffnen Sie dessen Detailansicht: Sie erfasst die Integration als Quelle und zeigt der Ausführung die extrahierten Werte. Diesen Ablauf haben wir auch lokal verwendet; er deckt einen falschen Abgleichschlüssel auf, bevor ein externer Dienst davon abhängt.

Ja. Die REST API umfasst Projekte, Repositories, Inventare, Zugangsdaten, Variable Groups, Task Templates und weitere Automatisierungsressourcen. Ihr Portal oder Infrastrukturdienst kann sie konfigurieren, Tasks starten und Status sowie Ausgabe lesen. Pro stellt außerdem Workflow-Ausführungen und Freigaben über die API bereit. So kann eine CI/CD-Pipeline einen vollständigen mehrstufigen Vorgang starten. Nutzen Sie die OpenAPI-Referenz für Endpunktparameter und Antwortschemas.