Tutoriels d'intégration

Synchroniser Work avec GitHub

Objectif : relier une tâche à une issue GitHub et refléter automatiquement son statut (issue fermée → tâche « terminée »).

Prérequis : module Projets ; un dépôt GitHub ; un PAT GitHub avec accès au dépôt.

1. Connecter le dépôt (par organisation)¶

WORK=https://work.puwapi.com
curl -X PUT $WORK/api/work/github/config \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{
    "repo": "monorg/monrepo",
    "accessToken": "ghp_xxx",
    "webhookSecret": "un-secret-fort"
  }'

Le PAT et le secret sont stockés côté serveur et jamais renvoyés par l'API.

2. Créer ou lier une issue depuis une tâche¶

Créer une issue (le titre est préfixé de la référence de la tâche, ex. SITE-12) :

curl -X POST $WORK/api/work/items/$ITEM_ID/github/issue -H "Authorization: Bearer $JWT"

Ou lier une issue/PR existante :

curl -X POST $WORK/api/work/items/$ITEM_ID/github/link \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"url":"https://github.com/monorg/monrepo/issues/42"}'

3. Configurer le webhook côté GitHub¶

Dans les réglages du dépôt GitHub → Webhooks :

Payload URL : https://work.puwapi.com/api/work/github/webhook
Content type : application/json
Secret : le même webhookSecret qu'à l'étape 1
Events : Issues et Pull requests

4. Vérifier la synchronisation¶

Fermez l'issue liée sur GitHub. Le webhook :

vérifie la signature X-Hub-Signature-256 (HMAC SHA-256 sur le corps brut) ;
retrouve l'intégration par le dépôt ;
sur action closed/reopened, mappe le statut : closed → done (tâche) / resolved (ticket), reopened → in_progress ;
l'opération est idempotente (rejouer le même état ne fait rien).

La tâche passe en « terminé » automatiquement, et le tableau se rafraîchit en temps réel.

Dépannage¶

Symptôme	Cause probable
Aucun effet	Dépôt inconnu ou signature absente → `200` silencieux (volontaire)
`403` sur le webhook	Signature invalide (secret différent des deux côtés)
Rien ne bouge	L'événement n'est pas `closed`/`reopened`, ou l'item n'est pas lié

Limite : une organisation ne relie qu'un seul dépôt (voir Support → Limites connues).

#tutorial #work