Conectar Jira con un token de API

Un token de API permite que Planning Poker Web lea las incidencias de tu Jira y escriba de vuelta la estimación aceptada, sin pasar por una pantalla de inicio de sesión. Esta página explica cómo crear uno, qué puede hacer y qué revisar cuando algo no funciona. Se aplica a Jira Cloud (una dirección como tu-equipo.atlassian.net). Jira Data Center no es compatible.

Antes de empezar

• Necesitas el permiso para gestionar el planning poker en tu organización. Los propietarios lo tienen de forma predeterminada.
• La cuenta de Jira detrás del token necesita, en cada proyecto que vayas a usar, el permiso para examinar el proyecto (para importar incidencias) y editar incidencias (para escribir la estimación de vuelta). Si solo importas y nunca devuelves estimaciones, con examinar basta.
• Prefiere una cuenta compartida creada para esto, como [email protected], en lugar de la cuenta de una persona. La estimación aparece en el historial de la incidencia con el nombre de esa cuenta, y un token personal deja de funcionar el día en que esa persona se va o pierde el acceso.

Paso 1: crear el token en Atlassian

1. Inicia sesión en Atlassian con la cuenta elegida y abre id.atlassian.com → Seguridad → Tokens de API.
2. Elige Crear token de API. Usa el normal, no "Crear token de API con alcances": un token con alcances no funciona con esta conexión.
3. Dale un nombre que reconozcas, como "Planning Poker Web", y elige cuánto tiempo debe durar.
4. Copia el token de inmediato. Atlassian lo muestra una sola vez. Si lo pierdes, crea uno nuevo.

Si no ves la opción, es posible que el administrador de tu Atlassian haya restringido quién puede crear tokens. Pídele que lo habilite para la cuenta elegida.

Paso 2: conectarlo en Planning Poker Web

1. Abre Configuración → Integraciones, elige Jira y luego Conectar, y selecciona la opción Token de API.
2. Completa los tres campos:
   • Sitio de Jira: la dirección de tu Jira, por ejemplo https://tu-equipo.atlassian.net. Solo se aceptan direcciones https://….atlassian.net.
   • Correo de la cuenta: el correo de la cuenta de Atlassian que creó el token.
   • Token de API: el token que copiaste.
3. Elige Probar. Si funciona, verás el nombre de la cuenta de Jira. Tu token se guarda cifrado y nunca vuelve a mostrarse.
4. En el paso Configurar, elige si la estimación aceptada vuelve a Jira y en qué campo. Consulta Devolver estimaciones.

Cómo funciona

Cada solicitud se hace desde nuestros servidores hacia tu Jira, firmada con tu correo y tu token. El token tiene los mismos permisos que la cuenta que lo creó, ni más ni menos. Planning Poker Web hace solamente esto:

• Lee tus proyectos y, de un proyecto, sus estados, tipos de incidencia, épicas y sprints, para que el diálogo de importación pueda ofrecer los filtros.
• Lee incidencias: la clave, el título y la descripción, para traerlas a una sala.
• Escribe un número en una incidencia: la estimación aceptada, en el campo que elegiste.

Nunca crea ni elimina incidencias, nunca cambia su estado y nunca agrega comentarios. Los sprints solo se leen si la cuenta puede abrir el tablero del proyecto en Jira Software. Sin eso, el filtro de sprint queda simplemente vacío.

Si no funciona

• "Jira rechazó las credenciales": el correo o el token están mal, el token fue revocado o expiró. Crea un token nuevo y usa Reconectar.
• "Jira denegó el acceso (403)": Jira entendió la clave, pero rechazó la solicitud. Revisa, en este orden: que la cuenta realmente tenga acceso a Jira en ese sitio (abre el sitio con sesión iniciada con esa cuenta), que pueda examinar el proyecto (y editar incidencias, para las estimaciones), que el administrador de Atlassian no haya limitado el acceso a la API a ciertas redes, y que el token sea del tipo normal, no el de "con alcances". La explicación del propio Jira, cuando la da, aparece después de los dos puntos.
• Tu proyecto no aparece en la lista: la cuenta no puede examinarlo. Agrega la cuenta al proyecto, o usa una cuenta que ya pertenezca a él.
• La estimación no se envió, indicando que el campo no está en la pantalla: el campo debe estar en la pantalla de edición de la incidencia en ese proyecto. Jira tiene dos campos parecidos, Story points y Story point estimate; elige el que muestra tu tablero.
• "Usa la dirección de tu Jira Cloud": el campo del sitio debe tener el aspecto de https://tu-equipo.atlassian.net, sin nada después.

Cuando el token expira o quieres detenerlo

Los tokens de Atlassian no duran para siempre. Cuando el tuyo expire, crea uno nuevo y usa Reconectar; tus configuraciones de estimación se conservan. Para detener la conexión, elige Desconectar en Planning Poker Web y, si quieres, revoca el token en id.atlassian.com → Seguridad → Tokens de API. Después de eso, nada puede llegar a tu Jira.