Premiers Pas avec GitHub Actions

GitHub Actions est une plateforme intégrée qui permet de créer, exécuter et automatiser des workflows directement dans GitHub. Dans cette section, nous allons explorer comment configurer un workflow de base, comprendre la syntaxe YAML utilisée pour définir ces workflows, et découvrir les différents déclencheurs d'événements disponibles.

1. Configuration de base : .github/workflows

Pour commencer à utiliser GitHub Actions, vous devez créer un répertoire spécifique dans votre dépôt GitHub pour y stocker vos fichiers de workflow. Ce répertoire doit être nommé .github/workflows.

Étapes pour créer votre premier workflow

  1. Créer le répertoire : Dans la racine de votre projet, créez le répertoire .github/workflows.

  2. Ajouter un fichier de workflow : Les workflows sont définis dans des fichiers au format YAML (avec l'extension .yml). Par exemple, vous pouvez créer un fichier nommé ci.yml pour un workflow CI.

Exemple de structure de dépôt avec un workflow

my-project/ ├── .github/ │ └── workflows/ │ └── ci.yml ├── src/ ├── README.md └── package.json

Le fichier de workflow contient toutes les étapes que GitHub Actions doit exécuter lorsqu'un événement est déclenché, comme un push ou une pull request. Ce fichier YAML spécifie les jobs, les actions, et d'autres paramètres qui forment la base de votre pipeline CI/CD.

2. Exemple simple d’un workflow CI

Voici un exemple de workflow CI simple qui s'exécute à chaque fois qu'une modification est poussée vers la branche main. Ce workflow installe les dépendances, exécute des tests et compile le projet.

name: CI Pipeline # Nom du workflow # Ce workflow est déclenché lors d'un push ou d'une pull request sur la branche 'main' on: push: branches: - main pull_request: branches: - main jobs: build: # Nom du job runs-on: ubuntu-latest # Environnement dans lequel le job s'exécute steps: # Étape 1 : Vérifier le code source - name: Checkout repository uses: actions/checkout@v2 # Étape 2 : Configurer Node.js - name: Set up Node.js uses: actions/setup-node@v2 with: node-version: '14' # Étape 3 : Installer les dépendances - name: Install dependencies run: npm install # Étape 4 : Exécuter les tests - name: Run tests run: npm test # Étape 5 : Compiler le projet - name: Build project run: npm run build

Explication

  • name: : Donne un nom au workflow. Ce nom est visible dans l’interface GitHub Actions.

  • on: : Spécifie les événements qui déclenchent le workflow. Dans cet exemple, le workflow s'exécute lorsqu'il y a un push ou une pull request sur la branche main.

  • jobs: : Définit les différents jobs dans le workflow. Chaque job peut contenir plusieurs étapes (steps).

  • runs-on: : Indique l'environnement où le job sera exécuté (ici, une machine Ubuntu hébergée par GitHub).

  • steps: : Les étapes à exécuter dans le job, qui peuvent inclure des actions pré-construites (comme actions/checkout@v2) ou des commandes à exécuter.

3. Syntaxe des fichiers YAML pour définir les workflows

Les workflows GitHub Actions sont écrits en YAML. Ce format est simple à lire et à écrire, et permet de structurer les workflows avec des jobs, des étapes, des actions, et des variables. Voici une explication détaillée de la syntaxe de base des fichiers YAML pour GitHub Actions.

Structure générale d’un fichier YAML GitHub Actions

name: Nom du workflow on: # Déclencheur(s) d'événement(s) push: branches: - main jobs: # Les jobs à exécuter job_name: # Nom du job runs-on: environnement # Environnement d'exécution (ex: ubuntu-latest, windows-latest, macos-latest) steps: # Les étapes à exécuter dans ce job - name: Nom de l'étape uses: action@version # Utilisation d'une action prédéfinie with: # Arguments passés à l'action param: valeur - name: Nom de l'étape run: commande_shell # Commande shell à exécuter

Les éléments YAML les plus courants

  • name: : Nom du workflow.

  • on: : Les événements qui déclenchent le workflow. Il peut s'agir de push, pull_request, schedule, ou autres.

  • jobs: : Définit les jobs, qui contiennent des étapes à exécuter.

  • runs-on: : Spécifie l'environnement d'exécution du job (ex. ubuntu-latest, windows-latest, macos-latest).

  • steps: : Les étapes dans un job, qui peuvent inclure des actions prédéfinies ou des commandes personnalisées à exécuter.

Exemples d'étapes

  1. Utilisation d’une action prédéfinie :

- name: Checkout code uses: actions/checkout@v2

Ici, nous utilisons l'action actions/checkout@v2 pour récupérer le code source du dépôt.

  1. Exécution d’une commande personnalisée :

- name: Run tests run: npm test

Cette étape exécute la commandenpm test pour lancer les tests du projet.

4. Déclencheurs (events) : push, pull_request, schedule, et plus

Les workflows GitHub Actions peuvent être déclenchés par une variété d'événements. Voici les déclencheurs les plus courants :

4.1. push

Le déclencheur push est utilisé pour exécuter un workflow chaque fois qu'un push est effectué dans le dépôt. Vous pouvez également spécifier des branches ou des chemins spécifiques pour lesquels le workflow doit s'exécuter.

Exemple Push

on: push: branches: - main paths: - 'src/**'

  • branches: : Le workflow se déclenchera uniquement lorsque des modifications sont poussées sur la branche main.

  • paths: : Le workflow s'exécutera uniquement si les fichiers modifiés se trouvent dans le répertoire src.

4.2. pull_request

Le déclencheur pull_request permet d'exécuter un workflow lorsqu'une nouvelle pull request est créée, ou lorsque celle-ci est mise à jour.

Exemple Pull Request

on: pull_request: branches: - main

Dans cet exemple, le workflow se déclenchera pour toutes les pull requests ouvertes sur la branche main.

4.3. schedule

Le déclencheur schedule vous permet de définir des workflows qui s'exécutent à des moments spécifiques, similaires à une tâche cron.

Exemple Schedule

on: schedule: - cron: "0 0 * * 1"

Cet exemple déclenche le workflow chaque lundi à minuit (heure UTC). Le format cron est le même que celui utilisé dans les tâches cron de Linux.

4.4. Autres déclencheurs

  • workflow_dispatch : Permet d’exécuter manuellement un workflow via l'interface utilisateur de GitHub.

  • workflow_call : Permet d'invoquer un workflow à partir d'un autre workflow. Cela est utile pour réutiliser des workflows dans plusieurs projets ou dépôts.

  • release : Déclenche le workflow lorsqu'une nouvelle version est publiée.

  • issue_comment : Exécute le workflow lorsqu'un commentaire est ajouté à une issue.

  • push_tag : Déclenche le workflow lorsqu'un tag est poussé.

Exemple de workflow_dispatch

on: workflow_dispatch:

Ce workflow peut être déclenché manuellement depuis l'interface GitHub Actions. Par exemple, voici un cas d'utilisation réel de workflow_dispatch pour la Plateforme CEDILLE, permettant d'ajouter un nouveau membre à l'organisation via l'interface utilisateur de GitHub Actions :

name: Ajouter un nouveau membre à l'organisation on: workflow_dispatch: inputs: github_username: description: 'GitHub username' required: true type: string github_email: description: 'GitHub Email' required: true type: string team_sre: description: 'Add to SRE team?' required: false type: boolean cluster_role: description: 'Cluster Role' required: true type: choice options: - None - Reader - Operator - Admin

Dans cet exemple, le workflow permet à l'administrateur d'ajouter un nouveau membre à l'organisation, de modifier les fichiers Terraform, et de créer une Pull Request pour appliquer ces changements.

Exemple de workflow_call

on: workflow_call:

Le déclencheur workflow_call permet à un workflow d'être appelé depuis un autre workflow. C'est une manière efficace de partager et de réutiliser des workflows dans plusieurs projets ou équipes. Par exemple, dans le dépôt cedille-workflows, nous utilisons ce type de déclencheur pour centraliser et réutiliser des workflows standardisés dans différents projets.

Voici un exemple d'utilisation de workflow_call :

name: Réutilisation d'un workflow on: workflow_call: inputs: environment: description: 'Environnement cible (dev, staging, prod)' required: true type: string jobs: build: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v2 - name: Run build run: echo "Building for ${{ inputs.environment }}"

Dans cet exemple, le workflow peut être invoqué par d'autres workflows pour effectuer une tâche spécifique, comme la construction ou le déploiement pour un environnement particulier.

Conclusion

Avec GitHub Actions, la configuration de base pour l'automatisation des workflows CI/CD est simple et puissante. En créant des workflows dans le répertoire .github/workflows, vous pouvez automatiser des tâches en réponse à divers événements tels que des push, pull_request, ou des horaires planifiés via schedule. La syntaxe YAML permet de définir facilement les jobs et les étapes, et la flexibilité des déclencheurs rend GitHub Actions adaptable à différents scénarios de développement et de déploiement.

GitHub Actions est conçu pour être intuitif et peut être étendu en utilisant des actions prédéfinies ou personnalisées, ce qui en fait un outil essentiel pour tout pipeline CI/CD moderne.