> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codewarden.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira

> Somete un pull request al ticket de Jira que enlaza: configuración, qué muestra el resumen, qué se lee, qué se guarda y cómo desconectar.

Cuando un pull request enlaza un ticket de Jira, CodeWarden lee el ticket y hace dos cosas:

* Reporta el código que hace algo **distinto** de lo que dice el ticket, como un comentario en línea con la categoría `acceptance`.
* Lista los requisitos del ticket en el resumen de la revisión, cada uno marcado según lo que **muestra este cambio**. Consulta [Qué muestra el resumen](#what-the-summary-shows).

Nunca reporta, como comentario, que falta algo que el ticket pide. Una revisión ve una parte de un cambio, nunca todo, y el resto del ticket puede hacerse en otro pull request.

## Requisitos

* **Jira Cloud** (`*.atlassian.net`). Jira Server y Jira Data Center no son compatibles.
* Un [propietario](https://docs.codewarden.co/es/console/organizations-and-roles.md) de la organización en la consola de CodeWarden, para conectarlo.
* Alguien que pueda hacer merge en la base branch, para listar los proyectos permitidos en `.codewarden.yml`.

## Configúralo

**1. Conecta Jira en la consola**

En la página de inicio de la consola, abre la instalación y, bajo **Integraciones**, haz clic en **Conectar Jira**. Atlassian te pide otorgar a CodeWarden acceso de lectura. Si tu cuenta de Atlassian puede ver varios sitios de Jira, la consola te pregunta entonces **¿Qué sitio?**; elige uno.

Una instalación tiene un sitio de Jira. Conectar de nuevo reemplaza la autorización anterior, que es también la forma de reparar una conexión rota.

**2. Permite los proyectos en .codewarden.yml**

Agrega las claves de los proyectos de Jira desde los que un pull request puede enlazar tickets, y haz merge del cambio en la base branch:

```yaml .codewarden.yml theme={null}
jira:
  projects: ["PROJ"]
  public_repositories: false
```

Sin esta lista no se lee ningún ticket, aunque Jira esté conectado. En un repositorio público, no se lee nada a menos que `public_repositories` sea `true`.

**3. Enlaza el ticket en el pull request**

Pon la URL del ticket en el título o la descripción del pull request:

```text theme={null}
Closes https://acme.atlassian.net/browse/PROJ-123
```

Una clave suelta como `PROJ-123` no coincide; solo coincide una URL completa. El resumen de la revisión termina con `Checked against PROJ-123.` cuando se leyó el ticket.

## Qué muestra el resumen

Bajo `Checked against PROJ-123.`, el resumen lista los requisitos que establece el ticket, en el orden del ticket y con sus propias palabras, cada uno con una marca:

```markdown theme={null}
**What this change shows of PROJ-123**

- Invitations expire after 7 days: **contradicted, see the comment**
- An expired invitation shows a clear message: **seen in this change**
- The owner is emailed when an invitation expires: **not seen in this change**

This list describes only what this review was shown. Criteria may be done in other files or other pull requests; this is not a statement that the ticket is done or not done.
```

| Marca | Significado |
| - | - |
| **seen in this change** | El código de este pull request lo hace visiblemente. |
| **not seen in this change** | Nada de lo que se le mostró a esta revisión lo hace. Eso no dice nada sobre el resto de tu repositorio, y nunca es un comentario. |
| **contradicted, see the comment** | El código de este pull request lo hace distinto de lo que dice el ticket. Hay un comentario `acceptance` en la línea. |

Algunas cosas que conviene saber:

* **Es información, no un veredicto.** Nunca es un comentario en línea, no se cuenta como hallazgo y nunca hace fallar el check de CodeWarden.
* **Las palabras son fijas.** CodeWarden escribe por sí mismo las marcas y la línea bajo la lista. Los requisitos se citan de tu ticket, acortados si son largos, nunca reescritos.
* **La línea bajo la lista dice qué se dejó fuera.** Agrega cuántos archivos no se revisaron, si una revisión de seguimiento vio solo el push más reciente y si el ticket cambió desde la última revisión.
* **Lo que se vio sigue visto.** En un push de seguimiento, un requisito que una revisión anterior del mismo pull request marcó como visto nunca vuelve a "no visto". La lista se publica de nuevo solo cuando una marca cambió.
* **Un requisito con varias partes** se lista parte por parte cuando el cambio hace solo algunas.
* **Un ticket que no establece ningún requisito** (un título de una línea, prosa de contexto) no recibe lista.
* **Ningún comentario dice que algo falta.** Un comentario que el modelo vincula a un requisito que la lista marca como no visto, o un comentario `acceptance` que la lista no marca como contradicho, se retiene y se lista en la página de la revisión en la consola bajo **Descartados**, con el motivo.

La lista está activada por defecto. Para desactivarla en un repositorio, define `jira.ticket_coverage: false` en `.codewarden.yml` en la base branch; las contradicciones se siguen reportando como comentarios. Consulta [`jira`](https://docs.codewarden.co/es/configure/codewarden-yml#jira).

## Cuándo se lee un ticket

Deben cumplirse todas. Si no, la revisión se ejecuta sin el ticket, y la consola muestra por qué en la página de la revisión.

1. La URL está en el título o la descripción del pull request, con la forma `https://<site>/browse/<KEY-123>`.
2. El proyecto del ticket está listado en `jira.projects` en la base branch.
3. El sitio de la URL es el sitio conectado a la instalación. Un enlace a cualquier otro sitio nunca se lee.
4. El repositorio es privado, o `jira.public_repositories` es `true`.
5. La conexión funciona.

Se lee un ticket por revisión: la primera URL enlazada que pasa estas verificaciones. Un ticket que no se puede leer (no encontrado, sin permiso o demasiado lento) nunca hace fallar la revisión y nunca marca la conexión como rota.

La URL de un pull request la escribe quien lo abrió, y por eso no decide nada por sí sola: la lista de proyectos de tu repositorio es en lo que confías.

## Qué se lee

El **resumen, la descripción, el tipo, el estado y el proyecto** del ticket, en una solicitud de solo lectura por revisión. El texto se le muestra al modelo como datos contra los que comprobar el código, nunca como instrucciones.

CodeWarden le pide a Atlassian solo permisos de lectura (`read:jira-work` y `offline_access`). Nunca crea, edita ni comenta en issues de Jira.

## Qué se guarda

* **Los tokens de la conexión**, cifrados en reposo, porque las revisiones los usan cuando nadie ha iniciado sesión. Se renuevan automáticamente, y una conexión inactiva por 30 días se renueva en segundo plano para que Atlassian no la expire.
* **Qué ticket se usó**: su clave, sitio, URL y el resultado de la lectura, en el registro de la revisión.
* **No el texto del ticket.** El modelo lee el título y la descripción, pero la copia del prompt que CodeWarden guarda los tiene eliminados.
* **La lista del resumen, sin las palabras.** Por cada requisito, el registro de la revisión guarda su marca y dónde está en el ticket, nunca su texto. Las palabras aparecen solo en el resumen en GitHub.

## Estados de la conexión

El cuadro **Integraciones** de la instalación en la consola muestra uno de estos:

| Estado | Significado |
| - | - |
| no conectado | Sin autorización. **Conectar Jira**. |
| Se concedió acceso a Jira…, ¿Qué sitio? | La autorización cubre varios sitios. Elige uno. |
| conectado | Funciona. Muestra el sitio, la fecha en que se conectó y cuándo funcionó por última vez. Los propietarios pueden **Probar conexión**. |
| requiere reconexión | Atlassian rechazó la autorización: fue revocada, expiró tras 90 días de inactividad o se agotó. Haz clic en **Reconectar Jira**. |

## Desconectar y revocar

* **En la consola:** un propietario hace clic en **Desconectar** en el cuadro de Jira de la instalación. Los tokens guardados se eliminan.
* **En Atlassian:** la persona que lo conectó puede quitar CodeWarden en [id.atlassian.com](https://id.atlassian.com) → **Connected apps**, o un administrador del sitio puede quitar la app del sitio.

Conectar, elegir un sitio, desconectar y la rotura de una conexión aparecen en el [registro de actividad](https://docs.codewarden.co/es/console/activity-log.md) de la organización.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.