Aller au contenu principal

Premiers pas

Semaphore UI est une interface web et une API pour exécuter des automatisations reproductibles avec Ansible, Terraform/OpenTofu, Bash, PowerShell et Python. Il réunit l’automatisation stockée dans Git, les identifiants, les variables, les planifications, les workflows et les environnements d’exécution, puis conserve l’état et le journal de chaque exécution.

Ce guide utilise Ansible pour le premier exemple pratique. Utilisez un playbook de votre propre dépôt ou reproduisez l’exemple des captures d’écran avec le dépôt public semaphoreui/semaphore-demo.

1. Installer Semaphore​

Choisissez la méthode d’installation adaptée à l’environnement où Semaphore sera exécuté. Le paquet natif est sélectionné par défaut.

Pour Debian ou Ubuntu sur amd64 :

wget https://github.com/semaphoreui/semaphore/releases/download/v2.19.12/semaphore_2.19.12_linux_amd64.deb
sudo apt install ./semaphore_2.19.12_linux_amd64.deb

Pour RHEL, Fedora, Rocky Linux, AlmaLinux ou CentOS Stream sur amd64 :

curl -LO https://github.com/semaphoreui/semaphore/releases/download/v2.19.12/semaphore_2.19.12_linux_amd64.rpm
sudo dnf install ./semaphore_2.19.12_linux_amd64.rpm

Configurez la base de données et le premier administrateur, puis démarrez Semaphore avec la configuration générée :

semaphore setup --config ./config.json
semaphore server --config ./config.json

Pour une évaluation locale, choisissez SQLite, acceptez ou définissez les chemins de la base de données et des playbooks, indiquez l’URL publique et créez le premier administrateur à l’invite.

Pour une configuration guidée, utilisez la page officielle d’installation de Semaphore afin de sélectionner la version, générer la configuration et obtenir les commandes de téléchargement ou d’exécution correspondantes.

Vous hésitez sur la méthode d’installation ?
Méthode d’installationÀ choisir pourGuide détaillé
Paquet natifUn serveur Linux pris en chargeInstallation par gestionnaire de paquets
Docker ComposeUne installation isolée rapide ou un hôte de conteneursInstallation Docker
Archive binairemacOS, Windows, FreeBSD ou Linux sans paquet adaptéInstallation du binaire
Kubernetes avec HelmUn cluster Kubernetes existantInstallation Kubernetes

Les guides détaillés couvrent les bases de données de production, les services, les secrets, le stockage, ingress et les mises à niveau.

Pour cette procédure Ansible, git --version et ansible-playbook --version doivent fonctionner sur le serveur Semaphore ou le runner. Si l’une de ces commandes est absente, installez Git et Ansible avant de continuer.

Installation en production

Avant d’utiliser Semaphore en production, consultez Configuration, Sécurité, Runners, Haute disponibilité et Mise à niveau.

2. Se connecter​

  1. Ouvrez Semaphore dans un navigateur. Une installation locale utilise généralement http://localhost:3000.
  2. Saisissez l’identifiant et le mot de passe administrateur définis par semaphore setup ou par les variables administrateur de Docker.
  3. Sélectionnez Sign In.

Écran de connexion de Semaphore

Utilisez le compte administrateur pour la configuration initiale, car il peut créer des projets et des utilisateurs. Les utilisateurs ordinaires se connectent sur la même page après qu’un administrateur a créé leur compte et accordé l’accès au projet. Consultez Gestion des utilisateurs.

3. Créer un projet​

Après connexion à une instance Semaphore vide, la page New Project s’ouvre automatiquement. Si des projets existent déjà, ouvrez le sélecteur de projets et choisissez New Project.... Remplissez le formulaire :

ChampValeur à saisir
Project NameUn nom d’espace de travail reconnaissable, par exemple Production infrastructure ou le nom de votre application.
Max number of parallel tasksFacultatif. Limite les tâches simultanées de ce projet ; laissez vide pour utiliser la limite du serveur.
Telegram Chat IDFacultatif. Utilisé lorsque les notifications Telegram sont configurées pour le projet.
Allow alerts for this projectFacultatif. Active les notifications configurées du projet.
Sélectionnez Create.

Ne sélectionnez pas Create Demo Project : cette option ajoute des ressources d’exemple, alors que ce guide crée un projet vide. Lors de la création ultérieure d’un autre projet, la même option apparaît sous forme de commutateur Demo dans la boîte de dialogue New Project.

Formulaire New Project vide avec tous les champs disponibles

Le nouveau projet comporte les sections Task Templates, Workflows, Schedule, Inventory, Variable Groups, Key Store et Repositories. Consultez Projets pour les paramètres du projet, l’accès de l’équipe, l’activité et l’historique.

Voir cette étape

Création du premier projet dans une instance Semaphore vide

4. Comprendre les concepts fondamentaux​

Le nouveau projet s’ouvre sur un Dashboard vide. La barre latérale constitue la navigation principale du projet :

Interface d’un projet Semaphore vide avant l’ajout de ressources et de tâches

  • Dashboard affiche l’historique des exécutions, les statistiques, l’activité et les paramètres du projet.
  • Task Templates, Workflows et Schedule définissent ce qui s’exécute et à quel moment.
  • Repositories, Inventory, Variable Groups et Key Store fournissent le code, les cibles, les variables et les identifiants.
  • Integrations, Team et Runners relient les systèmes externes, les utilisateurs et les hôtes d’exécution.

Le schéma montre comment ces ressources produisent une exécution :

Comment les ressources et déclencheurs Semaphore produisent une exécution de tâche

Une action dans l’interface, une requête API ou une planification peut démarrer directement un Task Template ou un Workflow utilisant des modèles de tâches. Semaphore crée une exécution, affichée comme Task dans l’interface, et l’envoie au serveur Semaphore ou à un runner distant admissible. Pour Ansible, cet hôte exécute ansible-playbook ; l’Inventory répertorie les systèmes gérés par Ansible.

ConceptFonction
ProjectUn espace de travail isolé contenant les ressources d’automatisation, les autorisations et l’historique des exécutions.
RepositoryDésigne la branche ou le tag Git contenant les fichiers d’automatisation utilisés par une tâche.
Key StoreStocke les clés SSH, identifiants, jetons et mots de passe Ansible Vault réutilisables hors de Git et des entrées de tâches.
InventoryIndique à Ansible les hôtes et groupes à gérer ainsi que les identifiants à utiliser.
Variable GroupStocke les variables Ansible, variables d’environnement et secrets réutilisables pour un ou plusieurs modèles.
Task TemplateEnregistre les éléments à exécuter : type d’automatisation, fichier, dépôt, inventaire, variables, paramètres demandés et options d’exécution.
Task (task run)Une exécution avec ses propres entrées, état, horodatages, journal, détails et résultat.
WorkflowRelie les modèles de tâches dans un parcours à plusieurs étapes avec des branches de réussite, d’échec, d’approbation et de notes.
ScheduleDémarre un modèle de tâche ou un workflow une fois ou régulièrement selon une expression cron.
RunnerExécute les tâches en attente hors du serveur principal Semaphore, par exemple dans un autre réseau ou périmètre de sécurité.

5. Connecter le dépôt​

Un Repository relie Semaphore à l’automatisation stockée dans Git ; Semaphore ne stocke pas le playbook lui-même. Connectez votre dépôt ou utilisez les valeurs de démonstration publique ci-dessous pour reproduire exactement l’exemple. Les Intégrations sont une fonction distincte permettant de lancer l’automatisation depuis GitHub, GitLab ou d’autres sources de webhooks.

  1. Ouvrez Repositories et sélectionnez New Repository.

  2. Saisissez le nom, l’URL, la branche et les identifiants du dépôt. Pour la démonstration publique, utilisez :

    ChampValeur
    NameDemo
    URL or pathhttps://github.com/semaphoreui/semaphore-demo.git
    Branch / Tagmain
    Access KeyNone, car ce dépôt est public

  3. Sélectionnez Create.

Formulaire de dépôt renseigné avec le dépôt public de démonstration Semaphore

Votre dépôt doit maintenant apparaître dans la liste. Semaphore le clone ou le met à jour sur l’hôte d’exécution au démarrage d’une tâche, et non lors de la création de l’entrée Repository. La capture présente les valeurs de démonstration de ce guide.

Dépôt Demo connecté dans la liste des dépôts du projet

Pour un dépôt privé, sélectionnez des identifiants adaptés dans le Key Store au lieu de None. Consultez Dépôts pour les chemins locaux, HTTPS, SSH, branches, identifiants et fichiers de dépendances.

6. Ajouter une clé SSH pour un hôte distant géré​

Ces identifiants SSH permettent à Ansible de se connecter depuis le serveur Semaphore ou le runner à un hôte distant de l’Inventory. Pour la démonstration localhost, aucune clé SSH n’est nécessaire ; passez à l’étape 7.

La démonstration utilise localhost avec ansible_connection=local et n’ouvre donc aucune connexion SSH. Si votre playbook gère un hôte distant, ajoutez sa clé :

  1. Ajoutez la partie publique de la clé à ~/.ssh/authorized_keys sur l’hôte géré.
  2. Ouvrez Key Store et sélectionnez New Key.
  3. Saisissez un nom reconnaissable, par exemple Production hosts, conservez Local sélectionné et choisissez SSH Key.
  4. Saisissez le compte qu’Ansible doit utiliser sur l’hôte, par exemple ubuntu ou ec2-user.
  5. Collez la clé privée complète, y compris ses lignes BEGIN et END, et ajoutez la phrase secrète si nécessaire.
  6. Sélectionnez Create. À l’étape suivante, choisissez cette clé sous Inventory → User Credentials.

Formulaire New SSH Key pour le compte utilisé sur les hôtes gérés

La capture contient une valeur fictive, pas un secret valide. Ne publiez jamais une clé privée dans la documentation, les captures, les arguments de tâches ou le contrôle de version.

Semaphore peut stocker les secrets localement ou intégrer des gestionnaires externes tels que HashiCorp Vault et Devolutions Server. Consultez Magasin de clés pour tous les types d’identifiants et options de stockage pris en charge.

7. Créer l’inventaire Ansible​

Chaque tâche Ansible nécessite un inventaire. Pour une première exécution locale, ajoutez un fichier tel que inventory.ini à votre dépôt :

[local]
localhost ansible_connection=local

Ici, localhost désigne l’hôte d’exécution, soit le serveur Semaphore, le conteneur ou le runner, pas nécessairement l’ordinateur où le navigateur est ouvert. ansible_connection=local indique à Ansible de ne pas utiliser SSH. Le dépôt de démonstration utilise le fichier équivalent invs/prod/hosts avec un groupe nommé site.

Si vous avez créé inventory.ini dans votre dépôt, effectuez un commit et un push vers la branche connectée à Semaphore avant de continuer.

  1. Ouvrez Inventory et sélectionnez New Inventory → Ansible Inventory.

  2. Saisissez les valeurs correspondant à votre inventaire. Par exemple :

    ChampValeur
    NameLocal (Prod dans la démonstration)
    User CredentialsNone pour localhost ; utilisez les identifiants SSH de l’hôte pour un inventaire distant
    TypeFile
    Path to Inventory fileinventory.ini (invs/prod/hosts dans la démonstration)

  3. Laissez Runner tag, Sudo Credentials et Repository vides, puis sélectionnez Create.

Inventaire Ansible de type fichier configuré avec les valeurs du dépôt de démonstration

Si Repository reste vide, Semaphore résout ce chemin relatif d’inventaire depuis le dépôt sélectionné dans le modèle de tâche. Choisissez un dépôt ici uniquement si l’inventaire se trouve ailleurs. Pour un hôte distant, utilisez la clé SSH de l’étape 6 comme User Credentials.

Consultez Inventaire pour les inventaires statiques, basés sur des fichiers et dynamiques.

8. Ajouter un groupe de variables (facultatif)​

Un Variable Group est un ensemble de valeurs réutilisables à associer à un ou plusieurs modèles de tâches. Utilisez Extra variables pour les variables Ansible, Environment variables pour les valeurs exportées vers le processus et Secrets pour les valeurs sensibles à chiffrer et masquer. La configuration propre à chaque environnement reste ainsi hors du playbook et n’a pas à être ressaisie dans chaque modèle.

La première tâche fonctionne sans groupe de variables. À titre d’exemple, créez-en un définissant ansible_python_interpreter=auto_silent ; Ansible détectera toujours Python automatiquement, mais n’affichera pas son avertissement informatif de détection.

  1. Ouvrez Variable Groups et sélectionnez New Group.

  2. Donnez à Group Name un nom descriptif, par exemple Ansible defaults.

  3. Sous Variables → Extra variables, conservez Table sélectionné et choisissez +.

  4. Saisissez :

    NomTypeValeur
    ansible_python_interpreterStringauto_silent

  5. Sélectionnez Save.

Groupe de variables configuré dans l’éditeur de tableau

Consultez Groupes de variables pour les règles de priorité et les options de stockage des secrets.

9. Créer le modèle de tâche Ansible​

Examiner le playbook dans Git​

Si le dépôt connecté contient déjà un playbook Ansible, utilisez-le. Sinon, ajoutez un petit exemple tel que get-started.yml :

- name: Verify Semaphore setup
  hosts: all
  gather_facts: false
  tasks:
    - name: Check the Ansible connection
      ansible.builtin.ping:

Si vous suivez la démonstration, utilisez plutôt son ping.yml. Il cible le groupe site de l’inventaire de démonstration et exécute le rôle ping inclus.

La démonstration télécharge ce rôle depuis un sous-module Git et envoie une requête ICMP à semaphoreui.com. L’hôte d’exécution doit donc accéder à GitHub et autoriser l’ICMP sortant. Si l’ICMP est bloqué, utilisez l’exemple local get-started.yml.

ping.yml dans le dépôt GitHub connecté

La capture présente le playbook du dépôt public de démonstration. Stocker l’automatisation dans Git permet de réviser les changements et à Semaphore d’enregistrer le commit exact utilisé pour chaque exécution.

Si vous avez créé get-started.yml dans votre dépôt, effectuez un commit et un push vers la branche connectée à Semaphore avant de continuer.

Configurer le modèle​

  1. Ouvrez Task Templates et sélectionnez New template → Applications.

  2. Activez Ansible Playbook, puis revenez à Task Templates.

  3. Sélectionnez New template → Ansible Playbook.

  4. Conservez l’onglet Task sélectionné. Build et Deploy sont des types de modèles CI/CD versionnés, inutiles pour cette exécution indépendante.

  5. Configurez le modèle avec les valeurs correspondant à vos fichiers. Par exemple :

    ChampValeurRôle
    NameRun first playbookIdentifie le modèle réutilisable et son historique de tâches.
    RepositoryVotre dépôt (Demo dans l’exemple)Fournit le playbook et les fichiers associés.
    Path to playbook fileget-started.yml (ping.yml dans la démonstration)Chemin résolu depuis la racine du dépôt.
    InventoryLocal (Prod dans la démonstration)Fournit la cible locale de cette première exécution.
    Variable GroupsAnsible defaults, si crééAjoute le paramètre Ansible réutilisable facultatif.
    Runner tagLaisser videUtilise l’exécution locale ou le runner par défaut selon la configuration du serveur.

  6. Sous Ansible options, activez Skip Galaxy install pour le petit playbook ci-dessus ou la démonstration publique : aucun n’a besoin de dépendances Galaxy pour cette tâche. Laissez cette option désactivée si votre dépôt nécessite des rôles ou collections provenant d’un fichier requirements.yml.

  7. Sélectionnez Create.

Modèle de tâche Ansible avec dépôt, inventaire et groupe de variables

Voir cette étape

Activation d’Ansible et création du premier modèle de tâche Ansible

Autres champs utiles :

  • Vaults sélectionne les mots de passe du Key Store pour le contenu Ansible chiffré.
  • Limit, Tags et Skip tags limitent ce que le playbook exécute.
  • Prompts permettent à un utilisateur, une planification ou une requête API de remplacer les valeurs autorisées pour une exécution donnée.
  • Runner tag détermine où la tâche s’exécute ; il ne sélectionne pas une cible Ansible.

Consultez Modèles Ansible et Modèles de tâches pour tous les champs et options d’exécution.

10. Exécuter le modèle et examiner la tâche​

  1. Ouvrez le modèle de tâche créé et sélectionnez Run.
  2. Ajoutez éventuellement un message tel que First Semaphore run.
  3. Laissez Dry Run et Diff désactivés, puis sélectionnez Run.

Boîte de dialogue New Task sans options supplémentaires pour le playbook Ansible

Semaphore met la tâche en file d’attente, prépare le dépôt, applique l’inventaire et le groupe de variables facultatif, puis exécute le playbook choisi. L’état passe par Waiting et Running avant de se terminer par Success ou Failed.

Journal​

Log contient la sortie réelle des commandes. Lisez le PLAY RECAP final, pas seulement l’indicateur d’état vert.

Journal d’une tâche Ansible réussie avec sortie ping et PLAY RECAP

Les compteurs exacts dépendent du playbook. Une première exécution réussie doit se terminer avec unreachable=0 et failed=0 pour localhost. Si le journal de démonstration indique changed=1, son étape ping via shell s’est exécutée et a signalé un changement ; ce n’est pas une erreur.

Détails et résumé​

OngletPoints à vérifier
LogPhases d’exécution en direct, sortie des modules, erreurs et PLAY RECAP final.
DetailsType de modèle, commit Git, message d’exécution, auteur, horodatages et durée.
SummaryRésultats et erreurs Ansible par hôte après la fin, lorsque le résumé des tâches est disponible.

Détails de la tâche avec modèle, commit et informations temporelles

Résumé de la tâche avec le nombre d’hôtes OK et Not OK

Si Summary n’est pas disponible, vérifiez l’exécution dans Log ; PLAY RECAP reste le résultat Ansible de référence.

Voir l’exécution et le résultat

Exécution de la tâche Ansible et examen du journal et des détails

Retrouver les exécutions précédentes​

Fermez la fenêtre de tâche pour revenir à l’onglet Tasks du modèle. Chaque exécution possède son numéro de tâche, son état, son utilisateur, son heure de début, sa durée et son journal conservé. Dashboard → History affiche les exécutions de tous les modèles du projet. Consultez Tâches et Historique du projet pour en savoir plus.

Historique d’un modèle Ansible avec des exécutions réussies

Si la tâche échoue, utilisez la dernière ligne significative du journal pour choisir la vérification suivante :

  • Une erreur de clonage indique un problème d’URL du dépôt, de branche, d’Access Key ou d’accès réseau depuis l’hôte d’exécution.
  • ansible-playbook: command not found signifie qu’Ansible est absent du serveur Semaphore ou du runner sélectionné.
  • UNREACHABLE indique un problème d’adressage de l’inventaire, d’identifiants d’hôte, d’accès SSH ou de vérification de clé d’hôte.
  • Une étape Ansible en échec indique généralement le nom de la tâche, l’hôte et l’erreur du module juste au-dessus de PLAY RECAP.

11. Planifier l’exécution de la tâche​

Après une exécution réussie depuis l’interface, vous pouvez automatiser le lancement. Par exemple, l’expression cron 0 3 * * * lance la tâche chaque jour à 03:00 dans le fuseau horaire affiché par Semaphore.

  1. Ouvrez Schedule et sélectionnez New Schedule → Cron.
  2. Saisissez un nom descriptif, par exemple Nightly playbook.
  3. Sélectionnez le modèle de tâche à exécuter.
  4. Conservez Show cron format activé et saisissez une expression cron, par exemple 0 3 * * *.
  5. Conservez Enabled sélectionné et choisissez Save.

Planification cron pour exécuter la tâche d’exemple chaque jour à 03:00

Semaphore affiche le fuseau horaire configuré et calcule la prochaine exécution avant l’enregistrement. Une exécution planifiée utilise les mêmes dépôt, inventaire, groupes de variables et paramètres d’exécution que le modèle. Si le modèle expose des paramètres à renseigner, la planification peut fournir leurs valeurs. Consultez Planifications pour la syntaxe cron, les fuseaux horaires, les exécutions uniques et les paramètres planifiés.

Après l’enregistrement, vérifiez que la planification est Enabled et que Next run affiche l’heure attendue. Les tâches planifiées apparaissent dans l’onglet Tasks du modèle et dans Dashboard → History.

Pour aller plus loin​

Une fois la première tâche Ansible réussie :

  • Ajoutez les identifiants privés adaptés dans le Magasin de clés si votre dépôt exige une authentification.
  • Créez un Workflow lorsque plusieurs modèles nécessitent des parcours ordonnés de réussite, d’échec, d’approbation ou de notes.
  • Utilisez les Intégrations pour les déclencheurs webhook authentifiés depuis GitHub, GitLab ou d’autres systèmes.
  • Utilisez l’API pour gérer les ressources et démarrer les modèles par programmation.
  • Ajoutez un runner distant si l’exécution doit se faire dans un autre réseau, système d’exploitation ou périmètre de sécurité.

Pour la production, exposez Semaphore via HTTPS, sauvegardez ensemble la base de données et le secret de chiffrement des clés d’accès, configurez une authentification centralisée et consultez Sécurité, Journaux et Mise à niveau.