Déploiement

Jobs qui déploient un projet Drupal en place, dans le dépôt git du serveur (PROJECT_ROOT), et qui lancent des scripts de migration avant et après.

Fonctionnement

Le job deploy exécute sur le serveur le script drupal-deploy.sh :

1. Mode maintenance (si DRUPAL_MAINTENANCE_ON_DEPLOY: "1") : le site passe en maintenance avant toute modification du code. Un site qui y était déjà y reste.
2. Droits : le dossier du site (DRUPAL_SITE_PATH) et son settings.php deviennent inscriptibles pour git et composer, puis retrouvent exactement leurs droits d'origine.
3. git :
   • prod (tag x.y.z) : git fetch --tags --force --prune --prune-tags, pour qu'un tag recréé ou supprimé sur le dépôt le soit aussi sur le serveur, puis git checkout <tag> (HEAD détaché). Le déploiement est refusé si des fichiers suivis sont modifiés sur le serveur : le job les liste.
   • preprod : alignement forcé sur origin/<branche> (git checkout --force -B <branche>), qui écrase les modifications locales des fichiers suivis.
4. composer install --no-dev --no-interaction --prefer-dist --no-progress --optimize-autoloader, avec le composer du PATH du serveur. Les droits de l'étape 2 sont rétablis juste après.
5. drush cr. Toutes les commandes drush du déploiement reçoivent DRUSH_ALIAS (depuis 0.4.35).
6. Version déployée : enregistrée dans l'état environment_indicator.current_release (le tag en prod, <branche>-<numéro de pipeline> en preprod), et dans raven.settings si le module raven est activé.
7. drush deploy : mises à jour de base, import de la configuration, vidage des caches.
8. Mode maintenance levé.

Si une étape échoue, les droits sont rétablis et le mode maintenance est levé quand même : le job est rouge, mais le serveur ne reste ni ouvert en écriture ni en maintenance.

Depuis 0.4.36

• Fichiers modifiés sur la prod : jusqu'en 0.4.35, git checkout <tag> conservait sans rien dire un fichier modifié sur le serveur s'il était identique entre l'ancien et le nouveau tag. Désormais le déploiement est refusé. Il faut reporter la modification dans le dépôt ou l'annuler (git checkout -- <fichier>), puis relancer le job. Le job diff-repository signale ces fichiers avant le déploiement, dans le docroot.
• Fichiers non suivis : ils ne sont jamais supprimés. Un fichier non suivi que le checkout devrait écraser fait échouer git.
• Retour arrière : il reste manuel. En cas d'échec de drush deploy, le code du nouveau tag est déjà en place.

Utilisation

variables:
  CI_TEMPLATE_VERSION: &CI_TEMPLATE_VERSION main
  DRUPAL_SITE_PATH : 'web/sites/default'

include:
  - project: kgaut/gitlab-ci-templates
    ref: *CI_TEMPLATE_VERSION
    file:
      - '/templates/generic/stages-variables-extends.yml'
      - '/templates/drupal/deploy.yml'

Scripts pré-déploiement et post-déploiement

Il est possible d'exécuter des scripts PHP par drush (drush php:script) avant et après le déploiement.

Scripts pré-déploiement

Lancés avant le job deploy : avant donc que le dépôt ne soit mis à jour sur le serveur, que le composer install soit lancé…

Ils sont utiles pour désactiver un module avant sa suppression effective du composer.json.

Comme le serveur n'a pas encore le nouveau code, le job envoie le dossier des scripts par rsync, puis les exécute. Le dossier est ensuite retiré du serveur et remis à sa version versionnée, que les scripts aient réussi ou échoué.

Scripts post-déploiement

Lancés une fois que tout est déployé et que les mises à jour de base de données sont jouées. Ils sont lus dans le dépôt du serveur, que le déploiement vient de mettre à jour.

Emplacements des scripts

Par défaut :

• les scripts de pré-déploiement doivent être dans le dossier scripts/pre-deploy ;
• les scripts de post-déploiement doivent être dans le dossier scripts/post-deploy.

Tout cela peut être changé par les variables :

• MIGRATION_SCRIPT_PATH, par défaut scripts ;
• MIGRATION_SCRIPT_PREDEPLOY_PATH, par défaut $MIGRATION_SCRIPT_PATH/pre-deploy ;
• MIGRATION_SCRIPT_POSTDEPLOY_PATH, par défaut $MIGRATION_SCRIPT_PATH/post-deploy.

Notes

• Seuls les fichiers *.php sont exécutés. Les autres (README.md, .gitkeep, sauvegardes d'éditeur…) sont listés comme ignorés.
• L'ordre d'exécution est l'ordre alphabétique des noms (LC_ALL=C). Préfixez-les par un numéro (001-…, 002-…) quand l'un dépend d'un autre.
• Un script en échec arrête les suivants et fait échouer le job. Le journal récapitule ce qui a tourné (1/3 script(s) exécuté(s) avant lui, 1 non lancé(s)).
• Si un dossier est absent du dépôt, le job correspondant ne fait rien. S'il est présent dans le dépôt mais absent du serveur (envoi ou déploiement manqué), le job échoue.
• Rien ne garde la trace des scripts déjà joués : un script que vous ne supprimez pas sera exécuté à chaque déploiement, et un déploiement relancé après un échec rejoue aussi ceux qui avaient réussi. Écrivez-les rejouables (vérifier l'état avant d'agir), et retirez-les une fois passés en production.

Variables nécessaires

Nom de la variable	Contenu	Exemple	Remarque
PROJECT_ROOT	Chemin relatif ou absolu vers la racine du projet	~/public_html
SSH_CHAIN	Chaine de connexion SSH	ssh user@serveur
SSH_USER, SSH_HOST, SSH_PORT	Utilisateur, serveur et port, pour l'envoi des scripts par rsync		SSH_PORT vaut 22 par défaut
SSH_PRIVATE_KEY	Clé ssh privée pour se connecter au serveur		Comment générer une clé ssh
DRUSH_BIN	Chemin relatif à la racine du projet vers le binaire drush	vendor/bin/drush	par défaut vendor/bin/drush
DRUSH_ALIAS	Alias drush ou paramètres supplémentaires, découpés comme par un shell	@monsite	ne pas le définir si inutile ; avant 0.4.35, ignoré par le déploiement
DRUPAL_SITE_PATH	Dossier du site, relatif à la racine du projet	web/sites/default	par défaut web/sites/default
DRUPAL_MAINTENANCE_ON_DEPLOY	1 : site en maintenance pendant le déploiement	1	par défaut 0 (depuis 0.4.36)
MIGRATION_SCRIPT_PATH	Dossier des scripts de migration, relatif à la racine du projet	scripts	par défaut scripts
MIGRATION_SCRIPT_PREDEPLOY_PATH	Dossier des scripts de pré-déploiement	scripts/pre-deploy	par défaut $MIGRATION_SCRIPT_PATH/pre-deploy
MIGRATION_SCRIPT_POSTDEPLOY_PATH	Dossier des scripts de post-déploiement	scripts/post-deploy	par défaut $MIGRATION_SCRIPT_PATH/post-deploy

Liste des jobs

Chaque job existe en prod: et en preprod:.

pre-deploy

Envoie les scripts de pré-déploiement sur le serveur et les exécute (stage predeploy).

pre-deploy-success-clear et pre-deploy-failure-clear

Retirent du serveur le dossier des scripts de pré-déploiement, après la réussite ou l'échec de pre-deploy.

deploy

Lance le déploiement (stage deploy).

post-deploy

Exécute les scripts de post-déploiement (stage postdeploy).