zendesk-guide-theme-import-from-github
eesel Team
Last edited 25 febrero 2026
{
"title": "Cómo importar un tema de Zendesk Guide desde GitHub",
"slug": "zendesk-guide-theme-import-from-github",
"locale": "es",
"date": "2026-02-25",
"updated": "2026-02-25",
"template": "default",
"excerpt": "Una guía práctica para importar y gestionar temas de Zendesk Guide directamente desde GitHub, incluyendo la configuración del desarrollo local y los flujos de trabajo en equipo.",
"categories": [
"Guides",
"Zendesk"
],
"tags": [
"Zendesk",
"GitHub",
"Help Center",
"Theme Development",
"ZCLI"
],
"readTime": 9,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Cómo importar un tema de Zendesk Guide desde GitHub",
"description": "Una guía práctica para importar y gestionar temas de Zendesk Guide directamente desde GitHub, incluyendo la configuración del desarrollo local y los flujos de trabajo en equipo.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-89e34146-a9bc-4c22-b3df-5e6f7b400990"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-89e34146-a9bc-4c22-b3df-5e6f7b400990",
"coverImageAlt": "Imagen del banner para Cómo importar un tema de Zendesk Guide desde GitHub",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Preguntas Frecuentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "¿Puedo usar la integración de GitHub con cualquier plan de Zendesk?",
"answer": "No. La integración de GitHub para los temas de Zendesk Guide requiere al menos Growth Suite con Guide Professional, o cualquier Professional o Enterprise Suite. Los planes Team y Guide Lite no incluyen esta función."
},
{
"question": "¿Qué sucede si edito un tema gestionado por GitHub directamente en Zendesk?",
"answer": "Zendesk le advertirá que realizar cambios en la interfaz de administración romperá la conexión de GitHub. Si continúa, el tema se convierte en un tema personalizado normal y deberá sincronizar manualmente los cambios con GitHub si desea restaurar la integración."
},
{
"question": "¿Puedo importar varios temas desde el mismo repositorio de GitHub?",
"answer": "No, cada repositorio solo puede contener un tema. Sin embargo, puede usar diferentes ramas dentro del mismo repositorio e importar cada rama como un tema separado en Zendesk. Esto es útil para gestionar las versiones de prueba y producción."
},
{
"question": "¿La integración de GitHub funciona con GitHub Enterprise Server?",
"answer": "No, la integración es compatible con GitHub Enterprise Cloud, pero no con GitHub Enterprise Server. Si está utilizando GitHub Enterprise Server, puede utilizar la API de temas para crear su propia integración."
},
{
"question": "¿Cómo actualizo mi tema después de la importación inicial?",
"answer": "En la administración de Knowledge, busque su tema, haga clic en el menú de tres puntos y seleccione 'Actualizar desde GitHub'. Zendesk recupera el código más reciente de su repositorio. Puede obtener una vista previa de los cambios antes de publicarlos en vivo."
},
{
"question": "¿Puedo usar ZCLI con un tema que descargué de Zendesk?",
"answer": "Sí. Cualquier tema de Zendesk Guide se puede previsualizar localmente con ZCLI. Descargue el tema como un ZIP, extráigalo y ejecute 'zcli themes:preview' desde el directorio del tema."
}
],
"supportLink": null
}
}
Gestionar un tema del centro de ayuda directamente en la interfaz de administración de Zendesk funciona bien para pequeños ajustes. Pero una vez que empiezas a hacer cambios significativos o a trabajar con un equipo, rápidamente te encuentras con limitaciones. No hay control de versiones, ni forma de rastrear quién cambió qué, ni un método fácil para probar los cambios antes de que se publiquen.
Ahí es donde entra en juego la integración de GitHub. Al conectar tu tema de Zendesk Guide a un repositorio de GitHub, obtienes todos los beneficios del control de versiones: ramificación para experimentos, pull requests para la revisión del código y un historial completo de cada cambio. Tu equipo puede colaborar en el desarrollo del tema sin pisarse el trabajo, y puedes implementar actualizaciones con confianza.
Esta guía te guía a través del proceso completo de importación de un tema de Zendesk Guide desde GitHub. Tanto si empiezas con el tema oficial de Copenhague como si importas un tema personalizado existente, aprenderás a configurar la integración, a trabajar localmente con ZCLI y a establecer un flujo de trabajo que se adapte a tu equipo.
Mientras mejoras la apariencia de tu centro de ayuda, considera también cómo gestionas las interacciones con los clientes. Herramientas como eesel AI se integran directamente con Zendesk para automatizar las respuestas y clasificar los tickets, complementando tu nuevo tema con automatización inteligente.
Paso 1: Prepara tu tema en GitHub
La integración de GitHub tiene requisitos específicos sobre cómo debe estructurarse tu repositorio. Hacer esto bien desde el principio evita dolores de cabeza más adelante.
Requisitos de la estructura del repositorio
Tu repositorio de temas debe cumplir dos requisitos clave:
-
El archivo manifest.json debe estar en la raíz del repositorio Este archivo contiene metadatos del tema y definiciones de configuración. Zendesk lo busca en el nivel superior, no en subdirectorios.
-
Un tema por repositorio No puedes almacenar varios temas en un solo repositorio. Si necesitas variaciones de un tema, usa ramas en su lugar.
La estructura estándar del tema se ve así:
mi-tema-zendesk/
├── manifest.json
├── style.css
├── script.js
├── thumbnail.png
├── templates/
│ ├── header.hbs
│ ├── footer.hbs
│ ├── home_page.hbs
│ ├── article_page.hbs
│ └── ...
├── assets/
│ ├── logo.png
│ └── ...
├── settings/
│ └── ...
└── translations/
└── ...
Forking del tema de Copenhague vs. creación desde cero
Para la mayoría de los equipos, hacer un fork del tema oficial de Copenhague es el mejor punto de partida. Es el tema predeterminado de Zendesk, se mantiene activamente y está diseñado para ser responsivo y accesible. Empezar aquí significa que recibirás actualizaciones cuando Zendesk mejore el tema base.
Para hacer un fork, visita el repositorio del tema de Copenhague y haz clic en el botón Fork. Esto crea tu propia copia que puedes personalizar libremente.
Si ya tienes un tema existente en Zendesk, descárgalo de la interfaz de administración de Knowledge y súbelo a un nuevo repositorio de GitHub en su lugar.
Estrategia de ramificación para las variaciones del tema
Dado que solo puedes tener un tema por repositorio, usa ramas para gestionar las variaciones:
mainomasterTu tema de produccióndevelopEntorno de pruebas para probar los cambiosfeature/new-headerTrabajo específico de la funciónbrand/variant-aVariaciones de marca blanca para diferentes marcas
Al importar a Zendesk, puedes especificar qué rama usar, lo que facilita el mantenimiento de múltiples variaciones de tema desde el mismo repositorio.
Paso 2: Configura tu entorno de desarrollo local
Trabajar localmente te permite previsualizar los cambios al instante sin tener que subirlos a Zendesk cada vez. ZCLI hace que esto sea sencillo.
Instala ZCLI
ZCLI es la moderna herramienta de línea de comandos de Zendesk para el desarrollo de temas. Instálalo globalmente a través de npm:
npm install -g @zendesk/zcli
Verifica la instalación:
zcli --version
Autentícate con tu cuenta de Zendesk
Antes de que puedas previsualizar los temas, ZCLI necesita acceder a tu cuenta de Zendesk. Ejecuta el comando de inicio de sesión:
zcli login -i
Se te pedirá:
- Subdominio Tu subdominio de Zendesk (la parte anterior a
.zendesk.com) - Correo electrónico Tu dirección de correo electrónico de administrador de Zendesk
- Contraseña Un token de API (recomendado) o la contraseña de tu cuenta
Para crear un token de API, ve a Centro de administración > Aplicaciones e integraciones > API > API de Zendesk, luego agrega un token en la pestaña Configuración.
Clona tu repositorio de temas
Si aún no lo has hecho, clona tu repositorio de temas localmente:
git clone https://github.com/tu-org/tu-tema.git
cd tu-tema
Inicia la vista previa local
Con ZCLI autenticado y tu código de tema local, inicia el servidor de vista previa:
zcli themes:preview
Este comando:
- Sube tu tema a una ubicación temporal
- Inicia un servidor de desarrollo local
- Abre tu navegador predeterminado para previsualizar el tema
- Observa los cambios en los archivos y se recarga automáticamente
La vista previa utiliza los datos reales de tu cuenta de Zendesk, por lo que verás artículos, categorías y tickets reales renderizados con tu tema. Haz un cambio en un archivo de plantilla, guárdalo y el navegador se actualiza automáticamente.
Paso 3: Conecta Zendesk a tu repositorio de GitHub
Con tu tema listo en GitHub y el desarrollo local funcionando, es hora de establecer la conexión entre Zendesk y tu repositorio.
Navega a la integración de GitHub
En tu cuenta de Zendesk:
- Ve a Administración de Knowledge (la interfaz de gestión del centro de ayuda)
- Haz clic en Personalizar diseño en la barra lateral
- Haz clic en Añadir tema en la parte superior derecha
- Selecciona Añadir desde GitHub
Autoriza e importa
Verás un diálogo que te pide la URL de tu repositorio. Introduce la URL completa de GitHub:
https://github.com/tu-org/tu-tema
Opcionalmente, especifica un nombre de rama si quieres importar desde algo que no sea la rama predeterminada.
Haz clic en Importar. Si no has autorizado a Zendesk a acceder a GitHub antes, serás redirigido a GitHub para conceder permisos. Autoriza la aplicación de Zendesk y luego regresa a Zendesk.
El proceso de importación recupera los archivos de tu tema desde GitHub y crea un nuevo tema en tu cuenta de Zendesk. Cuando termine, verás la miniatura del tema en tu página de Temas.
Entendiendo la conexión
Esta importación inicial establece una conexión única entre tu tema de Zendesk y el repositorio de GitHub. Después de este punto, los cambios fluyen en una dirección: de GitHub a Zendesk. No puedes editar un tema gestionado por GitHub directamente en la interfaz de Zendesk sin romper la conexión.
Paso 4: Personaliza e implementa tu tema
Ahora que la integración está activa, tienes un flujo de trabajo que combina el poder del control de versiones con la fácil implementación en Zendesk.
Haciendo cambios localmente
Siempre trabaja en tu tema localmente, no en la administración de Zendesk. Aquí está el flujo de trabajo recomendado:
- Crea una rama para tus cambios:
git checkout -b feature/actualizar-encabezado - Haz ediciones a las plantillas, CSS o JavaScript
- Previsualiza los cambios con
zcli themes:preview - Confirma tu trabajo:
git commit -am "Actualizar el estilo del encabezado" - Sube a GitHub:
git push origin feature/actualizar-encabezado - Abre un pull request para la revisión del equipo
- Fusiona a main cuando sea aprobado
Importante: Nunca edites un tema gestionado por GitHub directamente en la interfaz de Zendesk. Si lo haces, Zendesk te advertirá que esto romperá la conexión de GitHub. Si accidentalmente haces cambios en Zendesk, tendrás que descargar el tema y confirmar esos cambios de nuevo en GitHub para restaurar la sincronización.
Actualizando el tema en Zendesk
Cuando tus cambios se fusionan con la rama principal y estás listo para implementar:
- En la administración de Knowledge, ve a Personalizar diseño
- Encuentra tu tema gestionado por GitHub
- Haz clic en el menú (tres puntos) y selecciona Actualizar desde GitHub
- Revisa los cambios en la vista previa
- Haz clic en Publicar cuando esté listo
Zendesk recupera la última versión de tu repositorio y la aplica a tu centro de ayuda. La actualización ocurre inmediatamente, así que considera usar un entorno de pruebas o una rama de prueba si necesitas validar los cambios antes de que se publiquen.
Consejos para la colaboración en equipo
Una vez que varias personas están trabajando en tu tema, algunas prácticas ayudan a mantener las cosas organizadas.
Estrategia de ramificación
Establece convenciones claras sobre cómo tu equipo usa las ramas:
- main Código listo para producción solamente. Nunca confirmes directamente a main.
- develop Rama de integración para pruebas. Fusiona las ramas de características aquí para las pruebas.
- feature/* Características individuales o correcciones de errores. Crea una nueva rama para cada tarea.
- hotfix/* Correcciones urgentes que necesitan evitar el flujo de trabajo normal.
En Zendesk, puedes tener múltiples temas importados desde el mismo repositorio usando diferentes ramas. Considera mantener un tema de "Pruebas" que rastree tu rama de desarrollo, permitiéndote previsualizar los cambios antes de que lleguen a producción.
Flujos de trabajo de revisión de código
Requiere pull requests para todos los cambios a main. Esto asegura:
- Al menos otra persona revisa el código
- Se pueden ejecutar comprobaciones automatizadas (linting, pruebas de accesibilidad)
- Hay un registro documentado de por qué se hicieron los cambios
Muchos equipos usan GitHub Actions para ejecutar automáticamente pruebas en pull requests, detectando problemas antes de que lleguen a Zendesk.
Gestionando múltiples temas
Si gestionas centros de ayuda para múltiples marcas o regiones, tienes opciones:
- Repositorios separados Aislamiento completo entre temas
- Mismo repositorio, diferentes ramas Código compartido con anulaciones específicas de la marca
- Tematización basada en la configuración Usa la configuración de manifest.json para alternar elementos de la marca
El enfoque de la rama funciona bien cuando los temas son similares pero necesitan colores, logotipos o contenido específicos de la marca.
Solución de problemas comunes
Errores de autenticación: Si Zendesk no puede acceder a tu repositorio, comprueba que el repositorio sea accesible para la cuenta que autorizaste. Los repositorios privados requieren los permisos adecuados.
Fallos de importación: Asegúrate de que manifest.json esté en la raíz de tu repositorio y contenga JSON válido. Los errores de sintaxis en este archivo impiden la importación.
Problemas de sincronización: Si Zendesk no refleja tus últimos cambios, verifica que subiste a la rama correcta y que estás actualizando desde la rama correcta en Zendesk.
Mejora tu centro de ayuda más allá de los temas
Un tema bien diseñado hace que tu centro de ayuda se vea profesional, pero el impacto real en la experiencia del cliente proviene de cómo gestionas las interacciones. Si bien los visitantes aprecian una interfaz limpia, lo que realmente quieren son respuestas rápidas y precisas a sus preguntas.
Aquí es donde las herramientas de soporte impulsadas por IA se vuelven valiosas. eesel AI se integra directamente con Zendesk para automatizar las respuestas, clasificar los tickets entrantes y proporcionar respuestas instantáneas desde tu base de conocimientos. En lugar de solo verse bien, tu centro de ayuda se vuelve genuinamente más útil.
La combinación funciona particularmente bien: tu tema personalizado gestionado por GitHub crea la experiencia visual, mientras que la IA gestiona la capa conversacional. Los clientes obtienen una experiencia de marca cohesiva, ya sea que estén navegando por artículos o chateando con tu agente de IA.
Si estás invirtiendo esfuerzo en personalizar la apariencia de tu centro de ayuda, considera también mejorar cómo gestionas las conversaciones que ocurren dentro de él. Nuestra guía para la automatización del soporte al cliente explica cómo la IA puede reducir los tiempos de respuesta y liberar a tu equipo para que se concentre en los problemas complejos que realmente necesitan atención humana.
Compartir esta entrada
Article by
