Introduction
GitHub Projects v2, lancé en beta et stabilisé en 2024, révolutionne la gestion de projets avec des tableaux dynamiques, champs personnalisés et automatisations natives. Contrairement aux Projects v1 limités à des colonnes statiques, v2 offre une API GraphQL puissante pour CRUD programmatique, des itérations comme les sprints, et des intégrations fluides avec GitHub Actions. Pour un expert, l'enjeu est de scaler : automatiser les mises à jour basées sur issues/PRs, créer des dashboards data-driven et intégrer avec des outils externes. Ce tutoriel vous guide pas à pas avec du code complet, pour transformer vos repos en usines à projets. Idéal pour leads tech gérant 10+ repos simultanément. (132 mots)
Prérequis
- Compte GitHub Pro ou Enterprise avec accès Projects v2 (beta activée si besoin).
- Repository existant avec issues et PRs.
- Connaissances avancées en GitHub Actions et GraphQL.
- Node.js 20+ pour tester les scripts API.
- GitHub CLI installé (
gh auth login).
Créer un Project via GraphQL API
mutation CreateProject {
createProjectV2(input: {
ownerId: "REPO:your-org/your-repo",
title: "Mon Projet Expert 2026",
description: "Projet avancé avec automatisations",
public: true
}) {
projectV2 {
id
number
title
url
}
}
}Cette mutation GraphQL crée un Project v2 sur un repo spécifique. Remplacez ownerId par votre repo (format 'REPO:org/repo'). Exécutez-la via GitHub CLI (gh api graphql -f queryFile=query.graphql) ou curl avec token PAT (scopes: project). Piège: sans public: true, il reste privé et inaccessible aux automatisations.
Ajouter des champs personnalisés
Après création, configurez des champs via l'UI ou API : iteration (pour sprints), single select (priorités), number (effort). Cela prépare les automatisations.
Ajouter champ custom via API
mutation AddCustomField {
projectV2FieldCreate(input: {
projectId: "PVT_xxxxx",
name: "Priorité",
dataType: SINGLE_SELECT,
singleSelectOptionValues: ["P0", "P1", "P2", "P3"]
}) {
field {
id
name
dataType
}
}
}Ajoute un champ 'Priorité' de type single-select. projectId vient de la réponse de création (format PVT_). Utile pour trier dynamiquement. Attention: max 50 options par champ, et dataType doit matcher (SINGLE_SELECT, ITERATION, etc.). Testez avec gh api graphql.
Workflow YAML pour auto-ajout d'issues
name: Ajouter Issue au Project
on:
issues:
types: [opened, labeled]
jobs:
add-issue:
runs-on: ubuntu-latest
permissions:
issues: write
pull-requests: write
steps:
- uses: actions/add-to-project@v2
with:
project-url: https://github.com/orgs/your-org/projects/1
github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
labeled: triage
label-operator: ORCe workflow ajoute automatiquement les issues labellisées 'triage' au Project. Utilisez un PAT dédié (repo:write, project). project-url est l'URL du board. Piège: permissions manquantes causent des échecs silencieux ; vérifiez les logs Actions.
Lier items aux issues/PRs
Maintenant, mappez des issues existantes au Project et mettez à jour des champs automatiquement.
Ajouter item et updater champs
mutation AddItemAndUpdate {
addProjectV2ItemById(input: {
projectId: "PVT_xxxxx",
contentId: "I_abc123"
}) {
item {
id
}
}
projectV2ItemFieldSingleSelectValueUpdate(input: {
projectId: "PVT_xxxxx",
itemId: "PVTF_xxxxx",
fieldId: "PVTF_xxxxx",
singleSelectOptionId: "P0"
}) {
singleSelectField {
name
}
}
}Ajoute un issue (contentId: I_... pour issue, PR_ pour PR) au project, puis met à jour le champ 'Priorité' à 'P0'. Récupérez IDs via queries préalables. Astuce: chainnez mutations en batch pour perf. Erreur courante: IDs expirés après 30j.
Workflow avancé : Auto-update sur PR merge
name: Update Project on Merge
on:
pull_request:
types: [closed]
jobs:
update-field:
if: github.event.pull_request.merged == true
runs-on: ubuntu-latest
steps:
- name: Run field updater
uses: actions/github-script@v7
with:
script: |
const { data: { project } } = await github.rest.projects.get({ owner: context.repo.owner, project_id: 1 });
// Logique custom pour update via GraphQL
env:
PROJECT_ID: ${{ secrets.PROJECT_ID }}Déclenché sur merge PR, met à jour champs (ex: passer à 'Done'). Étendez avec github-script pour GraphQL calls. Secret PROJECT_ID sécurise. Limite: rate limits API (5000/h avec PAT).
Query GraphQL pour dashboard custom
query ProjectDashboard($projectId: ID!) {
node(id: $projectId) {
... on ProjectV2 {
title
items(first: 20) {
nodes {
content {
... on Issue {
title
labels(first: 5) { nodes { name } }
}
}
fieldValues(first: 10) {
nodes {
... on ProjectV2ItemFieldSingleSelectValue {
name
}
}
}
}
}
}
}
}Query paginée pour exporter données Project en JSON/CSV. $projectId variable. Parfait pour dashboards externes (ex: script Node vers Google Sheets). Piège: first:100 max par page ; utilisez after pour cursor pagination.
Bonnes pratiques
- Utilisez toujours des PAT dédiés avec scopes minimaux (project, repo) stockés en secrets.
- Paginer les queries GraphQL pour >100 items ; implémentez cursors.
- Versionnez les workflows avec branches/feature pour tests.
- Backup IDs : stockez project/field IDs en repo vars/secrets.
- Monitorez rate limits via GitHub API status.
Erreurs courantes à éviter
- IDs obsolètes : Projects v2 IDs changent rarement, mais vérifiez après org migrations.
- Permissions manquantes : Actions échouent sans
issues:write; ajoutezpermissions:block. - Champs non initialisés : Update avant addItem cause NULL errors.
- Rate limiting : >100 mutations/jour → 429 ; throttle avec delays.
Pour aller plus loin
- Docs officielles : GitHub Projects GraphQL.
- Repo exemple : Forkez github/docs pour tester.
- Intégrez avec Slack/Teams via webhooks.
- Découvrez nos formations Learni Dev sur GitHub Automation.