Déployer en ligne de commande avec la CLI Vimonto Deploy

La CLI Vimonto Deploy est un petit outil en ligne de commande appelé deploy. Avec elle, vous déployez un site, suivez sa sortie et son code de sortie, listez vos serveurs et vos sites, et lancez des recettes et des sauvegardes, depuis votre propre terminal ou depuis un pipeline de CI comme GitHub Actions ou GitLab CI.

La CLI est un client léger de l’API Vimonto Deploy : chaque commande correspond à une ou plusieurs requêtes à l’API, signées avec un jeton d’API personnel. Elle peut faire exactement ce que le jeton et votre rôle dans l’organisation autorisent, rien de plus.

De quoi avez-vous besoin ?#

• PHP 8.2 ou plus récent avec l’extension curl. La CLI est un seul fichier PHP sans dépendances : il n’y a pas d’installation Composer. Vérifiez avec php -v et php -m | grep curl.
• Un jeton d’API, créé sous Paramètres du compte → Jetons d’API (voir votre compte). Le jeton n’est affiché qu’une fois, au moment où vous le créez.
• macOS, Linux ou WSL. La CLI fonctionne aussi sous Windows avec php deploy …, mais ne masque le jeton pendant la saisie que sous macOS et Linux.

Installer la CLI#

La CLI est le seul fichier deploy. Téléchargez-le depuis votre adresse Vimonto Deploy, à /cli/deploy (le lien figure aussi sous Paramètres du compte → Jetons d’API, avec la commande à copier), rendez-le exécutable et placez-le dans un répertoire de votre PATH :

curl -fsSL https://deploy.example.com/cli/deploy -o deploy
chmod +x deploy
sudo mv deploy /usr/local/bin/deploy
deploy --version

deploy --version (ou deploy version) affiche la version, par exemple deploy 1.1.0. Sans déplacer le fichier, vous pouvez aussi le lancer directement avec ./deploy ou php deploy.

Dans un pipeline de CI, committez le fichier dans votre dépôt (par exemple sous bin/deploy), ou téléchargez-le dans le job avec la même commande curl, et lancez-le avec php bin/deploy. La CLI n’a aucun autre fichier et ne demande aucune installation. Pour la mettre à jour, téléchargez-la à nouveau.

Créer un jeton d’API#

1. Ouvrez Paramètres du compte → Jetons d’API et cliquez sur Nouveau jeton.
2. Donnez-lui un Nom qui indique où il est utilisé, comme GitHub Actions ou Mon portable.
3. Choisissez les Portées : Lecture, Déployer et/ou Écriture (voir le tableau ci-dessous).
4. Choisissez quand il Expire : dans 30, 90 ou 365 jours, ou Jamais.
5. Cliquez sur Créer le jeton et copiez le jeton depuis Votre nouveau jeton. Il n’est affiché qu’une fois ; seul son hachage est enregistré.

De quelles portées une commande a-t-elle besoin ?#

Les listes demandent Lecture (ou Écriture). Un jeton avec seulement Déployer peut tout de même déployer un site et le suivre : la CLI recherche le site par son domaine ou son id, ce que cette portée permet. Les autres travaux demandent Écriture.

En plus des portées, votre rôle dans l’organisation s’applique : un jeton ne fait jamais plus que vous. Un lecteur ne peut pas déployer, même avec un jeton Écriture, et les serveurs auxquels vous n’avez pas accès ne sont pas listés. Pour un pipeline de CI qui ne fait que déployer, créez un jeton avec seulement Déployer.

Se connecter avec deploy login#

Lancez deploy login et répondez aux deux questions : l’adresse de Vimonto Deploy (l’URL que vous ouvrez dans votre navigateur) et le jeton d’API. Le jeton n’est pas affiché pendant que vous le tapez ou le collez.

$ deploy login
URL of your Deploy app, such as https://deploy.example.com: https://deploy.example.com
API token (Account → API tokens):
✓ Logged in as Jane Doe (jane@example.com), scopes: read, deploy.
Organization: acme (change with "deploy use <org>")

Vous pouvez aussi passer les deux d’un coup : deploy login --url=https://deploy.example.com --token=…. Gardez à l’esprit qu’un jeton passé en ligne de commande se retrouve dans l’historique de votre shell.

La CLI vérifie le jeton, puis enregistre l’URL, le jeton et l’organisation (celle que vous indiquez avec --org <slug>, sinon celle enregistrée auparavant, sinon la première ; DEPLOY_ORG n’est jamais enregistrée) dans ~/.config/deploy/config.json (ou $XDG_CONFIG_HOME/deploy/config.json si cette variable est définie). Le répertoire est créé avec le mode 0700 et le fichier avec 0600 : vous seul pouvez le lire. Pour vous déconnecter, supprimez ce fichier, et révoquez le jeton sous Jetons d’API quand vous n’en avez plus besoin.

Choisir l’organisation#

La plupart des commandes travaillent dans une organisation. Après deploy login, c’est l’organisation que vous utilisiez déjà, sinon la première. Listez les vôtres avec deploy orgs (celle utilisée porte un *) et changez avec deploy use :

$ deploy orgs
SLUG         NAME       ROLE
* acme       Acme       owner
  acme-labs  Acme Labs  developer

$ deploy use acme-labs
✓ Using acme-labs.

Ajoutez --org=<slug> à une commande pour utiliser une autre organisation pour cette commande seulement.

Utiliser la CLI en CI avec des variables d’environnement#

Dans un pipeline, vous ne lancez pas deploy login. Définissez plutôt ces variables d’environnement ; elles l’emportent sur le fichier de configuration :

Les couleurs sont omises quand la sortie n’est pas un terminal, et quand NO_COLOR est défini.

GitHub Actions#

Ajoutez DEPLOY_TOKEN sous Settings → Secrets and variables → Actions de votre dépôt. Ce workflow déploie une fois les tests passés, et échoue si le déploiement échoue :

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    # needs: tests   # lancez d'abord votre job de tests
    steps:
      - uses: actions/checkout@v4

      - name: Deploy shop.example.com
        run: php bin/deploy deploy shop.example.com --watch
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
          DEPLOY_URL: https://deploy.example.com
          DEPLOY_ORG: acme

Les runners Ubuntu hébergés par GitHub incluent PHP et l’extension curl : il n’y a rien à installer.

GitLab CI#

Ajoutez DEPLOY_TOKEN comme variable masquée sous Settings → CI/CD → Variables de votre projet :

# .gitlab-ci.yml
deploy:
  stage: deploy
  image: php:8.3-cli
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  variables:
    DEPLOY_URL: https://deploy.example.com
    DEPLOY_ORG: acme
  script:
    - php bin/deploy deploy shop.example.com --watch

Avec --watch, le job attend le déploiement et reçoit son résultat comme code de sortie : un déploiement échoué fait passer le pipeline au rouge. Sans --watch, le job se termine dès que le déploiement a démarré.

Déployer un site#

deploy deploy déploie la branche du site, comme Déployer maintenant dans l’application. Désignez le site par son domaine ou son id :

$ deploy deploy shop.example.com --watch
✓ Deploying shop.example.com (main) on web-1.
==> Fetch code
Cloning git@github.com:acme/shop.git (main)
HEAD is now at 3f9c2ab
==> Run deploy script
Installing dependencies from lock file
   INFO  Running migrations.
==> Go live
Linked current → releases/20261007101500
==> Clean up old releases
Kept the last 5 releases.
✓ Deploying to shop.example.com succeeded.

La CLI trouve le site par son domaine ou son id en une seule requête. Si deux serveurs ont un site avec le même domaine, ajoutez --server <nom> pour ne chercher que sur un serveur. Un déploiement lancé depuis la CLI apparaît dans la liste des déploiements du site comme les autres ; le fonctionnement des déploiements est expliqué dans déploiements.

Sans --watch, la commande lance le déploiement et affiche la commande pour le suivre :

$ deploy deploy shop.example.com
✓ Deploying shop.example.com (main) on web-1.
Follow it with: deploy task 4821 --watch

Si un déploiement du site est déjà en cours, la CLI l’indique et donne l’id de cette tâche, pour que vous puissiez la suivre.

Suivre une tâche avec --watch#

Les déploiements, les nouvelles bases de données, les recettes et les sauvegardes s’exécutent comme des tâches en arrière-plan. deploy task <id> affiche le statut d’une tâche et sa sortie jusqu’ici ; avec --watch, elle vérifie la tâche toutes les deux secondes, affiche la nouvelle sortie dès qu’elle arrive et se termine avec le résultat :

$ deploy task 4821 --watch

--watch fonctionne avec deploy, task, database:create, recipe:run et backup:run.

Toutes les commandes#

Lancez deploy help pour la version courte.

Les serveurs se désignent par leur nom ou leur id, les sites par leur domaine ou leur id, les recettes et les sauvegardes par leur nom ou leur id. La casse n’a pas d’importance. Mettez un nom avec des espaces entre guillemets.

Options#

Les options prennent leur valeur après une espace ou un = : --org acme et --org=acme sont équivalents.

Lister les serveurs et les sites#

$ deploy servers
ID  NAME   TYPE      STATUS  IP            PHP
12  web-1  app       active  203.0.113.10  8.4
14  db-1   database  active  203.0.113.11

$ deploy sites web-1
ID  DOMAIN            SERVER  FRAMEWORK  STATUS     BRANCH  DEPLOYED
31  shop.example.com  web-1   laravel    installed  main    2 h ago

Bases de données, recettes et sauvegardes#

deploy databases web-1
deploy database:create web-1 shop_reports --watch

deploy recipes
deploy recipe:run "Clear caches" web-1 web-2 --watch --notify

deploy backups db-1
deploy backup:run db-1 "Nightly" --watch

Un nom de base de données peut contenir des lettres, des chiffres et des tirets bas, jusqu’à 63 caractères, et le serveur doit être prêt et avoir une base de données installée. recipe:run lance une tâche par serveur ; avec --watch, elle les suit l’une après l’autre et échoue si l’une d’elles a échoué. Plus d’informations dans recettes.

Codes de sortie et erreurs#

deploy task <id> sans --watch se termine aussi avec 1 quand la tâche a échoué ou a été annulée, et avec 0 tant qu’elle est en file d’attente ou en cours.

Les erreurs sont écrites sur la sortie d’erreur standard, après un ✗ :

Les messages de Vimonto Deploy lui-même, comme un site qui n’a pas encore de dépôt ou un déploiement déjà en cours, sont affichés tels quels.

Questions fréquentes#

La CLI a-t-elle besoin d’un accès SSH à mes serveurs ?#

Non. La CLI ne parle qu’à l’API de Vimonto Deploy, en HTTPS. Vimonto Deploy fait ensuite le travail sur le serveur, comme lorsque vous cliquez sur un bouton dans l’application.

Où mon jeton est-il enregistré ?#

Sur votre propre machine, dans ~/.config/deploy/config.json avec les droits 0600. En CI, le jeton vient de la variable DEPLOY_TOKEN et rien n’est écrit sur le disque.

Pourquoi mon jeton de CI reçoit-il « This token or your role does not allow that » ?#

deploy, deployments et task fonctionnent avec un jeton qui n’a que Déployer. Les autres commandes, comme servers ou sites, demandent Lecture ou Écriture (voir le tableau ci-dessus). Vérifiez aussi que votre rôle dans l’organisation permet de déployer, et que vous utilisez la version 1.1.0 ou plus récente de la CLI (deploy --version) : les versions précédentes cherchaient le site via la liste des serveurs, ce qui demande Lecture.

Puis-je utiliser la CLI pour plusieurs organisations ?#

Oui. Un jeton fonctionne dans toutes les organisations dont vous êtes membre. Changez avec deploy use <org>, ou ajoutez --org=<slug> à une seule commande.

Existe-t-il une API pour ce que la CLI ne fait pas ?#

La CLI couvre les tâches les plus courantes. L’API expose les mêmes endpoints que ceux utilisés par la CLI : vous pouvez donc aussi l’appeler directement depuis vos propres scripts.