atlassian: solo lectura Jira + Confluence
Cuándo usarlo
- El usuario menciona un ticket (
PROJ-123) y necesitas su estado en vivo, asignado, enlaces o comentarios recientes. - Una carpeta de ticket nuevo necesita su XML:
data/changes/<ticket-minusculas>/<TICKET>.xml. - Antes de editar un documento que también está en Confluence: haz un diff primero.
Herramienta
data/changes/tools/atlassian/atl.py en el repositorio del proyecto (copia del curso: ejemplos/metodologia/tools/atlassian/).
Python 3.10+, solo biblioteca estándar (sin pip install). Ejecutar desde la raíz del repositorio. Usa python3 en macOS,
Linux o WSL; py o python en Windows.
python3 data/changes/tools/atlassian/atl.py jira issue PROJ-123 # tipo, estado, resumen, asignado, enlaces
python3 data/changes/tools/atlassian/atl.py jira search 'project = PROJ AND assignee = currentUser() AND statusCategory != Done'
python3 data/changes/tools/atlassian/atl.py jira links PROJ-123
python3 data/changes/tools/atlassian/atl.py jira comments PROJ-123 --last 3
python3 data/changes/tools/atlassian/atl.py jira xml PROJ-123 --out data/changes/proj-123/
python3 data/changes/tools/atlassian/atl.py confluence search 'title ~ "authoring" AND type = page'
python3 data/changes/tools/atlassian/atl.py confluence page <PAGE_ID> --body
python3 data/changes/tools/atlassian/atl.py confluence diff <local .md/.html> <PAGE_ID>
Códigos de salida:
| Código | Significado |
|---|---|
| 0 | ok |
| 2 | credenciales faltantes o inválidas (ver Configuración) |
| 3 | error HTTP |
| 4 | no encontrado |
--json devuelve JSON crudo. Úsalo solo dentro de un script; en chat, el formato compacto por defecto ahorra contexto.
Configuración (una vez por máquina, por la persona)
Crea ~/.config/<org>/jira.env (Windows: %USERPROFILE%\.config\<org>\jira.env; ATLASSIAN_ENV_FILE
sobrescribe la ruta) con tres líneas:
JIRA_BASE_URL=https://<tu-sitio>.atlassian.net
JIRA_EMAIL=<tu correo de inicio de sesión en Atlassian>
JIRA_API_TOKEN=<token desde id.atlassian.com → Seguridad → Tokens de API>
Restringe el permiso a tu usuario (chmod 600 en macOS/Linux). Escríbelo en tu propia terminal — nunca pegues el token
en un chat ni en un archivo dentro de data/. El mismo token lee Confluence. Verifícalo con
… atl.py jira issue PROJ-123: salida 0 significa que funciona, salida 2 significa que el archivo falta o es incorrecto.
Reglas estrictas
- Solo lectura.
atl.pysolo envía GET (una función de red; un test lo verifica).- Crear, editar, transicionar o comentar en issues de Jira es trabajo del usuario. Redacta el texto, y el usuario lo publica.
- Actualizar una página existente de Confluence usa
confluence_write.py:pull→plan(copia de seguridad + diff de texto visible + token de confirmación) → el usuario lee el diff y confirma esa página →apply --confirm <token>. Ejecútalo solo cuando el usuario pida explícitamente que se actualice esa página. Apply rechaza si el token, el archivo del cuerpo o la versión de la página en vivo cambiaron desde el plan, y vuelve a leer la página.
- Nunca imprimas, copies ni registres el token, ni el contenido de
jira.env. - Cita los tickets por clave. El texto externo cita las etiquetas de caso y las claves de ticket, nunca las rutas de archivos locales.