Connecter Jira avec un jeton d'API

Un jeton d'API permet à Planning Poker Web de lire vos tickets Jira et d'y écrire l'estimation validée, sans passer par une page de connexion. Cette page explique comment créer un jeton, les autorisations qu'il permet et les vérifications à effectuer en cas de problème. Elle concerne Jira Cloud (avec une adresse comme your-team.atlassian.net). Jira Data Center n'est pas pris en charge.

Avant de commencer

• Vous devez avoir l'autorisation de gérer le planning poker dans votre organisation. Les propriétaires l'ont par défaut.
• Le compte Jira associé au jeton doit disposer, dans chaque projet utilisé, de l'autorisation parcourir le projet (pour importer les tickets) et modifier les tickets (pour y renvoyer l'estimation). Si vous ne faites qu'importer des tickets sans renvoyer d'estimations, l'autorisation de parcours suffit.
• Privilégiez un compte partagé créé à cet effet, par exemple [email protected], plutôt que le compte personnel d'un membre de l'équipe. L'estimation apparaîtra dans l'historique du ticket sous le nom de ce compte, et un jeton personnel cessera de fonctionner si son propriétaire quitte l'entreprise ou perd ses accès.

Étape 1 : créer le jeton dans Atlassian

1. Connectez-vous à Atlassian avec le compte choisi et ouvrez id.atlassian.com → Security → API tokens.
2. Choisissez Create API token. Utilisez le jeton standard, et non « Create API token with scopes » : les jetons avec des scopes ne fonctionnent pas avec cette connexion.
3. Donnez-lui un nom reconnaissable, par exemple « Planning Poker Web », et choisissez sa durée de validité.
4. Copiez immédiatement le jeton. Atlassian ne l'affiche qu'une seule fois. Si vous le perdez, créez-en un nouveau.

Si cette option n'apparaît pas, votre administrateur Atlassian a peut-être limité la création de jetons. Demandez-lui de l'autoriser pour le compte choisi.

Étape 2 : connecter le jeton dans Planning Poker Web

1. Ouvrez Settings → Integrations, choisissez Jira, puis Connect, et sélectionnez l'option API token.
2. Renseignez les trois champs :
   • Jira site : l'adresse de votre Jira, par exemple https://your-team.atlassian.net. Seules les adresses au format https://….atlassian.net sont acceptées.
   • Account e-mail : l'adresse e-mail du compte Atlassian ayant créé le jeton.
   • API token : le jeton que vous avez copié.
3. Choisissez Test. Si la connexion fonctionne, le nom du compte Jira s'affiche. Votre jeton est stocké sous forme chiffrée et ne sera plus jamais affiché.
4. À l'étape Configure, choisissez si l'estimation validée doit être renvoyée à Jira et dans quel champ. Consultez Renvoyer les estimations.

Fonctionnement

Chaque requête est envoyée depuis nos serveurs vers votre Jira et signée avec votre adresse e-mail et votre jeton. Le jeton possède les mêmes autorisations que le compte qui l'a créé, ni plus ni moins. Planning Poker Web effectue uniquement les opérations suivantes :

• Lit vos projets et, pour chaque projet, ses statuts, types de tickets, epics et sprints afin de proposer des filtres dans la fenêtre d'importation.
• Lit les tickets (clé, titre et description) pour les ajouter à une salle.
• Écrit un nombre dans un seul ticket : l'estimation validée, dans le champ choisi.

L'application ne crée ni ne supprime jamais de tickets, ne modifie pas leur statut et n'ajoute aucun commentaire. Les sprints ne sont lus que si le compte peut ouvrir le tableau du projet dans Jira Software. Sinon, le filtre de sprint reste simplement vide.

En cas de problème

• « Jira rejected the credentials » : l'adresse e-mail ou le jeton est incorrect, le jeton a été révoqué ou il a expiré. Créez un nouveau jeton et utilisez Reconnect.
• « Jira denied access (403) » : Jira a reconnu la clé, mais a refusé la requête. Vérifiez dans cet ordre que le compte a bien accès à Jira sur ce site (ouvrez le site en étant connecté avec ce compte), qu'il peut parcourir le projet (et modifier les tickets pour renvoyer des estimations), que votre administrateur Atlassian n'a pas limité l'accès à l'API à certains réseaux et que le jeton est de type standard, et non « avec scopes ». Si Jira fournit une explication, elle apparaît après les deux-points.
• Votre projet n'apparaît pas dans la liste : le compte n'a pas l'autorisation de le parcourir. Ajoutez ce compte au projet ou utilisez un compte qui en fait déjà partie.
• L'estimation n'a pas été envoyée : le champ n'est pas à l'écran : le champ doit figurer sur l'écran de modification des tickets de ce projet. Jira propose deux champs similaires, Story points et Story point estimate ; choisissez celui affiché sur votre tableau.
• « Use your Jira Cloud address » : le champ du site doit être au format https://your-team.atlassian.net, sans chemin supplémentaire.

Expiration ou arrêt du jeton

Les jetons Atlassian ont une durée de validité limitée. Lorsque le vôtre expire, créez-en un nouveau et utilisez Reconnect ; vos paramètres d'estimation sont conservés. Pour arrêter la connexion, choisissez Disconnect dans Planning Poker Web et, si vous le souhaitez, révoquez le jeton dans id.atlassian.com → Security → API tokens. Après cela, aucun accès à votre Jira n'est possible.