GitHub Actions

GitHub Actions est une plateforme d'automatisation intégrée à GitHub qui vous permet de définir et d'exécuter des workflows automatisés directement dans votre dépôt de code sans dépendre d'outils CI/CD externes.

Les cas d'utilisation courants incluent : exécuter automatiquement des tests après un push de code, déployer automatiquement sur des serveurs après la fusion de PR, et exécuter des scripts de scraping de données selon un calendrier.

GitHub Actions est entièrement gratuit pour lesdépôts publics., les dépôts privés disposent d'un quota gratuit de 2,000 minutes par mois.

Concepts fondamentaux

Avant d'écrire le fichier de configuration, vous devez comprendre les concepts clés suivants, et les relations entre eux sont les suivantes :

仓库（Repository）
└── Workflow（工作流）          ← 一个 .yml 文件 = 一个 Workflow
    ├── Event（触发事件）        ← 什么情况下启动这个 Workflow，如 push、PR
    └── Job（作业）× N          ← 一个 Workflow 可以包含多个并行或串行的 Job
        ├── Runner（运行器）     ← 执行 Job 的服务器，如 ubuntu-latest
        └── Step（步骤）× N     ← Job 内按顺序执行的一系列操作
            ├── Action          ← 可复用的封装好的操作，如 actions/checkout
            └── Run             ← 直接执行 Shell 命令

Concepts	Description	Analogie
Workflow	L'ensemble du workflow automatisé est défini par un`.yml`fichier, stocké dans`.github/workflows/`sous le répertoire	un plan de travail complet.
Événement	Conditions qui déclenchent l'exécution du Workflow, telles que le push de code, la création de PR, les tâches planifiées, etc.	La condition de démarrage du plan.
Job（tâche）	Une unité de tâche indépendante dans un Workflow. Chaque Job s'exécute sur une machine virtuelle indépendante, et plusieurs Jobs s'exécutent en parallèle par défaut.	Une section dans le plan.
Étape	La plus petite unité d'opération exécutée séquentiellement dans un Job, qui peut être une commande Shell ou une Action.	Chaque étape spécifique au sein d'une section.
Action	Opérations empaquetées réutilisables, provenant de GitHub officiel, de tiers ou écrites par vous-même, via`uses`Référence	Modèles d'outils prêts à l'emploi
Runner	Serveur qui exécute les Jobs. GitHub propose trois environnements hébergés : Ubuntu, Windows et macOS.	L'agent qui exécute le plan.

Créez votre premier Workflow.

1. Structure des répertoires

Tous les fichiers Workflow doivent être stockés dans le.github/workflows/répertoire à la racine du dépôt, et les noms de fichiers doivent se terminer par.ymlou.yamlLe nom du fichier peut être personnalisé :

your-repo/
├── .github/
│   └── workflows/
│       ├── ci.yml          ← 持续集成流程（如运行测试）
│       ├── deploy.yml      ← 部署流程
│       └── scheduled.yml   ← 定时任务
├── src/
├── package.json
└── README.md

Un dépôt peut contenir plusieurs fichiers Workflow, qui sont indépendants les uns des autres et sont déclenchés par leurs événements définis respectifs.

2. Le workflow le plus simple

Voici un exemple très basique : chaque fois que du code est poussé vers le dépôt, afficher une ligne "Hello, GitHub Actions!" :

Exemple

# .github/workflows/hello.yml

name: Hello World # Nom du workflow, affiché sur la page GitHub Actions

on: push # Condition de déclenchement : se déclenche lorsque du code est poussé vers n'importe quelle branche

jobs: # Définir toutes les tâches
say-hello: # ID de la tâche (nom personnalisé, unique au sein du même workflow)
name: Print greeting# Nom d'affichage de la tâche (facultatif ; si vide, affiche l'ID de la tâche)
runs-on: ubuntu-latest # Spécifier l'environnement d'exécution : utiliser la dernière machine virtuelle Ubuntu fournie par GitHub

steps: # Toutes les étapes de cette tâche sont exécutées dans l'ordre
- name: printMessage# Nom de l'étape (facultatif, utilisé pour identifier cette étape dans les journaux)
run: echo "Hello, GitHub Actions！" # run : exécuter directement des commandes Shell

Les fichiers YAML sont très sensibles à l'indentation et doivent utiliserdes espacesd'indentation, et ne peuvent pas utiliser la touche Tab. Il est recommandé d'utiliser VS Code et d'installer le plugin YAML, qui peut détecter les erreurs de format en temps réel.

Événements déclencheurs (on)

onLe champ définit quels événements déclenchent ce Workflow. Il peut s'agir d'un seul événement ou d'une combinaison de plusieurs événements.

1. Événements déclencheurs courants

Événements	Moment du déclenchement	Utilisations courantes
`push`	Lorsque du code est poussé vers le dépôt.	Exécuter des tests, des vérifications de code
`pull_request`	Lorsqu'une Pull Request est créée ou mise à jour.	Revue et tests automatisés avant la fusion de la PR.
`schedule`	Déclenché selon un calendrier à l'aide d'une expression Cron.	Sauvegardes planifiées, extraction de données planifiée.
`workflow_dispatch`	Déclenchement manuel sur la page web GitHub	Déploiement à la demande, exécution manuelle de script.
`release`	Lors de la publication d'une nouvelle version (création d'une Release)	Empaquetage et publication automatiques vers la production.
`workflow_call`	Lorsqu'il est appelé par d'autres Workflows	Réutiliser des workflows publics (comme les workflows de test publics)

2. Filtrage par branche ou par chemin

Exemple

span style="color: #0053A6;">
on:
push:
branches:
- main # Déclencher uniquement lors d'un push vers la branche main
- develop # Ou déclencher lors d'un push vers la branche develop
- 'release/**' # Ou déclencher lors d'un push vers toute branche commençant par release/ (** correspond à n'importe quels caractères)
chemins:
- 'src/**' # Filtrage supplémentaire : déclencher uniquement lorsque les fichiers du répertoire src/ changent.
- 'package.json' # Ou déclencher lorsque le fichier package.json change
# Les deux sont dans une relation « OU » ; l’un ou l’autre déclenche

pull_request:
branches:
- main # Se déclenche uniquement sur les PR dont la branche cible est main (c.-à-d. les PR destinées à être fusionnées dans main)
types:
- opened # Lorsqu’une PR est créée
- synchronize # Lorsqu’un nouveau commit est poussé vers la PR
- reopened # Lorsqu’une PR est rouverte

3. Déclencheurs planifiés (schedule)

Utilisez une expression Cron standard pour définir l’heure d’exécution, le fuseau horaire étant UTC (heure de Pékin = UTC+8, conversion nécessaire) :

Exemple

span style="color: #0053A6;">
on:
schedule:
# Format Cron : minute heure jour mois semaine
- cron: '0 2 * * *' # Exécuter une fois par jour à 02:00 UTC (c.-à-d. 10:00 heure de Pékin)
- cron: '0 9 * * 1' # Exécuter une fois chaque lundi à 09:00 UTC (soit 17:00 heure de Pékin)
- cron: '*/30 * * * *' # Exécuter toutes les 30 minutes

# Aide-mémoire rapide des expressions Cron courantes :
# '0 0 * * *' Chaque jour à minuit (UTC 00:00)
# '0 * * * *' toutes les heures à l'heure pile
# '0 0 * * 0' chaque dimanche à minuit
# '0 0 1 * *' minuit le 1er de chaque mois

4. Déclenchement manuel (workflow_dispatch)

workflow_dispatchPermet de cliquer manuellement sur un bouton dans l'onglet Actions de la page web GitHub pour démarrer le Workflow, et vous pouvez également définir des paramètres d'entrée :

Exemple

span style="color: #0053A6;">
on:
workflow_dispatch:
inputs:
environment: # Nom du paramètre d'entrée (peut être référencé dans les étapes via ${{ inputs.environment }})
description: 'Environnement cible de déploiement'# Description du paramètre, affichée dans le formulaire de déclenchement manuel
required: true # Est-ce requis ?
default: 'staging' # Valeur par défaut
type: choice # Type de paramètre : choice (sélection dans un menu déroulant)
options:
- staging # Valeurs optionnelles
- production

run_tests:
description: 'Exécuter les tests ou non'
required: false
type: boolean # Type de paramètre : boolean (case à cocher)
default: true

jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Afficher les paramètres de déploiement
run: |
echo "Environnement cible : ${{ inputs.environment }}"
echo "Run tests: ${{ inputs.run_tests }}"

Explication détaillée des jobs et des étapes

1. Structure de base d’un job

Exemple

span style="color: #0053A6;">
jobs:
build: # ID du job, doit être unique dans le même workflow
name: structurebuildProject# Nom d’affichage du job (facultatif)
runs-on: ubuntu-latest # Environnement d’exécution (obligatoire)

# Facultatif : définir des variables d’environnement pour l’ensemble du job, accessibles par toutes les étapes du job
env:
NODE_ENV: production
APP_PORT: 8080

# Facultatif : définir un délai d’attente en minutes. Le job sera automatiquement annulé après expiration du délai pour éviter tout blocage.
timeout-minutes: 30

steps:
# Méthode d'étape 1 : utiliser une Action (référence avec uses)
- name: Récupérer le code
uses: actions/checkout@v4 # Référence à l'Action checkout officielle (@v4 indique que la version v4 est utilisée)

# Syntaxe d'étape 2 : Exécuter une commande Shell (spécifiée avec run)
- name: Afficher la version de Node
run: node --version

# Étape 3 : Exécution de commandes Shell multilignes (utilisation de | pour plusieurs lignes)
- name: Installer les dépendances et structurer le build
run: |
npm install
npm run build
echo "Compilation terminée"

2. Environnement d'exécution (runs-on)

GitHub fournit les runners hébergés gratuits suivants, que vous pouvez choisir selon vos besoins :

Balises	Système d'exploitation	Description
`ubuntu-latest`	Ubuntu (dernière LTS)	Le plus couramment utilisé, rapide, et dispose du quota gratuit le plus généreux. Recommandé pour une utilisation prioritaire.
`ubuntu-22.04`	Ubuntu 22.04	Spécifiez une version fixe pour éviter les problèmes d'incompatibilité introduits par les dernières mises à niveau.
`windows-latest`	Windows Server (dernière version)	Utilisé pour les tests ou les compilations nécessitant un environnement Windows.
`macos-latest`	macOS (dernière version)	Utilisé pour les builds iOS/macOS, consomme le quota gratuit le plus rapidement (environ 10 fois celui d'Ubuntu).

3. Dépendances entre les Jobs (needs)

Par défaut, plusieurs Jobs s'exécutent en parallèle. UtilisezneedsVous pouvez définir l'ordre d'exécution des Jobs, formant des relations de dépendance en série :

Exemple

span style="color: #0053A6;">
jobs:
test: # Étape 1 : exécuter les tests
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm test

build: # Étape 2 : Compiler le projet
runs-on: ubuntu-latest
needs: test # le build ne démarrera qu'une fois le job de test terminé avec succès
steps:
- uses: actions/checkout@v4
- run: npm run build

deploy: # Étape 3 : Déployer
runs-on: ubuntu-latest
needs: [test, build] # Le déploiement doit attendre que test et build se terminent avec succès
steps:
- run: echo Début du déploiement...

# Ordre d'exécution : test → build → deploy (séquentiel)
# Si needs est supprimé, les trois Jobs s'exécuteront en parallèle.

4. Exécution conditionnelle (if)

ViaifVous pouvez contrôler si un Job ou une Step s'exécute, ce qui est couramment utilisé pour distinguer les branches, déterminer si l'étape précédente a réussi, etc. :

Exemple

span style="color: #0053A6;">
jobs:
deploy:
runs-on: ubuntu-latest
# if écrit au niveau du Job : l'ensemble du Job ne s'exécute que lors d'un push vers la branche main
if: github.ref == 'refs/heads/main'
steps:
- uses: actions/checkout@v4

- name: Déploiement vers l'environnement de production
run: ./deploy.sh

# if peut également être écrit au niveau de l'étape pour contrôler si une étape spécifique s'exécute
- name: Envoyer une notification de réussite
if: success() # success(): s'exécute uniquement lorsque toutes les étapes ci-dessus réussissent
run: echo "Déploiement réussi, envoyer une notification"

- name: Envoyer une notification d'échec
if: failure() # failure(): S'exécute uniquement lorsqu'une étape échoue
run: echo Échec du déploiement, envoyer une alerte

- name: Étapes de nettoyage toujours exécutées
if: always() # always(): S'exécute indépendamment du succès ou de l'échec (souvent utilisé pour nettoyer les fichiers temporaires)
run: rm -rf ./tmp

Variables d'environnement et secrets

1. Variables d'environnement (env)

Les variables d'environnement peuvent être définies à trois niveaux dans le Workflow, avec une portée décroissante dans l'ordre :

Exemple

# Niveau 1 : niveau Workflow (accessible à tous les Jobs et étapes)
env:
APP_NAME: my-app
NODE_VERSION: '18'

jobs:
build:
runs-on: ubuntu-latest

# Niveau 2 : niveau Job (seules les étapes au sein du Job actuel peuvent y accéder)
env:
BUILD_MODE: production

steps:
- name: Afficher les variables d'environnement
# Niveau 3 : niveau Étape (seule l'étape actuelle peut y accéder)
env:
STEP_VAR: bonjour
run: |
echo "Nom de l'application : $APP_NAME" # Accéder à la variable de niveau workflow
echo "Mode de build : $BUILD_MODE" # Accéder à la variable de niveau job
echo "Variable d'étape : $STEP_VAR" # Accéder à la variable de niveau étape
echo "Version de Node : $NODE_VERSION"

2. Variables intégrées de GitHub (contexte github)

GitHub Actions fournit un ensemble de variables de contexte intégrées, accessibles partout via${{ }}Référence de syntaxe :

Exemple

span style="color: #0053A6;">
steps:
- name: Afficher les variables intégrées courantes
run: |
echo "Nom du dépôt : ${{ github.repository }}" # Par exemple : your-user/your-repo
echo "Événement déclencheur : ${{ github.event_name }}" # p. ex. : push, pull_request
echo "Branche actuelle : ${{ github.ref_name }}" # p. ex. : main, develop
echo "Submit SHA：${{ github.sha }}" # valeur de hachage SHA complète de la soumission actuelle
echo "Committer: ${{ github.actor }}" # nom d'utilisateur qui a déclenché ce Workflow
echo "Working directory: ${{ github.workspace }}" # chemin du répertoire où se trouve le code après le checkout
echo "Run ID：${{ github.run_id }}" # ID unique de chaque exécution du Workflow
echo "RuneditNumber：${{ github.run_number }}" # nombre d'exécutions de ce Workflow

3. Secrets (gestion des informations sensibles)

Les informations sensibles telles que les mots de passe, les clés API, les adresses de serveur, etc.Ne peuvent pas être écrites directement dans le fichier yml.(Parce que le code est public), elles doivent être stockées dans les Secrets du dépôt GitHub.

Étapes de configuration : accédez à la page du dépôt →Paramètres → Secrets et variables → Actions→ Cliquez surNouveau secret de dépôtrenseignez le nom et la valeur, puis enregistrez.

Exemple

span style="color: #0053A6;">
steps:
# Dans l'étape, référencez le Secret configuré via ${{ secrets.secret_name }}
# Les valeurs de secret sont automatiquement masquées avec *** dans les journaux et ne seront pas divulguées
- name: Déployer sur le serveur
env:
SSH_KEY: ${{ secrets.SSH_PRIVATE_KEY }} # Clé privée SSH du serveur
SERVER_IP: ${{ secrets.DEPLOY_SERVER_IP }} # Adresse IP du serveur
run: |
echo "$SSH_KEY" > ~/.ssh/id_rsa
chmod 600 ~/.ssh/id_rsa
ssh user@$SERVER_IP "cd /app && git pull && pm2 restart all"

# GitHub fournit automatiquement GITHUB_TOKEN pour opérer sur ce dépôt (par exemple, pousser du code, créer des versions)
# Pas besoin de le créer manuellement, il suffit de l'utiliser directement
- name: Pousser les modifications vers le dépôt
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add .
git commit -m "Mise à jour automatique [skip ci]"
git push
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # GitHub le fournit automatiquement, pas besoin de le créer manuellement

Introduction aux Actions courantes

GitHub officiel et la communauté fournissent un grand nombre d'Actions prêtes à l'emploi, grâce àuses: action名称@版本des références, vous pouvez éviter d'écrire de manière répétée des opérations courantes.

1. actions/checkout (récupérer le code)

Presque la première étape de chaque Workflow consiste à récupérer le code du dépôt, en utilisant l'action officielleactions/checkout：

Exemple

span style="color: #0053A6;">
steps:
# L'utilisation la plus basique : récupérer le code le plus récent de la branche actuelle dans le répertoire de travail
- uses: actions/checkout@v4

# Utilisation avancée : personnaliser en passant des paramètres avec 'with'
- uses: actions/checkout@v4
with:
ref: develop # Récupérer la branche spécifiée (par défaut, récupère la branche où se trouve l'événement déclencheur)
fetch-depth: 0 # Récupérer tout l'historique git (par défaut, seul le dernier commit est récupéré)
# Définir à 0 pour récupérer tout l'historique, afin que des commandes comme git log puissent fonctionner correctement.
submodules: true # Initialiser et mettre à jour également les sous-modules git

2. actions/setup-node (configurer l'environnement Node.js)

Exemple

span style="color: #0053A6;">
steps:
- uses: actions/checkout@v4

- name: Configurer l'environnement Node.js
uses: actions/setup-node@v4
with:
node-version: '20' # Spécifier la version de Node.js

# Une fois la configuration terminée, les commandes npm et node peuvent être utilisées directement
- run: node --version
- run: npm install
- run: npm test

3. actions/setup-python (configurer l'environnement Python)

Exemple

span style="color: #0053A6;">
steps:
- uses: actions/checkout@v4

- name: Configurer l'environnement Python
uses: actions/setup-python@v5
with:
python-version: '3.11' # Spécifier la version de Python

- name: Installer les dépendances
run: pip install -r requirements.txt

- name: Exécuter les tests
run: pytest tests/

4. actions/cache (mettre en cache les dépendances pour accélérer les builds)

Télécharger les dépendances à chaque exécution du workflow peut être lent. L'utilisation de l'Action cache permet de mettre les dépendances en cache et de les utiliser directement lors de la prochaine exécution, ce qui réduit considérablement le temps de build :

Exemple

span style="color: #0053A6;">
steps:
- uses: actions/checkout@v4

- uses: actions/setup-node@v4
with:
node-version: '20'

- name: Mettre en cache node_modules
uses: actions/cache@v4
with:
path: ~/.npm # Spécifier le répertoire à mettre en cache
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
# key: identifiant unique pour le cache
# hashFiles('**/package-lock.json'): générer une valeur de hachage basée sur le contenu du fichier de verrouillage
# Si le fichier de verrouillage est inchangé, la clé est inchangée et le cache est directement utilisé ; si le fichier de verrouillage change, les dépendances sont réinstallées.

restore-keys: |
${{ runner.os }}-node-
# restore-keys : stratégie de correspondance de secours lorsque la clé ne correspond pas, en utilisant le cache valide le plus récent

- run: npm ci # npm ci est plus adapté aux scénarios CI que npm install, plus rapide et plus strict
- run: npm test

5. actions/upload-artifact / download-artifact (transférer des fichiers entre les jobs)

Des jobs différents s'exécutent sur des machines virtuelles indépendantes, donc les fichiers ne peuvent pas être partagés directement. En utilisant des artefacts, vous pouvez transmettre les fichiers de sortie d'un job à un autre job :

Exemple

span style="color: #0053A6;">
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm install && npm run build # Les artefacts de build seront générés dans le répertoire ./dist

- name: Téléverser les artefacts de build
uses: actions/upload-artifact@v4
with:
name: dist-files # Nom de l'artefact (référencé par ce nom lors du téléchargement)
path: ./dist # Le répertoire ou le chemin de fichier à téléverser
retention-days: 7 # Jours de conservation de l'artefact (max 90 jours)

deploy:
runs-on: ubuntu-latest
needs: build # Exécuter après la fin du job build
steps:
- name: Télécharger les artefacts de build
uses: actions/download-artifact@v4
with:
name: dist-files # Identique au nom lors du téléversement
path: ./dist # Répertoire de téléchargement en local

- name: Fichier de déploiement
run: rsync -avz ./dist/ user@server:/var/www/html/

Builds matriciels (Matrix)

Les builds matriciels vous permettent d'exécuter une seule configuration de job sur plusieurs environnements en parallèle, couramment utilisés pour les tests de compatibilité entre versions et systèmes d'exploitation :

Exemple

span style="color: #0053A6;">
jobs:
test:
name: Tester Node ${{ matrix.node-version }} sur ${{ matrix.os }}
runs-on: ${{ matrix.os }} # Lire l'environnement d'exécution à partir des variables de la matrice

strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest] # 3 Systèmes d'exploitation
node-version: ['18', '20', '22'] # 3 versions de Node
# Les combinaisons ci-dessus produisent 3 × 3 = 9 jobs parallèles

fail-fast: false # Par défaut true : annule tous les jobs restants si un job échoue.
# Défini sur false : même si une combinaison échoue, les autres combinaisons continuent de s'exécuter,
# Pratique pour voir les résultats des tests pour tous les environnements

steps:
- uses: actions/checkout@v4

- name: Configurer Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }} # Référencer les variables de matrice

- run: npm ci
- run: npm test

Exemple

# Utilisation avancée : utilisez exclude pour exclure certaines combinaisons non souhaitées, et include pour ajouter des configurations spéciales
strategy:
matrix:
os: [ubuntu-latest, windows-latest]
node-version: ['18', '20']
exclude:
- os: windows-latest
node-version: '18' # Exclure la combinaison Windows + Node 18

include:
- os: ubuntu-latest
node-version: '20'
experimental: true # Ajouter des variables supplémentaires pour des combinaisons spécifiques (peuvent être référencées dans les étapes en utilisant matrix.experimental)

Exemples pratiques

Exemple 1 : CI du projet Node.js (tests automatisés)

À chaque fois que du code est poussé ou qu'une PR est créée, installez automatiquement les dépendances et exécutez les vérifications de code et les tests :

Exemple

# .github/workflows/ci.yml
name: Node.js CI

sur:
push:
branches: [main, develop]
pull_request:
branches: [main]

jobs:
test:
name: CodeChecksandTesting
runs-on: ubuntu-latest

steps:
- name: Récupérer le code
uses: actions/checkout@v4

- name: Configurer l'environnement Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm' # setup-node dispose d'une prise en charge intégrée de la mise en cache, plus concise que d'utiliser l'action cache séparément

- name: Installer les dépendances
run: npm ci # npm ci effectuera l'installation strictement selon package-lock.json,
# Plus adapté aux scénarios CI que npm install

- name: Exécuter le linting du code (ESLint)
run: npm run lint

- name: Exécuter les tests unitaires
run: npm test -- --coverage # Générer aussi le rapport de couverture des tests

- name: Téléverser le rapport de couverture
uses: actions/upload-artifact@v4
if: always() # Téléverser le rapport que le test réussisse ou non (pour faciliter la consultation des causes d'échec)
with:
name: coverage-report
path: ./coverage

Exemple 2 : CI de projet Python

Exemple

# .github/workflows/python-ci.yml
name: CI Python

sur:
push:
branches: [main]
pull_request:

jobs:
test:
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v4

- name: Configurer l'environnement Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
cache: 'pip' # Mettre en cache les dépendances pip

- name: Installer les dépendances
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt
pip install flake8 pytest # Installer les outils de linting et de test du code

- name: Exécuter la vérification du format de code (flake8)
run: |
# Vérifier les erreurs de syntaxe et les variables non définies (séries E9, F63, F7, F82), et quitter directement avec une erreur si un problème est détecté
flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
# Vérifier le style de code (longueur maximale de ligne 120), compter uniquement le nombre de problèmes, ne pas quitter avec une erreur.
flake8 . --count --max-line-length=120 --statistics

- name: Exécuter les tests
run: pytest tests/ -v # -v affiche les résultats détaillés des tests

Exemple 3 : Construire et pousser une ou plusieurs images Docker

Exemple

# .github/workflows/docker.yml
name: Construire et pousser une image Docker

sur:
push:
branches: [main]
tags:
- 'v*' # Se déclenche lors du push de tags commençant par v, tels que v1.0.0

jobs:
docker:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

# Utiliser l’action officielle Docker metadata pour générer automatiquement les tags d’image.
# Par exemple, lors du push du tag v1.2.3, générer automatiquement plusieurs tags tels que 1.2.3, 1.2, 1, latest
- name: Extraire les métadonnées Docker (tags d’image, etc.)
id: meta # Définir un ID pour cette étape afin que les étapes suivantes puissent référencer sa sortie.
uses: docker/metadata-action@v5
with:
images: your-dockerhub-username/your-image-name

- name: Se connecter à Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }} # Utilisez un jeton d'accès au lieu d'un mot de passe pour une meilleure sécurité

- name: Construire et pousser l'image
uses: docker/build-push-action@v5
with:
context: . # Répertoire où se trouve le Dockerfile (répertoire courant)
push: true # true : pousser vers le registre après la fin de la construction
tags: ${{ steps.meta.outputs.tags }} # Référence la liste des tags générée par l'étape meta
labels: ${{ steps.meta.outputs.labels }} # Référence les informations de tag générées par l'étape meta

Exemple 4 : Déployer automatiquement sur un serveur après le build

Exemple

# .github/workflows/deploy.yml
name: Compiler et déployer

sur:
push:
branches: [main] # Déploiement déclenché uniquement lors d'un push sur la branche main

jobs:
build-and-deploy:
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v4

- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'

- name: Installer les dépendances et structurer le build
run: |
npm ci
npm run build # Les artefacts de build sont générés dans le répertoire ./dist

- name: Déployer sur le serveur via SSH
uses: appleboy/[email protected] # Action SSH tierce, pas besoin de configurer SSH manuellement
with:
host: ${{ secrets.SERVER_HOST }} # IP ou domaine du serveur
username: ${{ secrets.SERVER_USER }} # Nom d'utilisateur de connexion SSH
key: ${{ secrets.SSH_PRIVATE_KEY }} # Contenu de la clé privée SSH (correspondant à la clé publique sur le serveur)
port: 22 # Port SSH, par défaut 22
script: |
# Les commandes suivantes sont exécutées sur le serveur distant
cd /var/www/my-app
git pull origin main
npm ci --production
pm2 restart my-app # Redémarrer l'application Node.js avec pm2
echo "Déploiement terminé : $(date)"

Exemple 5 : tâche planifiée (sauvegarde automatique de la base de données)

Exemple

# .github/workflows/backup.yml
name: décider quand sauvegarder la base de données

sur:
schedule:
- cron: '0 2 * * *' # Exécuter quotidiennement à 02:00 UTC (10:00 heure de Pékin)
workflow_dispatch: # Prend également en charge le déclenchement manuel pour les sauvegardes temporaires

jobs:
backup:
runs-on: ubuntu-latest

steps:
- name: Exécuter le script de sauvegarde via SSH
uses: appleboy/[email protected]
with:
host: ${{ secrets.SERVER_HOST }}
username: ${{ secrets.SERVER_USER }}
key: ${{ secrets.SSH_PRIVATE_KEY }}
script: |
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="/backup/db_$TIMESTAMP.sql"

# Effectuer la sauvegarde de la base de données
mysqldump -u root -p${{ secrets.DB_PASSWORD }} my_database > $BACKUP_FILE

# Compresser les fichiers de sauvegarde
gzip $BACKUP_FILE

# Supprimer les fichiers de sauvegarde datant de plus de 30 jours pour éviter que le disque ne se remplisse
find /backup -name "*.sql.gz" -mtime +30 -delete

echo "Sauvegarde terminée : ${BACKUP_FILE}.gz"

Astuces de débogage

1. Activation des journaux de débogage

Lorsqu'une exécution de workflow échoue mais que les informations du journal sont insuffisantes, vous pouvez activer le mode de débogage détaillé. Méthode : accédez au dépôtParamètres → Secrets et variables → Actions, ajoutez les deux Secrets suivants (définissez les deux valeurs surtrue）：

ACTIONS_RUNNER_DEBUGActiver les journaux détaillés du runner
ACTIONS_STEP_DEBUG: Activer la journalisation de débogage détaillée pour chaque étape.

2. Affichage des informations de contexte pour faciliter le dépannage

Exemple

span style="color: #0053A6;">
steps:
- name: Afficher toutes les informations de contexte (pour le débogage ; à ajouter lors du dépannage, à supprimer après résolution)
run: |
echo "=== github context ==="
echo '${{ toJson(github) }}' # toJson() convertira le format d'objet en sortie de chaîne JSON
echo "=== env context ==="
echo '${{ toJson(env) }}'
echo "=== job context ==="
echo '${{ toJson(job) }}'

3. Test local du Workflow (avec act)

Tester le Workflow seulement en poussant du code à chaque fois est très inefficace.actest un outil open source qui peut simuler l'exécution de GitHub Actions localement, ce qui améliore grandement l'efficacité de débogage :

# 安装 act（需要本地已安装 Docker）
# macOS
brew install act

# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# 在仓库根目录运行所有 Workflow
act

# 只运行指定事件触发的 Workflow
act push

# 只运行指定的 Job
act -j build

Lors de l'exécution de tests locaux,actIl utilise des conteneurs Docker pour simuler l'environnement d'exécution GitHub, mais certaines Actions (telles queactions/cache) peuvent se comporter différemment lorsqu'elles sont simulées localement par rapport à l'environnement réel. Les résultats finaux dépendent de ce qui s'exécute réellement sur GitHub.

Problèmes courants et notes

1. Problème de permissions (Permission refusée)

Si le Workflow doit pousser du code vers le dépôt ou effectuer des opérations sur les Issues, vous devez déclarer explicitement les permissions dans le fichier de configuration :

Exemple

# Définir les permissions au niveau supérieur du Workflow ou au niveau du Job
permissions:
contents: write # Autorise la lecture/l'écriture du contenu du dépôt (code, fichiers)
issues: write # Autoriser la création et la modification des Issues
pull-requests: write # Autoriser les opérations sur les Pull Requests

# Principe du moindre privilège : n'accorder que les permissions réellement nécessaires, le reste est par défaut read ou none

2. Éviter les déclenchements en boucle du Workflow

Si le Workflow pousse automatiquement du code vers le dépôt, il peut déclencher un nouvel événement push, provoquant une boucle infinie. Solution : dans le message de commit du commit automatique, ajoutez[skip ci]mot-clé, et GitHub ignorera le déclenchement du Workflow pour ce commit :

git commit -m "自动格式化代码 [skip ci]"

3. Échappement des caractères spéciaux YAML

DansrunDans la commande Shell du champ, utilisez${{ }}expression, si l'expression contient un deux-points (:) et d'autres caractères spéciaux YAML, vous devez entourer toute la valeur de guillemets, ou, à la place, l'affecter d'abord à une variable d'environnement puis l'utiliser:

Exemple

span style="color: #0053A6;">
steps:
# Non recommandé : intégrer directement des commandes complexes dans les expressions ${{ }} peut provoquer des erreurs d'analyse YAML.
- run: echo ${{ github.event.pull_request.title }}

# Recommandé : affectez d'abord la valeur à une variable d'environnement, puis utilisez la variable d'environnement dans Shell
- name: Afficher le titre de la PR
env:
PR_TITLE: ${{ github.event.pull_request.title }}
run: echo "Titre de la PR : $PR_TITLE"

Pour une documentation plus complète, veuillez consulter la documentation officielle :https://docs.github.com/zh/actions

autres extensions