Collegare Semaphore ai tuoi strumenti

Usa webhook quando un evento deve selezionare un Task Template predefinito e associare valori agli input accettati. Usa REST API per un flusso esplicito di gestione ed esecuzione, come avviare e leggere stato. In entrambi i casi l’automazione segue il modello configurato. Scegli in base a cosa il chiamante deve inviare e seguire.

Un alias di progetto valuta le regole di corrispondenza configurate nelle sue integrazioni e può avviare quelle compatibili con la richiesta. Un alias specifico indirizza direttamente una sola integrazione senza valutarne le regole. È importante se una regola su ramo o tipo di evento deve controllare l’esecuzione. Scegli l’endpoint consapevolmente e testa payload corrispondenti e non corrispondenti, senza presumere che lo stesso filtro valga per ogni percorso alias.

Configura gli estrattori per leggere header o campi del corpo rilevanti e associarli a valori d’ambiente o parametri documentati. Le destinazioni dei parametri devono corrispondere ai campi accettati dal modello. Mantieni la mappatura specifica: una versione deve diventare l’input previsto, non un frammento di comando senza limiti. Valida il valore nell’automazione quando il suo significato lo richiede e testa campi mancanti o inattesi prima della produzione.

Un token API agisce con i permessi del suo utente Semaphore. Usa un’identità con accesso ai progetti coerente con le operazioni previste e proteggi il token ovunque venga conservato dal chiamante. L’API non aggira le autorizzazioni di progetto. Per i webhook configura anche autenticazione documentata ed esposizione dell’endpoint in modo deliberato. Separa l’autenticazione del chiamante dalle credenziali usate dal task per raggiungere l’infrastruttura.

In un flusso REST API conserva l’identificativo restituito dall’operazione documentata e usa i metodi corrispondenti per stato e output. Una richiesta riuscita indica che l’esecuzione è stata richiesta, non che il lavoro infrastrutturale è riuscito. Il servizio deve distinguere errori di richiesta, task in attesa o attivi e risultati conclusi. Collega i tecnici al task per analizzare le evidenze effettive.

Non presumere esecuzione esattamente una volta o garanzie di consegna durevole. Un servizio esterno può riprovare dopo un timeout anche se la prima richiesta ha raggiunto Semaphore. Progetta gestione dei duplicati e tentativi in base alle conseguenze e rendi l’automazione idempotente dove opportuno. Conserva la correlazione tra evento originale ed esecuzione seguita dal servizio per comprendere consegne ripetute o incerte.

Il riferimento mostra il documento Swagger/OpenAPI pubblicato con la release Semaphore: operazioni, percorsi e schemi corrispondono a una versione precisa, non a un riepilogo manuale. Consultalo per risorsa in /api-docs/ o leggi il documento grezzo per generare un client. Controlla la specifica della versione realmente usata perché endpoint e schemi cambiano tra release.

Il chiamante deve raggiungere Semaphore, ma non necessariamente da Internet pubblico. Rete privata, VPN o bilanciatore interno bastano se il chiamante vi opera. I nostri test di regole ed estrattori usavano un listener solo loopback senza autenticazione, non adatto a endpoint esposti. Se l’alias è raggiungibile fuori dalla rete fidata, configura autenticazione supportata e limita l’esposizione anche in rete.

Punta prima l’integrazione a un Task Template innocuo e invia i payload con curl o un client HTTP. Invia un corpo non corrispondente e verifica che non appaia un task; poi uno corrispondente e verifica un solo avvio. Apri Details: registra l’integrazione come origine e rende visibili i valori estratti. È la stessa sequenza usata localmente e rileva una chiave errata prima che un servizio esterno ne dipenda.

Sì. La REST API copre progetti, repository, inventari, credenziali, Variable Groups, Task Template e altre risorse. Portale o servizio possono configurarli, avviare task e leggere output e stato. Pro espone anche workflow e approvazioni, quindi una pipeline CI/CD avvia operazioni complete. Usa il riferimento OpenAPI per parametri e schemi.