Manual del administrador

GobernIA · Gobernanza de agentes de IA dentro de Jira Service Management · metodología AIGOV · por Prodeo Innovation

Para quién es esta página. Para la persona que administra el sitio de Jira Service Management y opera la página de la app.

Qué resuelve. Cómo simular, cómo aplicar, cómo dar de alta un agente, cómo leer el sello y la bitácora, y qué hacer cuando la pantalla dice algo que no esperabas.

Si acaba de instalar la app, este no es su primer documento: es Empezar acá, que trae el camino en orden y lo que tiene que tener listo antes. Este manual es la referencia de operación: lo abre cuando ya está adentro.

Describe el producto tal como está construido hoy. Si una frase le parece demasiado modesta, es a propósito.

---

1. Qué hace la consola y qué no

La consola compara su sitio con el modelo AIGOV, le muestra el plan paso a paso, lo simula sin escribir nada y, después de una confirmación deliberada, aplica los pasos que sabe ejecutar. Los demás pasos salen como especificación, con su motivo, para completarlos a mano.

La app no declara salida de datos fuera de Atlassian, y todo su estado vive en el almacenamiento de la propia app.

2. Antes de instalar

2.1 Requisitos del sitio

• Jira Service Management Cloud con Assets. El modelo guarda los despliegues de agentes en Assets. Qué plan de Jira Service Management incluye Assets conviene confirmarlo con Atlassian: no lo damos por sentado.
• Confluence en el sitio, sólo para el testigo diario del sello. La app instala y funciona en Jira igual sin Confluence, pero el testigo diario necesita dónde escribir: está comprobado que en un sitio sin Confluence esa pieza no funciona. Sin Confluence el testigo no se publica y el sello no tiene esa referencia externa; es una condición del sitio, no un defecto de la app.
• Una persona con el permiso global Administrar Jira para aplicar en producción.
• El proyecto de Jira Service Management de gobernanza. Si ya existe, la app lo adopta; si no existe, lo crea. La plantilla con la que nace es un parámetro del producto: sin ella el proyecto nacería sin los tipos de solicitud que el modelo necesita, y el plan lo dice en vez de crearlo mal.
• Un ícono de Assets disponible. Assets exige un ícono para cada tipo de objeto y la API no permite subir uno: la consola usa uno que el sitio ya tenga (ver §4.5).

2.2 Permisos que verá quien consienta la instalación

La app declara sus permisos en el manifiesto, y quien instala los ve en la pantalla de consentimiento. Casi todos los ejerce algún código hoy. Uno está declarado por adelantado y todavía no lo llama ninguna línea: la lectura de usuarios de Jira, que necesitan dos piezas que existen en el producto pero todavía no se ejecutan solas (§6 y la página de alcance).

Confluence aparece en esa pantalla, y el código sí lo usa: el testigo diario del sello publica la página, la relee y la verifica al día siguiente contra la cadena de la bitácora.

Los permisos se declararon por adelantado porque agregar uno después obliga a una versión mayor y a un nuevo consentimiento de cada sitio. Los textos de privacidad y del listing lo dicen.

2.3 Qué datos guarda

El único dato personal es el identificador de cuenta de Atlassian de quien opera la consola, en un registro; todo lo demás guarda un alias opaco. Un disparador diario reporta esas cuentas a Atlassian y borra el registro cuando la cuenta se cierra.

Esto está implementado y probado contra dobles, y todavía no se comprobó contra la API real de Atlassian. Por eso no lo prometemos como medido. El detalle está en la política de privacidad del producto.

2.4 Ambientes

La app distingue desarrollo, preproducción y producción.

• Fuera de producción la consola no exige el permiso de administrador y lo dice en pantalla («Ambiente no productivo: no se exige autorización de administrador»).
• En producción, Aplicar exige Administrar Jira, comprobado contra Jira en el momento. Una instalación desde Marketplace corre en producción.
• Antes del primer despliegue a producción hay que fijar la variable de ambientes declarados; si falta, Aplicar se rehúsa nombrándola.

2.5 Licencia

La licencia es la nativa de Atlassian. Con una licencia inactiva la consola queda en modo restringido: se puede consultar, simular y leer el sello y la bitácora, y Aplicar se detiene con un mensaje que dice que es una condición comercial, no una decisión de gobernanza. Nada se borra.

Esto está probado contra dobles y contra una licencia simulada; todavía no se comprobó con una licencia real de Marketplace.

Una instalación directa, fuera del Marketplace, no tiene mecanismo comercial por decisión: es un camino de piloto, no un canal de venta.

3. La consola, panel por panel

La app pone una sola página en la administración de Jira, con una sola entrada en Configuración de Jira → Aplicaciones. Adentro hay cinco pestañas. Todo el texto está en español; no hay versión en otro idioma.

Cada pestaña entra en un momento distinto del ciclo de gobernanza; el ciclo completo está en Empezar acá.

Si leyó una versión anterior de esta documentación: hasta el 9 de noviembre de 2026 eran tres páginas (aprovisionamiento, alta de agentes y tablero), y dos de ellas no se podían abrir desde el menú de Jira. Ahora es una sola, y cada una de aquellas es una pestaña. El alta dejó de operarse pegando un JSON: es un formulario por pasos, y el JSON quedó como «Importar lote (JSON)», una opción secundaria.

La página está hecha con Custom UI (HTML, CSS y React propios de la app, con sus tipografías incluidas) y sigue sin declarar salida de datos fuera de Atlassian. Cada pestaña es su propia pantalla: si una falla, no tira a las otras, y cambiar de pestaña no borra lo que ya cargó en otra.

Dos momentos del ciclo NO tienen pantalla en la app, y es a propósito: la aprobación ocurre en el proyecto de gobernanza de Jira Service Management, con el flujo y los aprobadores de siempre (la app no aprueba), y la consulta de la compuerta la hace la cadena de despliegue del cliente contra una URL (§4.8). Son los dos puntos donde la gobernanza se apoya en lo que la organización ya usa en vez de duplicarlo.

La pestaña «Aprovisionamiento» es la que este capítulo llama «la consola», y tiene estos paneles:

4. Operar paso a paso

4.1 Simular (sin escribir)

Simular (sin escribir) solo lee: no escribe en su sitio ni en el almacenamiento de la app. Leer un sitio grande lleva decenas de segundos, así que la simulación avanza por tramos y muestra «Leyendo la instancia: N de M elementos resueltos…». Si avanza «mucho más despacio de lo esperado», la consola se lo dice con el motivo.

Si la simulación falla, la consola muestra «No se pudo completar la operación» con el motivo original y un identificador de la petición para soporte. Nada se modificó: vuelva a pulsar Simular.

4.2 Leer el plan

• Ejecutable = Sí quiere decir que esta versión sabe escribir el paso. No quiere decir que se vaya a escribir: un paso Sin cambios no escribe nada.
• Un paso marcado «Se completa a mano (no se escribe)» no se escribe nunca: es una instrucción para hacer a mano. No es un error.
• «Media» en Confianza significa que el servicio de Atlassian que usaría todavía no se comprobó contra un sitio real.
• Bloqueos. Si el plan trae bloqueos («la aplicación no arranca hasta resolverlos»), no se puede aplicar. Un bloqueo aparece cuando hay un candidato ambiguo (dos objetos con el mismo nombre) o una diferencia destructiva con algo que declaró el modelo. La app no «arregla» eso por usted.
• El aviso de arriba suma los pasos: «X de Y pasos se ejecutan · Z no se ejecutan en esta versión · W se completan a mano por diseño». Las tres cifras suman el total del plan. Ese total cambia con cada versión del producto: el número que vale es el que le muestra la pantalla, no uno escrito en un documento.

4.3 Aplicar

1. Pulse Aplicar. Sólo se habilita con un plan vigente.
2. En producción, la consola pregunta a Jira, con su cuenta, si es administrador. Verá «Comprobando contra Jira si tu cuenta es administradora…». Si no lo es, «No podés aplicar» y no hay botón. Si no se pudo comprobar, «No se pudo comprobar tu permiso de administrador»: ante la duda se deniega.
3. El cuadro «Confirmar aplicación» muestra la huella del plan que va a aplicar. Confirme con Confirmar y aplicar. Esa confirmación es deliberada y no es un control de seguridad: quien decide si puede aplicar es Jira.
4. La corrida se encola y avanza sola, una etapa por vez, aunque cierres la página. Antes de escribir vuelve a leer el sitio: si cambió desde su simulación, se rechaza y hay que simular de nuevo.
5. Nada se borra y no hay reversión. Si un paso falla, la corrida se detiene en la frontera de esa etapa. Antes de reintentar, revise la bitácora y el sello: pudo haber escrito parte del plan.

Sólo corre una corrida a la vez por ambiente. Si otra está en curso, la nueva se rechaza. Si una corrida figura en curso pero la pantalla dice que «se le venció el turno», nadie la está sosteniendo; otra corrida podrá tomar el turno y esta quedará «Interrumpida: dejó de avanzar y se le venció el turno».

4.4 Estados de una corrida

4.5 El ícono de Assets

Assets exige un ícono por tipo de objeto. La consola lo busca en su sitio por el nombre que dice su parámetro; si no lo encuentra, hay varios con ese nombre, o no pudo leer la lista, los tipos de objeto de Assets y todo lo que se escribe sobre ellos salen como especificación. En ese caso: abra «Ícono de los tipos de objeto (Assets)», elija uno de la lista real del sitio, Usar este ícono, y simule de nuevo. La elección queda para esa instalación y, en producción, exige el mismo permiso que Aplicar.

4.6 La configuración de la organización

La pestaña «Configuración» es donde su organización fija lo que es decisión suya: por ejemplo, quién firma por un perfil sectorial, el espacio de Confluence del testigo diario o las horas hábiles en que el comité tiene que ratificar una emergencia. Esos valores no pueden venir con el producto, porque son de cada organización.

• Qué lista. Todo valor que nadie decidió todavía. La lista no se escribe a mano: si el producto suma un valor nuevo de este tipo, aparece solo.
• Qué muestra de cada uno. Quién lo decide, por qué existe, el valor que rige, el recomendado cuando alguien lo recomienda y qué pasa si falta, con el mensaje real que va a ver (no una descripción).
• Qué rige. Lo que fijes gana sobre lo que trae el producto y queda guardado en esta instalación. «Volver a lo sembrado» no borra nada.
• Quién puede guardar. Sólo una persona administradora de Jira (lo comprueba Jira). Cada cambio queda en la bitácora, con el alias de quien lo hizo y sin el valor; si la bitácora no puede escribirse, el cambio se deshace.
• Si falta un valor, no se inventa uno. Sin espacio de Confluence, el testigo no se publica; sin horas hábiles, la vigilancia de las emergencias dice cuál falta; y sin firmante sectorial definido la compuerta de despliegue no autoriza un despliegue de ese sector, nombrando el perfil. Eso no es un error: es el fallo cerrado funcionando.

4.7 Dar de alta un agente

La pestaña «Dar de alta» es el camino para registrar un despliegue; se llega también con el botón «Dar de alta un agente» de la pestaña «Agentes». Tiene tres momentos y ninguno escribe antes de tiempo.

1. Antes de empezar. Lo primero que dice es lo que falta en su sitio: nombra las direcciones y su techo, los objetos a los que las fichas apuntan, si la lectura de incidentes de Jira está enlazada y si su cuenta puede crear. Los prerrequisitos completos están en Empezar acá.
2. Completar y revisar. La ficha se completa en un formulario por pasos, no pegando un JSON. El riesgo se calcula mientras la completa y dice qué exige ese nivel —quién aprueba, cada cuánto se revisa, qué evidencia—, de modo que no se descubre al final. Revisar no escribe nada: corre la misma ejecución que crear, hasta el último chequeo. Devuelve, sin resumir, la validación de la ficha, el riesgo con sus factores y elevadores, la dirección y su techo, los perfiles que aplican y por qué, los objetos a los que la ficha apunta con su estado, y «lo que se crearía». Un lote (varias fichas) se trae con «Importar lote (JSON)», la vía secundaria: pasa por la misma revisión, de a una ficha.
3. Crear en Assets. Crea, en orden, el agente, su versión y el despliegue, y los relee para comprobarlos. Exige la huella de lo que revisó: si Assets cambió desde entonces, no escribe nada y lo dice.

Lo que hay que saber antes de prometer algo:

• Nada se aprueba. El atributo de estado de aprobación no lo escribe esta herramienta: sale como pendiente manual.
• Nada se actualiza. Si un objeto ya existe y difiere de la ficha, queda dicho en «Lo que ya existe y difiere de la ficha» y no se cambia. Corregir se corrige en Assets.
• Una escritura a la vez. El alta toma el mismo turno que una corrida de aprovisionamiento.
• Si el riesgo queda incompleto, no hay nivel y no se crea nada. «Incompleto» no es un nivel y no autoriza nada; la pantalla nombra qué falta.
• Algunos valores que la ficha admite todavía no tienen equivalente en el catálogo de Assets. Con uno de ellos la ficha es válida y no se puede crear; el mensaje nombra el atributo. Las equivalencias que ya están resueltas son un parámetro del producto, a la espera de que una persona las ratifique; las que el modelo no contesta quedan declaradas como sin decidir en vez de inventadas.
• Si se cortó a mitad, la respuesta dice qué quedó creado. Nada se borra.

4.8 La compuerta de despliegue

Su cadena de integración continua le pregunta a la app, por HTTP y con la huella del cambio, si un despliegue está autorizado. La app responde una de seis salidas y nada más:

Su cadena de despliegue tiene que tratar cualquier estado distinto de 200 como NO autorizado. Una salida no declarada y una excepción responden 424, que no está en esa lista. Nada, salvo 200, autoriza.

Para ponerla en marcha: obtener la URL de la compuerta para su instalación, emitir la credencial desde la sección «Compuerta de despliegue (Gate 3)» de la pestaña «Aprovisionamiento» —se entrega una sola vez— y guardarla como secreto de su cadena.

La autorización se consume una sola vez. Pedirla de nuevo sin un cambio nuevo responde sin_cambio.

4.9 La vigilancia diaria y su tablero

Un disparador programado corre todos los días y recorre sus lotes: revisiones periódicas vencidas, excepciones vencidas, combinación prohibida y el cierre del día (que re-emite el sello degradado con lo que los verificadores releyeron y publica el testigo en Confluence, si hay espacio fijado). Las pestañas «Panorama» y «Agentes» muestran, sólo en lectura (ninguna escribe en su sitio), cada lote con su estado, su última corrida completa, cuántos días lleva sin completar, y los criterios que no están en verde.

Un lote «incompleto» no siempre es una falla suya. La vigilancia detecta y lo deja escrito; actuar sigue siendo de una persona. Hoy no se ejecutan solos: abrir una solicitud en Jira Service Management, escribir el estado del despliegue y avisar al comité de gobierno de IA. El lose lo dice en vez de fingir que los hizo, y no se simulan ni se aplican a medias.

El lote de emergencias queda fallido todos los días a propósito: leer la ratificación posterior exige servicios cuya forma todavía no está comprobada, así que el lote nombra qué falta. Es preferible a que diga «cero emergencias» porque no puede mirar.

Lo que falta para cablear esos efectos es una comprobación autorizada contra un sitio real, no código.

5. Qué se ejecuta y qué no

• La mayor parte del plan va por API y se ejecuta, siempre que el ícono de Assets esté resuelto en el sitio. Sin ícono resuelto, la parte de Assets no se ejecuta: los tipos de objeto, sus atributos y sus objetos salen como especificación, porque Assets exige un ícono para crear un tipo y su API no permite subir uno. Es el paso que más trabajo ahorra.
• No se ejecutan en ningún caso los filtros de consulta sobre los campos de Assets: se comprobó y el resultado fue negativo. No hay API pública; la ruta interna exige atributos que el modelo no declara y, una vez escrita, no se puede releer. Salen como especificación, con ese motivo escrito.
• Se completan a mano por diseño: aprobaciones, colas, permisos y acuerdos de nivel de servicio (Atlassian no ofrece API pública de configuración para eso; de las colas, la app sólo puede leer), un grupo de tipos de solicitud que no tienen API de creación, y el contenido de las pantallas (la API crea el contenedor vacío; qué campo va en qué pestaña se arma a mano).
• Después de aplicar, la vigilancia relee esas configuraciones manuales y las compara con el modelo.
• La cantidad exacta de pasos cambia con cada versión. El número que vale es el que muestra la pantalla del plan.

Los contenidos de gobernanza —política aprobada, techos por dirección, responsables— no se aprovisionan: son del cliente. El producto no los inventa.

6. El sello

• Verde = todo creado o adoptado. Amarillo = hay pendientes manuales o no verificables. Rojo = algo falló o difiere.
• El sello de esta versión es amarillo por diseño y se queda amarillo. Hay secciones del modelo que Atlassian no deja configurar por API y salen como especificación manual, y hay criterios que el propio modelo declara sin con qué compararlos — por ejemplo la cola «Por aprobar — mías», que queda no verificable mientras el modelo no le dé un criterio comprobable. Un sello en verde sería mentira. Si alguien le pide «dejarlo en verde», es un pedido que el producto no puede cumplir y no debe cumplir. Cómo explicárselo al cliente: Empezar acá.
• El sello está firmado; la consola recalcula la firma al mostrarlo («Firma válida» / «Firma NO coincide»). La firma detecta una alteración accidental; no protege contra una persona con acceso al almacenamiento de la app, ni es no repudio. Lo que sí lo refuerza es el testigo diario en Confluence: publica la cabeza de la bitácora y la firma del sello fuera del almacén, y al día siguiense lo relee y degrada el sello si no coincide. Se declara en el sello sólo si fijó el espacio de Confluence en la pestaña «Configuración».

7. La bitácora

Registro encadenado de cada operación y de cada rechazo, de la más reciente a la más antigua. Cada entrada guarda quién, cuándo (hora de Costa Rica y UTC), qué acción, sobre qué elemento y con qué resultado. «Cadena íntegra» o «Cadena rota: una entrada fue alterada».

• El actor es quien operó la consola, no quien aprobó un cambio. La bitácora registra lo que hizo la app. No sirve para saber quién ejerció un rol de gobernanza: eso se verifica a mano, con la lista de verificación de traspaso.
• La columna del actor muestra el identificador de cuenta de Atlassian que la app resuelve desde el alias guardado; no muestra el nombre de la persona. Si la cuenta se cerró en Atlassian, ya no se puede resolver y aparece el alias con la nota «(cuenta cerrada)».
• Que la bitácora sea «sólo de agregar» es disciplina de diseño más la cadena de huellas: el almacenamiento no lo garantiza, y qué ocurre exactamente con escrituras simultáneas todavía no está comprobado. No lo prometemos como garantía técnica.

8. Cuando algo sale mal

Qué NO hace la app cuando falla: no reintenta en silencio y no marca «completada» algo que no comprobó. Una corrida que no puede registrar ni su propio fallo deja que la plataforma la reintente, que es la única forma de que el fallo quede registrado.

9. Qué contestar cuando el cliente pregunta

---

Dónde seguir

---

GobernIA 2.4.0 · 9 de noviembre de 2026