Exportación o restablecimiento de Git

Nota: En febrero de 2025, se lanzó una nueva versión de esta integración. Los usuarios de la versión anterior pueden proporcionar tokens sin usar secretos. La siguiente documentación se aplica principalmente a la nueva versión.

Dialogflow CX se integra en varios proveedores de Git (GitHub, GitLab, Bitbucket y otros). Esta integración facilita la exportación de tu agente a JSON para enviarlo a un proveedor de Git y extraerlo de un proveedor de Git para restablecer el agente. El formato exportado de JSON que se envía a un proveedor de Git es el contenido del archivo ZIP expandido del agente exportado.

El uso de esta función te permite aprovechar las funciones de control de código fuente de un proveedor de Git, como las siguientes:

• Revisiones de cambios de agentes con herramientas de revisión de código
• Examinar las diferencias entre agentes con herramientas de comparación
• Combinaciones

Limitaciones

Se aplica la siguiente limitación:

• [Solo para la versión de integración anterior] Las APIs de GitHub tienen una limitación en la cantidad de archivos que se pueden actualizar en una sola confirmación. Si la cantidad de archivos supera los 500, es posible que no puedas enviar contenido a GitHub desde Dialogflow CX. En esos casos, puedes exportar el agente como un archivo ZIP y usar la CLI de Git en tu máquina para enviar los archivos del agente a GitHub. Esta limitación se abordará en una versión posterior de Dialogflow CX.
• No se admiten los repositorios autohospedados de acceso privado de GitHub, ya que Dialogflow CX no puede acceder a ellos.
• El repositorio de Git no puede contener ningún archivo que no sea el que se exportó con la exportación de agentes. Cualquier otro archivo del repositorio se quitará en cada envío.

Configuración

Para configurar esta función, debes adquirir un token de acceso de tu proveedor de Git, almacenarlo en Secret Manager y proporcionar el recurso de Secret a Dialogflow CX:

Token de acceso

Para adquirir un token de acceso de tu proveedor de Git, haz lo siguiente:

GitHub

Debes adquirir un token personal de GitHub. Si usas un token de acceso personal detallado, necesitas los siguientes permisos de acceso:

• Repository Permissions > Contents: Read and write
• Repository Permissions > Metadata: Solo lectura (debe seleccionarse automáticamente después de seleccionar el permiso Contents)

GitLab

Debes adquirir un token de acceso personal de GitLab.

Bitbucket

Debes adquirir un token de acceso de Bitbucket.

Secret Manager

Ahora que tienes un token de acceso, debes crear un Secret para tu token:

1. Habilita la API de Secret Manager.
2. Crea un secreto.

Configuración de Dialogflow CX

Para configurar esta integración en Dialogflow CX, sigue estos pasos:

1. Proporciona al agente de servicio de Dialogflow permiso para acceder al secreto del token de acceso en Secret Manager. Proporciona el rol Secret Manager Secret Accessor a la cuenta de servicio gcp-sa-dialogflow. en tu proyecto de agente. Consulta Otorga acceso al Secret de Secret Manager.
2. Abre la configuración de la integración de Git:
   • Consola de Agentes conversacionales
     1. Abre la pantalla de configuración haciendo clic en el ícono de configuración cerca de la esquina superior derecha.
     2. Desplázate hacia abajo y haz clic en Agregar integración de Git.
   • Consola de Dialogflow CX
     1. Haz clic en la pestaña Administrar.
     2. Haz clic en Git en la sección Pruebas e implementación.
     3. Haz clic en Crear nueva.
3. Proporciona los detalles de configuración:
   1. Ingresa lo siguiente:
      • Es el nombre visible de la conexión de GitHub.
      • Es la URL del repositorio de Git (por ejemplo: https://github.com/<path-to-repo>.git).
      • Agrega las ramas de Git con las que interactuará tu agente. Para designar una rama como predeterminada, haz clic en el ícono de estrella junto a ella.
      • Secreto del token de acceso, que es la versión del secreto que creaste con el formato projects/*/secrets/*/versions/* para una versión específica o projects/*/secrets/*/versions/latest para la versión más reciente.
   2. Haz clic en Conectar.
   3. El servicio de Git puede tardar un minuto en estar listo. La consola mostrará notificaciones.

Envía y restablece

Una vez configurado, puedes enviar o extraer tu agente a Git o desde Git.

El botón Enviar se usa para exportar tu agente y realizar una confirmación en la rama de Git seleccionada en el menú desplegable de la rama de Git. Esta confirmación consistirá en todo el agente y no en cambios específicos, y borrará los archivos existentes en el repositorio.

Los usuarios con roles de lector de Dialogflow pueden enviar contenido a los repositorios de Git. Para evitar envíos no deseados, configura estos agentes con tokens de acceso personal de solo lectura.

El botón Restablecer se usa para extraer los datos de tu agente de la rama de Git seleccionada en el menú desplegable de la rama de Git y restablecer tu agente de Dialogflow CX a partir de estos datos. Esto reemplazará tu agente de la misma manera que se comporta cualquier restablecimiento de agente.

Ejemplo de caso de uso

En el siguiente ejemplo, se ilustra cómo varias personas pueden usar esta función para proponer diferentes cambios de agente a un agente de producción.

Considera que tu agente usa las siguientes ramas de Git:

• Prod: Rama para tu agente de producción
• Dev1: Rama para el desarrollo de agentes
• Dev2: Otra rama para el desarrollo de agentes

El usuario 1 quiere proponer cambios en el agente y sigue estos pasos:

1. Exporta el agente de producción a un agente nuevo.
2. Realiza los cambios que desees en esta copia del agente.
3. Prueba los cambios.
4. Envía el agente modificado a la rama Dev1.
5. Crea una solicitud de combinación para la rama Prod.

El usuario 2 quiere proponer cambios en el agente y sigue estos pasos:

1. Exporta el agente de producción a un agente nuevo.
2. Realiza los cambios que desees en esta copia del agente.
3. Prueba los cambios.
4. Envía el agente modificado a la rama Dev2.
5. Crea una solicitud de combinación para la rama Prod.

El usuario 3 revisa las solicitudes de combinación de ambos usuarios y sigue estos pasos:

1. Resuelve conflictos.
2. Confirma los cambios aprobados.
3. Restablece la rama de Git de producción al agente de Dialogflow CX de producción.