Flux de travail d'agent GitHub : Automatisation intelligente des dépôts avec le langage naturel

Si vous utilisez encore des fichiers YAML GitHub Actions traditionnels, en écrivant manuellement if: success() et steps pour gérer l'automatisation de votre dépôt de code, vous pourriez être en retard. Au cours des derniers mois, la tendance technologique la plus digne d'intérêt sur GitHub n'a pas été un nouveau framework, mais une toute nouvelle approche de l'automatisation : les flux de travail d'agent.

Cela change subtilement la façon dont les développeurs interagissent avec les dépôts de code. Imaginez que vous puissiez simplement écrire une description Markdown en langage naturel, telle que "Vérifiez l'activité du dépôt quotidiennement et générez un rapport d'état", et que le système comprenne automatiquement le contexte, analyse les données et crée une Issue contenant une analyse détaillée. Ce n'est plus un scénario de science-fiction, mais la capacité principale des flux de travail d'agent GitHub officiellement introduits par GitHub.

Contrairement à l'automatisation traditionnelle qui repose sur des règles fixes "si-alors", les flux de travail d'agent intègrent des agents de codage IA (tels que GitHub Copilot, Claude, GPT-4) dans le moteur d'exécution de GitHub Actions. Il ne s'agit plus simplement "d'exécuter des scripts", mais d'avoir la capacité de "comprendre les intentions, analyser le contexte et prendre des décisions". Cela signifie que le seuil de création de scripts d'automatisation est considérablement abaissé, passant de l'écriture de scripts YAML et Shell complexes à la description des tâches en langage humain.

Pourquoi dit-on que cela "commence à être appliqué" ? Parce que cette technologie est passée de la preuve de concept à la phase de préversion publique, avec des projets open source pertinents, des meilleures pratiques et des discussions communautaires qui émergent rapidement sur GitHub. Pour les petites et moyennes équipes et les développeurs individuels, cela signifie qu'ils peuvent automatiser les tâches de maintenance de dépôt répétitives, triviales mais nécessitant un jugement intelligent, à un coût très faible, telles que la classification automatique des Issues, l'enquête sur les raisons des échecs de CI, la synchronisation de la documentation avec le code, la génération de rapports hebdomadaires, etc.

Cet article vous guidera à travers une compréhension approfondie des principes fondamentaux des flux de travail d'agent GitHub et, grâce à un exemple pratique complet de zéro, vous montrera comment l'utiliser pour créer un "robot intelligent de rapport d'état de dépôt quotidien". Vous verrez que la prochaine étape de l'exploitation automatisée ne sera pas plus de YAML, mais des conversations plus intelligentes.

1. Le véritable problème résolu par cet article : le saut de l'"exécution de script" à la "compréhension de l'intention" dans l'automatisation

Dans l'automatisation DevOps traditionnelle, nous sommes confrontés à une contradiction fondamentale : la détermination des règles versus l'ambiguïté des scénarios. Prenons GitHub Actions comme exemple, nous écrivons des fichiers YAML pour définir les conditions de déclenchement (on: push) et une série d'étapes (steps). Ce système est très puissant, mais ses limites de capacité sont liées à la logique que nous avons écrite à l'avance.

Par exemple, vous souhaitez implémenter la fonctionnalité "répondre automatiquement aux Issues". Dans la méthode traditionnelle, vous auriez besoin de :

Écrire des expressions régulières ou des règles de correspondance de mots-clés pour identifier les types d'Issues.
Pré-définir des modèles de réponse pour chaque type.
Gérer divers cas limites et entrées inattendues.

Une fois qu'un cas non couvert par les règles est rencontré (par exemple, l'utilisateur décrit le même problème d'une autre manière), l'automatisation échoue. Cela conduit au fait que de nombreuses tâches "semi-structurées" qui pourraient être automatisées ne sont toujours pas traitées manuellement en raison de la complexité trop élevée de l'écriture et de la maintenance des règles.

Ce que les flux de travail d'agent GitHub visent à résoudre, c'est précisément ce problème d'intelligence du "dernier kilomètre". Il introduit une nouvelle couche d'abstraction : l'agent IA. Vous n'avez plus besoin de dire à la machine "si le titre contient 'bug', ajoutez l'étiquette bug", mais plutôt de lui dire : "Veuillez analyser l'Issue nouvellement créée, déterminer s'il s'agit d'une demande de fonctionnalité, d'un rapport de bug ou d'un problème de documentation en fonction du contenu, et attribuez-lui les étiquettes et la priorité appropriées."

La nature de ce changement est la suivante : le rédacteur de la logique d'automatisation passe de "programmeur" à "chef de produit" ou "chef d'équipe". Vous êtes responsable de définir "ce qu'il faut faire" (What) et "quels critères atteindre" (Criteria), tandis que l'agent IA est responsable de résoudre le problème "comment le faire" (How). Il génère dynamiquement des jugements et des actions d'exécution en analysant le contenu complet de l'Issue, les Issues similaires historiques, le contexte du code, etc.

Pour les développeurs individuels, cela signifie que vous pouvez consacrer plus de temps au codage créatif et à la conception d'architecture, plutôt qu'à la maintenance de ces scripts d'automatisation fastidieux. Pour les équipes, cela signifie que le processus de maintainance du dépôt de code peut être plus standardisé et plus rapide, réduisant les problèmes causés par les retards ou les négligences humaines.

2. Concepts de base et principes fondamentaux : Comment fonctionnent les flux de travail d'agent ?

Pour comprendre les flux de travail d'agent, nous devons décomposer plusieurs concepts clés et examiner les différences fondamentales avec les flux de travail GitHub Actions traditionnels.

2.1 Analyse des composants clés

Agent IA (Agent) : C'est le "cerveau" du flux de travail. Il s'agit d'un modèle d'IA capable de comprendre le langage naturel, d'analyser le contexte du dépôt de code (tels que les fichiers, l'historique des commits, les Issues, les PRs) et d'exécuter des tâches de programmation (telles que la lecture/écriture de fichiers, l'appel d'API, la création d'Issues). Les flux de travail d'agent GitHub prennent en charge plusieurs moteurs d'agent, notamment GitHub Copilot, Anthropic Claude, OpenAI Codex et Google Gemini.
Fichier de flux de travail d'agent (.md) : C'est le fichier de définition de la tâche. Ce n'est pas un fichier YAML, mais un fichier Markdown. Le fichier est divisé en deux parties :
- Frontmatter (Préface) : Bloc YAML situé entre ---, utilisé pour définir les métadonnées et les garde-fous de sécurité du flux de travail. Il comprend les déclencheurs (on), les autorisations (permissions), l'ensemble des outils utilisés (tools), les sorties sécurisées autorisées (safe-outputs) et le plafond des crédits IA (max-ai-credits), etc.
- Corps Markdown : Ce sont les instructions en langage naturel pour l'agent IA. Vous utilisez le langage humain pour décrire l'objectif de la tâche, les étapes et le format de sortie attendu.
Fichier verrouillé compilé (.lock.yml) : Lorsque vous poussez le fichier de flux de travail .md dans le dépôt, GitHub le compile en un fichier de flux de travail GitHub Actions standard et renforcé (avec l'extension .lock.yml). Ce fichier est en lecture seule, garantissant la sécurité et la cohérence de la définition du flux de travail et empêchant les modifications malveillantes.
Sorties sécurisées (Safe Outputs) : C'est l'un des mécanismes de sécurité les plus importants. Dans le Frontmatter, vous devez explicitement déclarer quelles opérations "d'écriture" le flux de travail est autorisé à exécuter, telles que create-issue, create-comment, create-pull-request. L'agent IA ne peut produire des résultats que via les canaux "sorties sécurisées" approuvés, et le contenu de la sortie subit un scan de détection des menaces pour empêcher la génération de code malveillant ou de contenu inapproprié.

2.2 Comparaison avec les flux de travail traditionnels

Pour une compréhension plus intuitive, nous utilisons un tableau pour comparer les deux :

Dimension des caractéristiques	Flux de travail GitHub Actions traditionnel	Flux de travail d'agent GitHub
Méthode de définition	Fichier YAML, écriture d'`steps` spécifiques (par exemple, `run: \|` pour exécuter des commandes shell).	Fichier Markdown (`.md`) avec instructions en langage naturel et Frontmatter YAML pour les métadonnées et la sécurité.
Cœur de la logique	Logique de script déterministe et linéaire. Repose sur des jugements conditionnels `if`.	Raisonnement contextuel et prise de décision basés sur des modèles d'IA.
Flexibilité	Faible. Les changements de scénario nécessitent de réécrire ou de modifier le YAML.	Élevée. L'IA peut s'adapter à une certaine gamme de changements de scénario et de descriptions ambiguës.
Seuil de développement	Élevé. Nécessite une familiarité avec la syntaxe YAML, les scripts Shell et l'écosystème GitHub Actions.	Faible. Il suffit de pouvoir décrire clairement la tâche en langage naturel.
Sécurité	Contrôlée via `permissions` et revue de code. Les scripts eux-mêmes peuvent contenir des opérations risquées.	Protection multicouche : lecture seule par défaut, liste blanche de sorties sécurisées, détection des menaces, exécution dans des conteneurs pare-feu.
Scénarios applicables	Tâches de pipeline fortement déterministes telles que la construction, les tests et le déploiement.	Tâches nécessitant un jugement cognitif telles que la classification des Issues, l'analyse des échecs de CI, la synchronisation de la documentation, la génération de rapports.

Diagramme de flux de travail :

Développeur écrit le fichier `.md` (instructions en langage naturel + garde-fous YAML)
        ↓
   Soumission au dépôt GitHub
        ↓
GitHub compile automatiquement pour générer le fichier `.lock.yml` (flux de travail Actions standard)
        ↓
    L'événement de déclenchement se produit (par exemple, tâche planifiée, création d'Issue)
        ↓
GitHub Actions Runner démarre le Job
        ↓
   À l'intérieur du Job : l'agent IA est activé
        ↓
L'agent lit les instructions, analyse le contexte du dépôt (code, Issues, PRs, etc.)
        ↓
L'agent effectue un raisonnement, une prise de décision et prépare l'exécution de l'action
        ↓
  L'action passe le contrôle des "sorties sécurisées" et la détection des menaces
        ↓
    Contrôle réussi → Exécute l'action (par exemple, création d'Issue)
    Échec du contrôle → Le flux de travail échoue, sortie du journal

En termes simples, Agent Workflow insère une "couche de décision IA" dans le pipeline CI/CD traditionnel. Cette couche de décision reçoit des instructions en langage naturel et le contexte du dépôt, et produit des opérations structurées, transformant ainsi des exigences ambiguës en actions automatisées déterminées.

3. Préparation de l'environnement et conditions préalables

Avant de commencer à créer votre premier flux de travail d'agent, vous devez vous assurer que les conditions suivantes sont remplies. La plupart de ces conditions sont similaires à celles de l'utilisation de GitHub Copilot.

3.1 Exigences de compte et d'abonnement

Compte GitHub : Un compte GitHub valide est la base.
Abonnement GitHub Copilot (recommandé) : Bien que les flux de travail d'agent prennent en charge les moteurs IA tiers (tels que Claude, GPT-4), GitHub Copilot est le moteur par défaut et le plus intégré. Pour une expérience optimale, vous avez besoin d'un abonnement GitHub Copilot valide (personnel, équipe ou entreprise). Les développeurs individuels peuvent demander un essai gratuit.
Actions GitHub activées : Le dépôt de code cible doit avoir les Actions GitHub activées. Ceci est généralement défini par défaut.

3.2 Outils de développement locaux (facultatif mais recommandé)

Pour créer, tester et gérer plus facilement les flux de travail d'agent, il est recommandé d'installer les outils suivants :

GitHub CLI ( gh ) : C'est l'outil de ligne de commande officiel pour interagir avec GitHub. Nous l'utiliserons pour compiler et exécuter les flux de travail d'agent.
- Installation : Accédez au site officiel de GitHub CLI pour télécharger et installer.
- Authentification : Après l'installation, exécutez gh auth login dans le terminal et suivez les instructions pour vous connecter et autoriser.

3.3 Dépôt de code cible

Préparez un dépôt GitHub auquel vous avez des droits d'écriture. Il peut s'agir d'un dépôt public ou privé. Nous créerons le flux de travail d'agent dans ce dépôt.

En résumé : Vous avez besoin d'un compte GitHub + abonnement Copilot + un dépôt de test. L'installation locale de l'outil CLI gh facilitera les opérations futures.

4. Décomposition du processus principal : Création de votre premier flux de travail d'agent

Apprenons à travers un scénario pratique : créer un rapport d'état de dépôt quotidien pour le dépôt. Ce flux de travail s'exécutera une fois par jour, analysera l'activité du dépôt au cours des dernières 24 heures (PRs fusionnés, Issues fermées, nouvelles discussions, etc.) et créera automatiquement une Issue récapitulative.

4.1 Première étape : Planifier la structure du flux de travail

Avant de commencer à écrire du code, clarifions les éléments clés du flux de travail :

Déclencheur (Quand) : S'exécute une fois par jour. Correspond à on: daily.
Autorisations (Ce qu'il peut faire) : Nécessite la lecture du contenu du dépôt (contents: read), des Issues (issues: read) et des Pull Requests (pull-requests: read). Comme il doit créer des Issues, il a besoin de l'autorisation d'écrire des requêtes Copilot (copilot-requests: write).
Description de la tâche (Ce qu'il faut faire) : Dites à l'IA en langage naturel : "Révisez l'activité récente du dépôt, créez une Issue résumant les changements des dernières 24 heures, y compris les PRs fusionnés, les Issues fermées, les nouvelles discussions, identifiez les blocages ou les problèmes ouverts mentionnés dans les commentaires, et fournissez des suggestions aux mainteneurs."
Sorties sécurisées (Ce qu'il peut écrire) : Nous l'autorisons uniquement à créer des Issues. Correspond à safe-outputs: create-issue.

4.2 Deuxième étape : Écrire le fichier Markdown du flux de travail d'agent

Dans le répertoire racine de votre dépôt local, créez un nouveau dossier .github/agent-workflows/ (il s'agit d'un répertoire conventionnel). Créez ensuite le fichier daily-report.md dans ce répertoire.

# Chemin du fichier : .github/agent-workflows/daily-report.md

---
on: daily
permissions:
  contents: read
  issues: read
  pull-requests: read
  copilot-requests: write
network: defaults
tools:
  github:
    toolsets: [default]
safe-outputs:
  create-issue:
---
# Rapport d'état quotidien du dépôt

Veuillez analyser l'activité de ce dépôt de code au cours des dernières 24 heures.

Votre tâche consiste à créer une Issue GitHub claire et concise résumant ce qui suit :

1.  <strong>Modifications du code</strong> :
    *   Quels Pull Requests ont été fusionnés ? Listez le numéro, le titre et les principaux contributeurs de chaque PR.
    *   Quelles nouvelles fonctionnalités ou corrections ces fusions ont-elles introduites ?

2.  <strong>Suivi des problèmes</strong> :
    *   Quelles Issues ont été fermées ? Listez le numéro et le titre.
    *   Quelles nouvelles Issues ont été créées ? Décrivez brièvement leur type (Bug, demande de fonctionnalité, question, etc.) et leur priorité (si déterminable à partir des étiquettes).

3.  <strong>Discussions et collaboration</strong> :
    *   Dans les commentaires des Issues ou des Pull Requests, des <strong>blocages</strong> ou des <strong>problèmes en suspens</strong> (open questions) ont-ils été mentionnés ? Veuillez extraire les points clés.
    *   De nouvelles discussions ont-elles été lancées ? Quel était le sujet ?

4.  <strong>Progrès et suggestions</strong> :
    *   Sur la base de l'activité récente, quels progrès le projet a-t-il réalisés vers ses objectifs visibles ?
    *   Proposez 1 à 3 <strong>suggestions d'actions concrètes</strong> pour les mainteneurs du dépôt (par exemple : PRs nécessitant une révision, Bugs à traiter en priorité, discussions à suivre).

<strong>Exigences de style du rapport</strong> :
*   Format du titre : `[Rapport Quotidien] YYYY-MM-DD Résumé de l'activité du dépôt`
*   Utilisez la syntaxe Markdown pour rendre le rapport facile à lire (par exemple, listes, gras).
*   Ajustez le niveau de détail en fonction du volume d'activité. S'il y a peu d'activité, un résumé bref suffit ; s'il y a beaucoup d'activité, veuillez diviser en sections et mettre en évidence les points clés.
*   Maintenez un ton objectif et professionnel.

Explication des parties clés :

on: daily : C'est un déclencheur simplifié spécifique aux flux de travail d'agent, indiquant qu'il s'exécute à 00h00 UTC tous les jours. Il prend également en charge des événements tels que on: issue_opened.
copilot-requests: write : Cette autorisation est nécessaire pour utiliser Copilot comme moteur IA afin d'effectuer des opérations d'écriture (telles que la création d'Issues).
safe-outputs: create-issue: : Cela déclare que la seule opération d'écriture autorisée pour ce flux de travail est "la création d'Issue". C'est une liste blanche de sécurité.
Corps Markdown : Cette partie est le "mode d'emploi" pour l'IA. Plus il est clair et structuré, plus le résultat d'exécution de l'IA sera conforme aux attentes. Nous avons clairement défini les quatre sections du rapport et les exigences de format spécifiques.

4.3 Troisième étape : Compiler le fichier de flux de travail

Le fichier .md du flux de travail d'agent ne peut pas être exécuté directement. Il doit d'abord être compilé en un fichier .lock.yml reconnaissable par GitHub Actions.

Utilisez GitHub CLI pour effectuer cette étape. Dans le répertoire du dépôt contenant .github/agent-workflows/daily-report.md, ouvrez un terminal et exécutez :

# Assurez-vous que vous êtes dans le répertoire du dépôt et que vous vous êtes authentifié via gh auth login
gh agent-workflow compile .github/agent-workflows/daily-report.md

Si la commande s'exécute avec succès, vous verrez un nouveau fichier généré dans le même répertoire : .github/agent-workflows/daily-report.lock.yml. Ce fichier est généré automatiquement, ne le modifiez pas manuellement. Son contenu est une définition de flux de travail GitHub Actions standard, mais il intègre la logique d'appel d'agents IA.

4.4 Quatrième étape : Valider et pousser les fichiers

Soumettez le fichier .md nouvellement créé et le fichier .lock.yml compilé dans votre dépôt.

# Ajouter les fichiers
git add .github/agent-workflows/

# Valider les changements
git commit -m "feat: add daily repo status agent workflow"

# Pousser vers le dépôt distant (par exemple, la branche main)
git push origin main

Important : Les fichiers de flux de travail d'agent doivent être situés dans la branche par défaut du dépôt (généralement main ou master) pour être efficaces.

4.5 Cinquième étape : Déclencher et exécuter le flux de travail

Une fois le flux de travail soumis, plusieurs façons de le déclencher :

Attendre le déclenchement programmé : Comme nous avons défini on: daily, il s'exécutera automatiquement à la prochaine heure UTC zéro.
Déclenchement manuel (recommandé pour les tests) :
- Sous l'onglet Actions de la page du dépôt GitHub, trouvez la liste des flux de travail nommée "Agent Workflow" ou un nom similaire. Vous devriez voir Daily Repo Status Report.
- Cliquez sur ce flux de travail, puis cliquez sur le bouton "Run workflow", sélectionnez la branche, puis exécutez-le manuellement.
Utiliser le déclencheur CLI : ``` gh workflow run "Daily Repo Status Report" --ref main

Une fois le flux de travail en cours d'exécution, vous pouvez voir les journaux en temps réel dans la page Actions. Les journaux afficheront l'agent IA analysant le contexte du dépôt, effectuant un raisonnement et exécutant finalement l'action de création d'Issue.

5. Résultats d'exécution et validation des effets

Une fois que le flux de travail s'exécute avec succès, comment pouvons-nous vérifier s'il fonctionne comme prévu ?

5.1 Vérifier les journaux d'exécution des Actions

Accédez à l'onglet Actions du dépôt, cliquez sur le dernier enregistrement d'exécution de daily-report. Dans les journaux, vous verrez des points clés similaires à ce qui suit :

Job Summary
Starting agent for workflow: .github/agent-workflows/daily-report.md
Initializing AI context with repository data...
Analyzing repository activity for the past 24 hours...
Found 3 merged pull requests, 2 closed issues, 1 new discussion.
Generating summary report...
Performing safety check on proposed output...
Safety check passed. Proceeding to create issue.
Creating GitHub issue with title: "[Daily Report] 2023-10-27 Repository Activity Summary"
Issue #45 created successfully.
Job completed successfully.

Les journaux montrent clairement le processus de "réflexion" et d'exécution de l'agent IA. Si des erreurs se produisent pendant le processus (telles que des autorisations insuffisantes, un dépassement du plafond de crédits IA, un échec de détection de sécurité), elles seront également affichées ici.

5.2 Vérifier l'Issue générée

Accédez à l'onglet Issues du dépôt, vous devriez voir une nouvelle Issue créée par le robot github-actions, avec un titre au format [Rapport Quotidien] 2023-10-27 Résumé de l'activité du dépôt.

En cliquant sur cette Issue, vous verrez un rapport bien formaté généré par l'IA. Il devrait contenir toutes les sections que vous avez demandées dans votre instruction : la liste des PRs fusionnés, les Issues fermées, le résumé des nouvelles discussions, les blocages découverts et les suggestions ultérieures. La qualité du rapport dépend du volume réel d'activité du dépôt au cours des dernières 24 heures et de la clarté de votre instruction.

Un signe de validation réussi est : le contenu du rapport ne se contente pas de lister les faits, mais effectue également un certain degré de synthèse et de résumé, par exemple en regroupant plusieurs PRs pertinents sous "Mises à jour de fonctionnalités frontend" ou en notant que "la correction d'un bug a suscité une nouvelle discussion sur la compatibilité". C'est précisément la valeur fondamentale du flux de travail d'agent qui transcende les scripts simples : il fournit des informations.

5.3 Affichage des coûts et de l'utilisation

L'exécution des flux de travail d'agent entraîne des coûts, principalement composés de deux parties :

Temps d'exécution des Actions GitHub : Comme les autres flux de travail, il consomme des minutes d'Actions.
Coût d'inférence IA : Crédits "IA" consommés pour l'analyse et la génération de contenu par les modèles d'IA.

Vous pouvez utiliser GitHub CLI pour surveiller les coûts :

# Afficher les journaux des dernières exécutions de flux de travail, y compris la consommation estimée de crédits IA
gh agent-workflow logs

# Afficher les informations d'audit détaillées d'une exécution spécifique, y compris l'utilisation des jetons et l'estimation des coûts
gh agent-workflow audit <run_id>
</run_id>

Dans le Frontmatter, vous pouvez définir max-ai-credits: 500 pour limiter la consommation maximale de crédits IA par exécution, empêchant ainsi les coûts incontrôlés dus à des boucles accidentelles ou des tâches complexes.

6. Avancement approfondi : Configuration et astuces de personnalisation

Une fois que vous maîtrisez le processus de base, nous pouvons explorer davantage d'utilisations avancées pour rendre les flux de travail d'agent plus puissants et adaptés aux besoins réels.

6.1 Utilisation de différents moteurs IA

Par défaut, il utilise GitHub Copilot, mais vous pouvez également spécifier d'autres moteurs. Cela nécessite de définir le paramètre engine dans le Frontmatter et de configurer la clé API correspondante dans les Secrets du dépôt.

# .github/agent-workflows/code-review.md
---
on: pull_request
permissions:
  contents: read
  pull-requests: write
  copilot-requests: write
engine: anthropic/claude-3-5-sonnet # Spécifier l'utilisation du modèle Anthropic Claude
safe-outputs:
  create-comment:
env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} # Lire la clé du Secret du dépôt
---
# Assistant de révision de code PR
Veuillez examiner les modifications de code pour ce Pull Request. Concentrez-vous sur :
1.  Le style de code est-il conforme aux spécifications du projet ?
2.  Y a-t-il des erreurs logiques évidentes ou des bugs potentiels ?
3.  Y a-t-il des opportunités d'amélioration des performances ?
4.  La couverture des tests est-elle suffisante ?
Veuillez proposer des commentaires dans un ton amical et constructif.

Remarque : L'utilisation de moteurs tiers entraînera des frais d'appel API supplémentaires, facturés directement par le fournisseur de services correspondant (par exemple, Anthropic, OpenAI).

6.2 Déclencheurs et conditions plus précis

En plus de daily, Agent Workflow prend en charge davantage de déclencheurs d'événements GitHub, la syntaxe est similaire à celle des Actions ordinaires :

---
# Se déclenche lorsqu'une nouvelle Issue est créée
on:
  issues:
    types: [opened]

# Se déclenche lorsqu'un PR est fusionné dans la branche main
on:
  push:
    branches:
      - main

# Déclenchement manuel
on: workflow_dispatch

# Tâche planifiée, toutes les deux heures (syntaxe Cron)
on:
  schedule:
    - cron: '0 */2 * * *'

Vous pouvez également utiliser des conditions if dans le Frontmatter pour filtrer, mais il est généralement plus recommandé de laisser l'IA juger dans le corps de l'instruction.

6.3 Attribution d'autorisations et d'outils plus larges

Pour que l'agent puisse effectuer des tâches plus complexes, vous devrez peut-être lui accorder plus d'autorisations ou d'accès à des outils externes.

---
on: workflow_dispatch
permissions:
  contents: write  # Permettre l'écriture de code
  issues: write
  pull-requests: write
  deployments: read
network: defaults
tools:
  github:
    toolsets: [default, issues, projects] # Activer les jeux d'outils Issues et Projects
  curl: {} # Permettre l'utilisation de la commande curl pour appeler des API externes (à utiliser avec prudence !)
safe-outputs:
  create-issue:
  create-branch:
  create-file:
  create-pull-request:
---
# Flux de travail de mise à jour des dépendances et d'analyse de sécurité
1. Analyser les dépendances de ce dépôt (par exemple, package.json, requirements.txt).
2. Vérifier les vulnérabilités de sécurité connues (peut simuler l'appel d'API pertinentes ou analyser les rapports d'outils existants).
3. Pour les dépendances présentant des vulnérabilités à haut risque et pour lesquelles des versions de correction sont disponibles, créez automatiquement une nouvelle branche, mettez à jour le fichier de dépendances et soumettez un Pull Request.
4. Dans la description du PR, expliquez la raison de la mise à jour, le numéro CVE de la vulnérabilité impliquée et l'impact de la modification.
5. En même temps, créez une Issue pour suivre cet élément et liez ce PR.

Avertissement : L'octroi des autorisations contents: write et de l'outil curl élargit considérablement la portée des opérations du flux de travail. Il doit être combiné avec une liste blanche safe-outputs stricte et des instructions claires, et doit être entièrement vérifié dans un environnement de test avant d'être utilisé dans des dépôts de production.

6.4 Sortie structurée et traitement ultérieur

La sortie de l'agent IA ne peut pas seulement créer des Issues/PRs, mais peut également générer des données structurées (telles que JSON) pour les étapes de flux de travail traditionnelles ultérieures. Cela permet une pipeline hybride de "décision IA" et "d'automatisation traditionnelle".

# .github/agent-workflows/analyze-and-notify.md
---
on: push
permissions:
  contents: read
  copilot-requests: write
outputs:
  change-summary: # Définir une variable de sortie
    description: "Résumé des changements généré par l'IA"
safe-outputs:
  agent-output: # Autoriser la sortie de données structurées par l'agent
---
# Analyse des changements de code
Analysez les changements de code dans ce push (git diff).
Veuillez générer un résumé au format JSON contenant les champs suivants :
- `files_changed` : Tableau, listant les chemins de fichiers modifiés.
- `change_types` : Objet, comptant le nombre de chaque type de changement (par exemple, `feat`, `fix`, `docs`, `refactor`).
- `complexity_estimate` : Chaîne de caractères, évaluant simplement la complexité du changement actuel ("low", "medium", "high").
- `potential_risks` : Tableau, listant les points de risque potentiels identifiés par l'IA (par exemple : modification de la logique centrale, absence de tests, etc.).

Sortez le résultat JSON.

Dans les étapes ultérieures, d'autres Jobs peuvent référencer ces données JSON via ${{ needs.analyze-job.outputs.change-summary }} et déclencher des notifications correspondantes (telles que l'envoi à Slack) ou des portes de qualité.

7. Questions fréquentes et pistes de dépannage

Lorsque vous utilisez les flux de travail d'agent pour la première fois, vous pourriez rencontrer certains problèmes. Le tableau suivant liste les problèmes courants et leurs solutions :

Phénomène du problème	Cause possible	Méthode de dépannage	Solution
Échec de compilation du flux de travail `gh agent-workflow compile` erreur	1. Erreur de syntaxe YAML du Frontmatter. 2. Utilisation d'événements ou de paramètres non pris en charge. 3. Version obsolète de GitHub CLI.	1. Vérifiez le format YAML entre `---`, assurez-vous que l'indentation est correcte et que les paires clé-valeur sont valides. 2. Consultez le message d'erreur de la ligne de commande. 3. Exécutez `gh version` pour vérifier la version de CLI.	1. Utilisez un validateur YAML en ligne pour vérifier la syntaxe. 2. Consultez la documentation officielle pour confirmer la syntaxe du déclencheur. 3. Mettez à jour GitHub CLI vers la dernière version.
Le flux de travail échoue, le journal affiche `Permission denied`	1. Actions non activées dans le dépôt. 2. Le fichier de flux de travail n'est pas dans la branche par défaut. 3. Paramètres `permissions` insuffisants dans le Frontmatter. 4. Pour Copilot, autorisation `copilot-requests: write` manquante ou jeton invalide.	1. Vérifiez les paramètres du dépôt -> Paramètres d'Actions. 2. Confirmez que les fichiers `.md` et `.lock.yml` sont dans la branche `main`. 3. Consultez les journaux détaillés du Job en échec pour trouver le message d'erreur d'autorisation spécifique.	1. Activez les Actions dans les paramètres du dépôt. 2. Fusionnez les fichiers de flux de travail dans la branche par défaut. 3. En fonction du message d'erreur, ajoutez les autorisations requises dans le Frontmatter (par exemple, `issues: write`). 4. Assurez-vous d'utiliser la facturation de l'organisation ou de configurer correctement le secret `COPILOT_GITHUB_TOKEN`.
L'agent IA n'effectue pas l'action attendue (par exemple, aucune Issue créée)	1. `safe-outputs` n'a pas déclaré l'opération correspondante. 2. L'instruction en langage naturel n'est pas assez claire ou est ambiguë. 3. Erreur de compréhension du modèle IA.	1. Vérifiez si la liste `safe-outputs` dans le Frontmatter inclut l'opération cible (par exemple, `create-issue:`). 2. Consultez les journaux de l'Agent pour voir ce qu'il décide d'exécuter après avoir analysé l'instruction. 3. Recherchez "Safety check" ou "Not a safe output" dans les journaux.	1. Ajoutez l'opération manquante sous `safe-outputs`. 2. Réécrivez l'instruction pour la rendre plus spécifique et structurée. Clarifiez les verbes ("créer", "résumer", "classifier") et les objets ("une Issue", "un rapport"). 3. Vous pouvez essayer d'ajouter explicitement "Veuillez impérativement créer une nouvelle Issue GitHub" au début de l'instruction.
Le flux de travail s'exécute avec succès, mais la qualité de la sortie est médiocre (par exemple, informations incomplètes, format désordonné)	1. Instruction trop vague. 2. Informations contextuelles du dépôt insuffisantes (par exemple, pas d'activité récente). 3. Limitations du modèle IA lui-même.	1. Revoyez le contenu de l'Issue générée, comparez-la à votre instruction, voyez quelles parties ont été ignorées. 2. Consultez les journaux pour confirmer quelles données contextuelles l'IA a lues.	1. Itérer et optimiser l'instruction. C'est la compétence clé de l'utilisation des flux de travail d'agent. C'est comme écrire des instructions de tâche pour un stagiaire, affinez continuellement les exigences. Par exemple, ne dites pas seulement "résumer le PR", mais aussi "listez le numéro du PR, le titre, l'auteur et l'heure de fusion sous forme de tableau". 2. Fournissez des exemples de format de sortie plus clairs dans l'instruction (Prompting Few-shot). 3. Si le dépôt n'a pas eu d'activité récente, l'IA peut n'avoir rien à résumer, ce qui est le comportement attendu.
Recevoir un avertissement de dépassement de coût ou une interruption du flux de travail due au coût	La consommation de crédits IA par exécution dépasse la limite de `max-ai-credits` (1000 par défaut).	Utilisez `gh agent-workflow audit <run_id></run_id>` pour afficher l'utilisation détaillée des jetons et l'estimation des coûts.	1. Définissez une limite `max-ai-credits` plus faible dans le Frontmatter (par exemple, 300). 2. Optimisez l'instruction pour la rendre plus concise et réduire les requêtes d'analyse contextuelle inutiles. 3. Pour les tâches très complexes, envisagez de les diviser en plusieurs flux de travail plus petits et plus ciblés.
Erreur `Invalid API Key` lors de l'utilisation d'un moteur tiers (par exemple, Claude)	1. La clé API n'est pas correctement définie dans les Secrets du dépôt. 2. Le format de la clé est incorrect ou la clé a expiré. 3. Nom du moteur mal orthographié.	1. Vérifiez les Paramètres du dépôt -> Secrets et variables -> Actions. 2. Confirmez que le nom du Secret correspond exactement au nom de la variable référencée dans le `env` du Frontmatter. 3. Vérifiez les identifiants corrects du moteur dans la documentation officielle.	1. Ajoutez correctement la clé API dans les Secrets du dépôt (par exemple, `ANTHROPIC_API_KEY`). 2. Assurez-vous que la clé a un solde et n'a pas expiré. 3. Utilisez le nom correct du moteur, par exemple `anthropic/claude-3-5-sonnet`.

8. Meilleures pratiques et conseils d'ingénierie

L'introduction des flux de travail d'agent dans l'environnement de production nécessite le respect de certaines meilleures pratiques pour garantir leur fiabilité, leur sécurité et leur maintenabilité.

8.1 Ingénierie des instructions : écrire des "instructions de tâche" efficaces

La qualité des instructions détermine directement l'efficacité du flux de travail.

Clair et spécifique : Évitez les instructions vagues comme "analyser le code". Il devrait plutôt être : "Vérifiez les fichiers .js modifiés au cours de la semaine dernière dans le répertoire src/utils/, trouvez les fonctions dont la longueur dépasse 50 lignes, et listez leur emplacement et les méthodes de refactorisation suggérées dans une nouvelle Issue."
Sortie structurée : Exigez explicitement le format de sortie. Par exemple, "Veuillez sortir sous forme de tableau Markdown, incluant les colonnes : nom du fichier, nom de la fonction, nombre de lignes, score de complexité".
Définir les limites : Dites à l'IA ce qu'il ne faut pas faire. Par exemple, "Analysez uniquement le code de la branche main, ignorez tous les fichiers dans le répertoire test".
Optimisation itérative : Traitez le flux de travail d'agent comme un "logiciel" qui nécessite un débogage et une optimisation. En fonction des résultats des premières exécutions, ajustez et affinez continuellement vos instructions.

8.2 La sécurité avant tout : suivre le principe du moindre privilège

L'un des principaux avantages des flux de travail d'agent est sa sécurité intégrée, mais une mauvaise configuration peut toujours introduire des risques.

Toujours commencer par les autorisations read : Dans permissions du Frontmatter, accordez uniquement les autorisations read par défaut. N'ajoutez des autorisations write que lorsque des opérations d'écriture sont explicitement nécessaires.
Restreindre strictement les safe-outputs : Ne déclarez que les opérations de sortie dont le flux de travail a réellement besoin. S'il n'a besoin que de commentaires, ne déclarez pas create-pull-request.
Utiliser les tools avec prudence : En particulier curl ou les jeux d'outils personnalisés, ils peuvent permettre à l'agent d'accéder à des systèmes externes. Assurez-vous de faire confiance à ces outils et de comprendre leurs impacts potentiels.
Utiliser la protection de branche : Placez les fichiers de flux de travail d'agent (.md et .lock.yml) sur une branche protégée, exigez la Pull Request et la revue de code pour la fusion, afin d'empêcher les modifications non autorisées.

8.3 Contrôle des coûts et surveillance

L'inférence IA est la principale source de coûts.

Définir des limites budgétaires : Utilisez max-ai-credits dans le Frontmatter de chaque flux de travail pour définir une limite raisonnable. Pour des tâches simples de classification et de résumé, 200 à 500 AIC sont généralement suffisants ; une analyse de code complexe peut en nécessiter davantage.
Examiner régulièrement les journaux : Utilisez gh agent-workflow logs pour vérifier régulièrement la consommation et identifier les flux de travail qui peuvent entraîner des appels en boucle ou une analyse de contexte excessive en raison d'instructions inappropriées.
Distinguer les environnements : Testez minutieusement les flux de travail dans des dépôts de développement ou de test pour vous assurer que leur stabilité et leurs coûts sont conformes aux attentes avant de les appliquer à des dépôts de production importants.

8.4 Utilisation combinée avec des flux de travail traditionnels

Agent Workflow n'est pas destiné à remplacer tous les flux de travail traditionnels, mais plutôt à les complémenter.

Décision IA + Exécution traditionnelle : Laissez l'agent analyser la situation et générer un plan (par exemple, "quelles dépendances doivent être mises à jour"), puis laissez les étapes du flux de travail traditionnel exécuter les commandes spécifiques et déterministes (par exemple, exécuter npm update).
Prétraitement traditionnel + Posttraitement IA : Utilisez d'abord des scripts traditionnels pour collecter et filtrer les données (par exemple, obtenir tous les journaux d'échec de CI), puis transmettez les données épurées au flux de travail d'agent pour analyser la cause profonde et générer un rapport.
Passage de données via outputs : Comme mentionné précédemment, utilisez les outputs du flux de travail d'agent pour transmettre le résultat de la décision IA (par exemple, une chaîne JSON) à un Job traditionnel en aval, construisant ainsi une pipeline hybride.

8.5 Gestion des versions et collaboration

Gérez les fichiers .md comme du code ordinaire.

Revue de code : Effectuez une revue de code pour les instructions des flux de travail d'agent. L'accent de la revue ne doit pas porter sur la syntaxe, mais sur la clarté, la sécurité et l'efficacité attendue des instructions.
Documentation : Au début du fichier .md ou dans le README du dépôt, décrivez le but de chaque flux de travail d'agent, ses déclencheurs, son comportement attendu et une estimation des coûts.
Tester les changements : Après avoir modifié les instructions, testez d'abord dans un dépôt de test ou déclenchez manuellement via workflow_dispatch, observez si la sortie est conforme aux attentes, puis fusionnez dans la branche principale.

Les flux de travail d'agent GitHub marquent le début d'une nouvelle ère : l'automatisation évolue de la "réflexe conditionné" basé sur des règles à la "prise de décision cognitive" basée sur la compréhension. Elle abaisse le seuil de l'automatisation intelligente, permettant à chaque développeur de créer des assistants robotiques plus intelligents pour lui-même et son équipe.

Cependant, ce n'est pas une solution miracle. Pour les processus de construction et de déploiement hautement déterministes et exigeant une fiabilité extrême, les flux de travail scriptés traditionnels restent le choix supérieur. Le véritable champ d'application des flux de travail d'agent réside dans le comblement des "lacunes d'automatisation qui nécessitent un peu de jugement humain" - gestion des Issues, analyse des changements de code, maintenance de la documentation, génération de rapports d'informations.

En tant que développeur, vous pouvez agir immédiatement : choisissez la tâche la plus fastidieuse et répétitive dans votre dépôt qui nécessite tout de même un peu de réflexion, essayez de la décrire avec un fichier Markdown, puis laissez l'agent IA la réaliser. Commencez par le rapport quotidien, étendez progressivement à la classification automatique, à la revue intelligente, à la maintenance de la base de connaissances. Dans ce processus, la compétence la plus importante ne sera plus d'écrire du YAML complexe, mais de définir clairement le problème, de décrire la tâche et de collaborer efficacement avec l'IA.

Étiquettes: GitHub Actions Agent Workflows IA automatisation devops

Publié le 6 octobre à 23h46

L'Atelier Monstre