Pipelines

Un pipeline est un document YAML dans votre dépôt. Cette page décrit ce que contient ce document ; la page d'installation par pipeline s'en sert pour déployer Aetheus lui-même.

Où vit la définition

Les définitions de pipelines sont lues depuis le dépôt, sous .pipeline/<slug>.yaml. Le backend relit le fichier depuis le dépôt canonique à chaque lancement : la définition présente sur la branche par défaut est donc toujours celle qui s'exécute. Modifier un pipeline depuis l'interface web réécrit le YAML dans le dépôt et le commite, ce qui implique de récupérer les modifications sur un clone local avant de pousser à la main.

Squelette

name: mon-application-deploy
trigger: manual

variables:
  APP_VERSION: "1.0.$(BUILD_PIPELINE_RUNNUMBER)"
  DEPLOY_ROOT: "/srv/mon-application"

stages:
  - name: Build
    os: linux
    steps:
      - name: Compiler
        checkout: true
        working_directory: "$(WORKSPACE)"
        timeout_seconds: 1800
        shell: |
          set -eu
          ./build.sh

  - name: Deploy
    os: linux
    depends_on:
      - Build
    steps:
      - name: Publier sur l'hôte
        shell: sh deploy/publish.sh

Étapes

Une étape est l'unité d'ordonnancement. Elle est distribuée en bloc à un agent éligible, et déclare ses besoins :

• os : linux ou windows, utilisé pour sélectionner un agent ;
• depends_on : une liste de noms d'étapes. Les étapes sans dépendance non satisfaite s'exécutent en parallèle ; cette liste est la seule chose qui les sérialise ;
• group : un regroupement d'affichage dans la vue d'exécution, par exemple Deploy. Sans effet sur l'ordonnancement ;
• artifacts : les chemins que cette étape publie une fois ses tâches réussies. Les étapes suivantes, et les exécutions ultérieures, les restaurent par leur nom ;
• execution_role : contrainte de routage facultative quand les agents sont spécialisés.

Tâches

Les tâches d'une étape s'exécutent dans l'ordre, sur le même agent et dans le même espace de travail. Les champs courants sont :

Types de tâches natifs

Certains travaux gagnent à être exprimés en tâche de premier ordre plutôt qu'en script : le backend comprend alors le résultat au lieu d'analyser du texte. Les types employés par les pipelines livrés dans le dépôt sont :

Paramètres d'exécution

Un pipeline peut demander des valeurs au lancement via un bloc parameters: de premier niveau. Chaque paramètre a un type parmi string, boolean ou choice, et une valeur par défaut pour qu'une exécution planifiée ou déclenchée par webhook dispose quand même d'une valeur.

parameters:
  - name: revision
    display_name: Revision recorded in the deployment journal
    display_name_fr: Révision consignée dans le journal de déploiement
    description: Recorded as is; a scheduled run records "scheduled".
    description_fr: Consignée telle quelle ; un run planifié consigne « scheduled ».
    type: string
    default: scheduled
    required: false

display_name_fr et description_fr sont facultatifs : le dialogue de lancement les affiche quand l'interface est en français, et reprend display_name et description sinon.

Variables

Les valeurs sont substituées par $(NOM). Trois sources alimentent la substitution :

variables:
  APP_VERSION: "1.0.$(BUILD_PIPELINE_RUNNUMBER)"

variable_libraries:
  - mes-valeurs-publiques

vaults:
  - secrets-mon-application

Une bibliothèque de variables n'est visible que par un pipeline qui la liste ; rien n'est appliqué implicitement. Un coffre absent est un échec net à la résolution des variables, de sorte qu'une tâche ne reçoit jamais silencieusement un secret vide.

Parmi les variables intégrées : $(WORKSPACE), le répertoire de checkout, BUILD_SOURCEVERSION, la révision exacte épinglée par l'exécution, et BUILD_PIPELINE_RUNNUMBER, le compteur de build propre au pipeline.

Construire un autre dépôt

Par défaut, l'espace de travail est le dépôt où vit la définition. Un bloc source: fait extraire un autre dépôt du même projet, alors que la définition et ses fichiers .pipeline/configs continuent de venir de leur propre dépôt. C'est ainsi qu'un pipeline gardé dans un dépôt privé construit ce que contient un miroir public.

source:
  repository: mon-miroir-public  # slug d'un dépôt attaché au projet
  branch: main                   # facultatif
  must_match_definition: true    # facultatif : refuser si les arbres diffèrent
  match_exclude_file: .pipeline/configs/public-source/exclude.txt

Un dépôt externe s'attache au projet depuis son onglet Dépôt externe ; le jeton peut rester vide pour un dépôt public. Il est rafraîchi à la préparation de l'exécution, puis épinglé à un commit. Avec must_match_definition, l'exécution est refusée sauf si l'arbre extrait est, fichier par fichier, celui de la révision de la définition, une fois retirés les chemins que liste le fichier d'exclusion (un motif par ligne). match_branch compare plutôt avec la tête d'une autre branche du dépôt de la définition, pour une copie publique qui est un export adapté, consigné sur cette branche.

Modèles

Un pipeline peut étendre un modèle publié avec extends: <modèle>@<version> et ne fournir que ses propres paramètres. Les modèles sont versionnés et immuables : une version publiée ne peut pas être modifiée, adopter un changement signifie donc passer explicitement à la version suivante. C'est ce qui empêche un parc de pipelines de dériver à votre insu.

Pour aller plus loin

• Installer via un pipeline Aetheus : un pipeline minimal build, deploy et release.
• Concepts : artefacts, releases et environnements.