Configurar Integraciones

Configura Jira y Confluence para que RaiSE pueda gestionar tu backlog y publicar documentación. Desde v2.4, la mayor parte del setup está automatizado — proporcionas credenciales y Rai descubre el resto.

Principio de diseño: Los archivos de configuración (.raise/*.yaml) se versionan en el repo — describen a qué conectarse. Las credenciales (tokens API, emails) viven en variables de entorno — identifican quién se conecta. Nunca necesitas buscar claves de proyecto, IDs de workflow o claves de espacio manualmente.

Quick Start (2 minutos)¶

Si solo quieres comenzar rápido:

# 1. Instalar dependencias de adaptadores
pip install "raise-cli[jira,confluence]"

# 2. Establecer credenciales (agregar a .bashrc/.zshrc para persistencia)
export JIRA_API_TOKEN="your-token"
export JIRA_EMAIL="[email protected]"
export CONFLUENCE_API_TOKEN="your-token"
export CONFLUENCE_USERNAME="[email protected]"

# 3. Ejecutar el skill de setup
/rai-adapter-setup

# 4. Verificar
rai doctor

Eso es todo. Rai descubre tus proyectos, espacios, workflows y tipos de issue, genera YAML validado y lo escribe. El resto de esta guía explica qué está pasando internamente y cómo personalizar.

Prerrequisitos¶

Herramienta	Versión	Propósito
`raise-cli`	2.4.0+	CLI principal
`raise-cli[jira]`	opcional	Adaptador Jira (`atlassian-python-api`)
`raise-cli[confluence]`	opcional	Adaptador Confluence (`atlassian-python-api`)

# Instalar ambos adaptadores
pip install "raise-cli[jira,confluence]"

No se necesitan herramientas CLI externas — ambos adaptadores son Python puro.

1. Autenticación¶

Ambos adaptadores usan tokens API de Atlassian (el mismo token funciona para Jira y Confluence en el mismo sitio).

Crear un token API¶

Ve a https://id.atlassian.com/manage-profile/security/api-tokens
Create API token — cópialo inmediatamente (se muestra solo una vez)
El token funciona para todos los productos Atlassian Cloud en tu sitio

Establecer variables de entorno¶

Agrégalas a tu perfil de shell (.bashrc, .zshrc o .env):

# Jira
export JIRA_EMAIL="[email protected]"
export JIRA_API_TOKEN="ATATT3x..."

# Confluence
export CONFLUENCE_USERNAME="[email protected]"
export CONFLUENCE_API_TOKEN="ATATT3x..."

Multi-instancia — si tu organización tiene múltiples sitios Atlassian, usa variables específicas de instancia:

export JIRA_API_TOKEN_HUMANSYS="token-for-humansys"
export JIRA_API_TOKEN_CLIENTSITE="token-for-client"

Orden de resolución: {VAR}_{INSTANCIA} → {VAR} (fallback genérico).

2. Setup Automatizado — `/rai-adapter-setup`¶

El skill de setup automatiza la configuración a través de una conversación. Ejecútalo y responde 3-4 preguntas:

/rai-adapter-setup

Qué sucede:

Detectar — Rai verifica qué credenciales están disponibles y qué configs ya existen
Descubrir — Rai consulta tu instancia de Atlassian para encontrar:
Jira: todos los proyectos, estados de workflow, tipos de issue
Confluence: todos los espacios y su estructura
Seleccionar — Eliges qué proyectos/espacios incluir
Generar — Rai produce YAML de configuración que pasa validación de esquema
Escribir — Tras tu aprobación, la config se guarda en .raise/

Ejemplo de flujo:

> /rai-adapter-setup

Credenciales de Jira detectadas (JIRA_API_TOKEN está configurado)
Credenciales de Confluence detectadas (CONFLUENCE_API_TOKEN está configurado)

¿Qué adaptadores configurar? [jira/confluence/ambos]
> ambos

Descubriendo Jira... Encontrados 39 proyectos.
¿Qué proyecto(s) incluir? [keys separadas por coma o 'all']
> RAISE, RTEST

Descubriendo Confluence... Encontrados 115 espacios.
¿Qué espacio usar?
> RaiSE1

[Muestra vista previa del YAML generado]

¿Escribir config en .raise/jira.yaml? [y/n]
> y

¿Escribir config en .raise/confluence.yaml? [y/n]
> y

Ejecutando rai doctor para verificar... Todas las verificaciones de adaptadores pasan.

Qué descubre el generador automáticamente¶

Sección	Fuente	Equivalente manual
Proyectos	API `list_projects()`	Buscar keys en UI de Jira
Estados de workflow	API `get_status_for_project()`	Verificar configuración del tablero
Mapeo de estados	Slugificado desde nombres de estado	Mapear nombres a IDs a mano
Tipos de issue	API `issue_createmeta_issuetypes()`	Verificar configuración del proyecto
Espacios	API `get_all_spaces()` (paginada)	Navegar admin de Confluence

Qué todavía configuras manualmente¶

El generador no puede descubrir todo. Estas secciones necesitan input humano:

Sección	Por qué	Cómo
`workflow.lifecycle_mapping`	Mapea eventos de ciclo de vida de RaiSE a transiciones de Jira	Agregar tras el setup — ver Mapeo de Ciclo de Vida
`team`	Miembros del equipo, roles, áreas de foco	Agregar manualmente a `jira.yaml`
`routing` (Confluence)	Dónde publicar cada tipo de artifact	Defaults proporcionados; personalizar por proyecto

3. Configuración Manual¶

Si prefieres control total o necesitas personalizar más allá de lo que provee el generador.

3.1 Jira — `.raise/jira.yaml`¶

Versionado en el repo. Describe la instancia, proyectos, workflows y equipo.

default_instance: humansys

instances:
  humansys:
    site: humansys.atlassian.net
    projects: [RAISE, RTEST]

projects:
  RAISE:
    instance: humansys
    name: RAISE
    category: Development
    description: Desarrollo del framework RaiSE
    board_type: scrum
  RTEST:
    instance: humansys
    name: RaiSE Test Sandbox
    category: Testing
    board_type: scrum

# Workflow — generado automáticamente por /rai-adapter-setup
workflow:
  states:
    - name: Backlog
      category: new
    - name: Selected for Development
      category: new
    - name: In Progress
      category: indeterminate
    - name: Done
      category: done

  status_mapping:
    backlog: Backlog
    selected-for-development: Selected for Development
    in-progress: In Progress
    done: Done

  # Manual — mapea eventos de ciclo de vida de RaiSE a transiciones de Jira
  lifecycle_mapping:
    story_start: 31      # ID de transición para "In Progress"
    story_close: 41      # ID de transición para "Done"
    epic_start: 31
    epic_close: 41
    selected: 21
    backlog: 11

# Tipos de issue — generados automáticamente
issue_types:
  - name: Epic
  - name: Story
  - name: Bug
  - name: Task
  - name: Sub-task

# Manual — sección de equipo
team:
  - name: Tu Nombre
    identifier: [email protected]
    role: lead-dev
    focus: product, architecture

Mapeo de Ciclo de Vida¶

El lifecycle_mapping conecta eventos de ciclo de vida de story/epic de RaiSE con transiciones de Jira. Para encontrar tus IDs de transición:

rai backlog get RAISE-123    # cualquier issue existente
# Ver transiciones disponibles

O pregúntale a Rai:

¿Cuáles son las transiciones disponibles para el issue RAISE-123?

3.2 Confluence — `.raise/confluence.yaml`¶

Mínimo (instancia única):

url: "https://yoursite.atlassian.net/wiki"
space_key: "MYSPACE"

Completo (con enrutamiento):

default_instance: humansys

instances:
  humansys:
    url: "https://humansys.atlassian.net/wiki"
    space_key: "RaiSE1"
    instance_name: "humansys"
    routing:
      adr:
        parent_title: "Arquitectura"
        labels: ["adr", "arquitectura"]
      developer:
        parent_title: "Docs de Desarrollador"
        labels: ["developer-docs"]

El enrutamiento controla dónde coloca rai docs publish <type> las páginas y qué etiquetas les aplica. Sin enrutamiento, las páginas se crean en la raíz del espacio sin etiquetas.

4. Verificación — `rai doctor`¶

Tras el setup, ejecuta el doctor para verificar que todo funciona:

rai doctor

La verificación de adaptadores valida tres niveles:

Nivel	Qué verifica	Fallo
Config	`.raise/jira.yaml` y `.raise/confluence.yaml` existen	WARN — ejecutar `/rai-adapter-setup`
Credenciales	Tokens API y usernames están configurados	ERROR — establecer variables de entorno
Conectividad	El backend es alcanzable (modo online)	ERROR — verificar token/red

Para verificaciones de conectividad en vivo:

rai doctor --online

5. Flujos de Trabajo Diarios con Rai¶

Una vez configurados, los adaptadores potencian tu trabajo diario a través de Rai. Esto es lo que se vuelve posible:

Gestión de Backlog (Jira)¶

# Buscar issues
rai backlog search "project = RAISE AND status = 'In Progress'" -n 10

# Obtener detalles de issue
rai backlog get RAISE-1187

# Crear issues
rai backlog create "Corregir bug de paginación" -p RAISE -t Bug

# Transicionar issues
rai backlog transition RAISE-1187 done

# Vincular issues
rai backlog link RAISE-1187 RAISE-1130 "is caused by"

# Agregar comentarios
rai backlog comment RAISE-1187 "Corregido en commit abc123"

Publicación de Documentación (Confluence)¶

# Publicar un ADR
rai docs publish adr --title "ADR-045: Protocolo Doctor"

# Buscar docs
rai docs search "adapter setup" -n 5

# Obtener una página
rai docs get 12345678

Cómo los Skills Usan los Adaptadores¶

Los adaptadores no son solo herramientas CLI — son consumidos por los skills de RaiSE a lo largo del ciclo de vida:

Skill	Uso de Jira	Uso de Confluence
`/rai-story-start`	Transiciona issue a In Progress	—
`/rai-story-close`	Transiciona issue a Done	—
`/rai-epic-start`	Crea issue Epic si es necesario	—
`/rai-epic-close`	Transiciona Epic a Done	—
`/rai-epic-docs`	—	Publica documentación del epic
`/rai-session-start`	Carga contexto del sprint	—
`/rai-doctor`	Valida salud del adaptador	Valida salud del adaptador
`/rai-adapter-setup`	Descubre proyectos + workflows	Descubre espacios

Uso Conversacional¶

También puedes trabajar con Rai conversacionalmente:

> ¿Qué hay en mi sprint actual?
> Muéstrame todos los bugs en RAISE
> Crea una story para agregar soporte OAuth
> Mueve RAISE-1200 a Done
> Publica el doc de diseño de E1130 en Confluence

Rai traduce tu intención en los comandos CLI y llamadas API correctas.

6. Resolución de Problemas¶

Síntoma	Causa	Solución
`No Jira API token found`	Variable de entorno faltante	`export JIRA_API_TOKEN="..."`
`No Confluence API token found`	Variable de entorno faltante	`export CONFLUENCE_API_TOKEN="..."`
`ImportError: atlassian-python-api`	Dependencia opcional faltante	`pip install "raise-cli[jira,confluence]"`
`401 Unauthorized`	Token o email incorrecto	Regenerar token en id.atlassian.com
`default_instance 'X' not found`	Nombre de instancia no coincide	Verificar que `default_instance` coincide con clave de `instances:`
`Space 'X' not found`	Clave de espacio incorrecta	Ejecutar `/rai-adapter-setup` para descubrir espacios disponibles
Doctor muestra WARN para config	Archivo de config faltante	Ejecutar `/rai-adapter-setup`
Doctor muestra ERROR para token	Variable de entorno no configurada	Verificar perfil de shell, reiniciar terminal
Discovery retorna tipos de issue vacíos	Incompatibilidad de versión API	Corregido en v2.4.0 — actualizar raise-cli
Discovery retorna menos espacios de los esperados	Bug de paginación	Corregido en v2.4.0 (RAISE-1187)

Checklist Rápido para Nuevos Devs¶

[ ] Instalar dependencias de adaptadores: pip install "raise-cli[jira,confluence]"
[ ] Crear token API en https://id.atlassian.com/manage-profile/security/api-tokens
[ ] Establecer variables de entorno en el perfil de shell (JIRA_API_TOKEN, JIRA_EMAIL, CONFLUENCE_API_TOKEN, CONFLUENCE_USERNAME)
[ ] Ejecutar /rai-adapter-setup — responder 3-4 preguntas
[ ] Verificar con rai doctor
[ ] Probarlo: rai backlog search "project = YOURPROJECT" -n 3