zendesk-guide-theme-import-from-github
eesel Team
Last edited 25 fevereiro 2026
{
"title": "Como importar um tema do Zendesk Guide do GitHub",
"slug": "zendesk-guide-theme-import-from-github",
"locale": "pt",
"date": "2026-02-25",
"updated": "2026-02-25",
"template": "default",
"excerpt": "Um guia prático para importar e gerenciar temas do Zendesk Guide diretamente do GitHub, incluindo configuração de desenvolvimento local e fluxos de trabalho em equipe.",
"categories": [
"Guides",
"Zendesk"
],
"tags": [
"Zendesk",
"GitHub",
"Help Center",
"Theme Development",
"ZCLI"
],
"readTime": 9,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Como importar um tema do Zendesk Guide do GitHub",
"description": "Um guia prático para importar e gerenciar temas do Zendesk Guide diretamente do GitHub, incluindo configuração de desenvolvimento local e fluxos de trabalho em equipe.",
"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": "Imagem do banner para Como importar um tema do Zendesk Guide do GitHub",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Perguntas Frequentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Posso usar a integração do GitHub com qualquer plano do Zendesk?",
"answer": "Não. A integração do GitHub para temas do Zendesk Guide requer pelo menos o Growth Suite com Guide Professional, ou qualquer Professional ou Enterprise Suite. Os planos Team e Guide Lite não incluem este recurso."
},
{
"question": "O que acontece se eu editar um tema gerenciado pelo GitHub diretamente no Zendesk?",
"answer": "O Zendesk avisará que fazer alterações na interface de administração quebrará a conexão com o GitHub. Se você prosseguir, o tema se tornará um tema personalizado regular e você precisará sincronizar manualmente as alterações de volta para o GitHub se quiser restaurar a integração."
},
{
"question": "Posso importar vários temas do mesmo repositório GitHub?",
"answer": "Não, cada repositório só pode conter um tema. No entanto, você pode usar diferentes branches dentro do mesmo repositório e importar cada branch como um tema separado no Zendesk. Isso é útil para gerenciar versões de staging e produção."
},
{
"question": "A integração do GitHub funciona com o GitHub Enterprise Server?",
"answer": "Não, a integração oferece suporte ao GitHub Enterprise Cloud, mas não ao GitHub Enterprise Server. Se você estiver usando o GitHub Enterprise Server, pode usar a API de Temas para criar sua própria integração."
},
{
"question": "Como atualizo meu tema após a importação inicial?",
"answer": "Na administração do Knowledge, encontre seu tema, clique no menu de três pontos e selecione 'Atualizar do GitHub'. O Zendesk busca o código mais recente do seu repositório. Você pode visualizar as alterações antes de publicá-las ao vivo."
},
{
"question": "Posso usar o ZCLI com um tema que baixei do Zendesk?",
"answer": "Sim. Qualquer tema do Zendesk Guide pode ser visualizado localmente com o ZCLI. Baixe o tema como um ZIP, extraia-o e execute 'zcli themes:preview' no diretório do tema."
}
],
"supportLink": null
}
}
Gerenciar um tema da central de ajuda diretamente na interface de administração do Zendesk funciona bem para pequenos ajustes. Mas, uma vez que você começa a fazer mudanças significativas ou a trabalhar com uma equipe, você rapidamente atingirá limitações. Não há controle de versão, nenhuma maneira de rastrear quem mudou o quê e nenhum método fácil de testar as alterações antes que elas entrem em vigor.
É aí que entra a integração com o GitHub. Ao conectar seu tema do Zendesk Guide a um repositório GitHub, você obtém todos os benefícios do controle de versão: branching para experimentos, pull requests para revisão de código e um histórico completo de cada alteração. Sua equipe pode colaborar no desenvolvimento do tema sem atrapalhar o trabalho uns dos outros, e você pode implantar atualizações com confiança.
Este guia orienta você através do processo completo de importação de um tema do Zendesk Guide do GitHub. Se você estiver começando com o tema oficial Copenhagen ou importando um tema personalizado existente, você aprenderá como configurar a integração, trabalhar localmente com o ZCLI e estabelecer um fluxo de trabalho que se adapta à sua equipe.
Enquanto você está melhorando a aparência da sua central de ajuda, considere como você lida com as interações com os clientes também. Ferramentas como eesel AI se integram diretamente com o Zendesk para automatizar respostas e triar tickets, complementando seu novo tema com automação inteligente.
Passo 1: Prepare seu tema no GitHub
A integração do GitHub tem requisitos específicos para como seu repositório deve ser estruturado. Fazer isso corretamente desde o início economiza dores de cabeça mais tarde.
Requisitos da estrutura do repositório
Seu repositório de temas deve atender a dois requisitos principais:
-
O arquivo manifest.json deve estar na raiz do repositório Este arquivo contém metadados do tema e definições de configurações. O Zendesk procura por ele no nível superior, não em subdiretórios.
-
Um tema por repositório Você não pode armazenar vários temas em um único repositório. Se você precisar de variações de um tema, use branches em vez disso.
A estrutura padrão do tema se parece com isto:
meu-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 do tema Copenhagen vs. criação do zero
Para a maioria das equipes, fazer um fork do tema oficial Copenhagen é o melhor ponto de partida. É o tema padrão do Zendesk, ativamente mantido e projetado para ser responsivo e acessível. Começar aqui significa que você receberá atualizações quando o Zendesk melhorar o tema base.
Para fazer um fork, visite o repositório do tema Copenhagen e clique no botão Fork. Isso cria sua própria cópia que você pode personalizar livremente.
Se você já tiver um tema existente no Zendesk, baixe-o da interface de administração do Knowledge e envie-o para um novo repositório GitHub.
Estratégia de branch para variações de tema
Como você só pode ter um tema por repositório, use branches para gerenciar variações:
mainoumasterSeu tema de produçãodevelopAmbiente de staging para testar alteraçõesfeature/novo-cabeçalhoTrabalho de recurso específicobrand/variante-aVariações de marca branca para diferentes marcas
Ao importar para o Zendesk, você pode especificar qual branch usar, facilitando a manutenção de várias variações de tema do mesmo repositório.
Passo 2: Configure seu ambiente de desenvolvimento local
Trabalhar localmente permite que você visualize as alterações instantaneamente sem fazer upload para o Zendesk cada vez. O ZCLI torna isso simples.
Instale o ZCLI
O ZCLI é a ferramenta de linha de comando moderna do Zendesk para desenvolvimento de temas. Instale-o globalmente via npm:
npm install -g @zendesk/zcli
Verifique a instalação:
zcli --version
Autentique com sua conta do Zendesk
Antes de poder visualizar os temas, o ZCLI precisa de acesso à sua conta do Zendesk. Execute o comando de login:
zcli login -i
Você será solicitado a informar:
- Subdomínio Seu subdomínio do Zendesk (a parte antes de
.zendesk.com) - E-mail Seu endereço de e-mail de administrador do Zendesk
- Senha Um token de API (recomendado) ou sua senha de conta
Para criar um token de API, vá para Admin Center > Apps e integrações > APIs > Zendesk API, então adicione um token na aba de Configurações.
Clone seu repositório de temas
Se você ainda não o fez, clone seu repositório de temas localmente:
git clone https://github.com/sua-org/seu-tema.git
cd seu-tema
Inicie a visualização local
Com o ZCLI autenticado e seu código de tema local, inicie o servidor de visualização:
zcli themes:preview
Este comando:
- Envia seu tema para um local temporário
- Inicia um servidor de desenvolvimento local
- Abre seu navegador padrão para visualizar o tema
- Observa as alterações de arquivo e recarrega automaticamente
A visualização usa seus dados reais da conta do Zendesk, então você verá artigos, categorias e tickets reais renderizados com seu tema. Faça uma alteração em um arquivo de modelo, salve-o e o navegador será atualizado automaticamente.
Passo 3: Conecte o Zendesk ao seu repositório GitHub
Com seu tema pronto no GitHub e o desenvolvimento local funcionando, é hora de estabelecer a conexão entre o Zendesk e seu repositório.
Navegue até a integração do GitHub
Na sua conta do Zendesk:
- Vá para Knowledge admin (a interface de gerenciamento da central de ajuda)
- Clique em Personalizar design na barra lateral
- Clique em Adicionar tema no canto superior direito
- Selecione Adicionar do GitHub
Autorize e importe
Você verá uma caixa de diálogo solicitando o URL do seu repositório. Insira o URL completo do GitHub:
https://github.com/sua-org/seu-tema
Opcionalmente, especifique um nome de branch se você quiser importar de algo diferente do branch padrão.
Clique em Importar. Se você não autorizou o Zendesk a acessar o GitHub antes, você será redirecionado para o GitHub para conceder permissões. Autorize o aplicativo Zendesk e retorne ao Zendesk.
O processo de importação busca seus arquivos de tema do GitHub e cria um novo tema em sua conta do Zendesk. Quando concluído, você verá a miniatura do tema na sua página de Temas.
Entendendo a conexão
Esta importação inicial estabelece uma conexão única entre seu tema do Zendesk e o repositório GitHub. Depois deste ponto, as alterações fluem em uma direção: do GitHub para o Zendesk. Você não pode editar um tema gerenciado pelo GitHub diretamente na interface do Zendesk sem quebrar a conexão.
Passo 4: Personalize e implante seu tema
Agora que a integração está ativa, você tem um fluxo de trabalho que combina o poder do controle de versão com a fácil implantação no Zendesk.
Fazendo alterações localmente
Sempre trabalhe no seu tema localmente, não na administração do Zendesk. Aqui está o fluxo de trabalho recomendado:
- Crie um branch para suas alterações:
git checkout -b feature/atualizar-cabeçalho - Faça edições em modelos, CSS ou JavaScript
- Visualize as alterações com
zcli themes:preview - Confirme seu trabalho:
git commit -am "Atualizar estilo do cabeçalho" - Envie para o GitHub:
git push origin feature/atualizar-cabeçalho - Abra um pull request para revisão da equipe
- Faça o merge para o main quando aprovado
Importante: Nunca edite um tema gerenciado pelo GitHub diretamente na interface do Zendesk. Se você fizer isso, o Zendesk avisará que isso quebrará a conexão com o GitHub. Se você acidentalmente fizer alterações no Zendesk, você precisará baixar o tema e confirmar essas alterações de volta para o GitHub para restaurar a sincronização.
Atualizando o tema no Zendesk
Quando suas alterações são mescladas ao branch principal e você está pronto para implantar:
- Na administração do Knowledge, vá para Personalizar design
- Encontre seu tema gerenciado pelo GitHub
- Clique no menu (três pontos) e selecione Atualizar do GitHub
- Revise as alterações na visualização
- Clique em Publicar quando estiver pronto
O Zendesk busca a versão mais recente do seu repositório e a aplica à sua central de ajuda. A atualização acontece imediatamente, então considere usar um ambiente de staging ou branch de teste se você precisar validar as alterações antes que elas entrem em vigor.
Dicas para colaboração em equipe
Uma vez que várias pessoas estão trabalhando no seu tema, algumas práticas ajudam a manter as coisas organizadas.
Estratégia de branching
Estabeleça convenções claras para como sua equipe usa branches:
- main Código pronto para produção apenas. Nunca faça commit diretamente para o main.
- develop Branch de integração para staging. Mescle branches de recursos aqui para teste.
- feature/* Recursos individuais ou correções de bugs. Crie um novo branch para cada tarefa.
- hotfix/* Correções urgentes que precisam ignorar o fluxo de trabalho normal.
No Zendesk, você pode ter vários temas importados do mesmo repositório usando branches diferentes. Considere manter um tema de "Staging" que rastreia seu branch de desenvolvimento, permitindo que você visualize as alterações antes que elas cheguem à produção.
Fluxos de trabalho de revisão de código
Exija pull requests para todas as alterações no main. Isso garante:
- Pelo menos uma outra pessoa revisa o código
- Verificações automatizadas podem ser executadas (linting, testes de acessibilidade)
- Há um registro documentado de por que as alterações foram feitas
Muitas equipes usam o GitHub Actions para executar automaticamente testes em pull requests, detectando problemas antes que eles cheguem ao Zendesk.
Gerenciando vários temas
Se você gerencia centrais de ajuda para várias marcas ou regiões, você tem opções:
- Repositórios separados Isolamento completo entre temas
- Mesmo repositório, branches diferentes Código compartilhado com substituições específicas da marca
- Temas baseados em configuração Use as configurações do manifest.json para alternar elementos da marca
A abordagem de branch funciona bem quando os temas são semelhantes, mas precisam de cores, logotipos ou conteúdo específicos da marca.
Solução de problemas comuns
Erros de autenticação: Se o Zendesk não conseguir acessar seu repositório, verifique se o repositório está acessível à conta que você autorizou. Repositórios privados exigem permissões adequadas.
Falhas de importação: Certifique-se de que manifest.json está na raiz do seu repositório e contém JSON válido. Erros de sintaxe neste arquivo impedem a importação.
Problemas de sincronização: Se o Zendesk não refletir suas alterações mais recentes, verifique se você enviou para o branch correto e se você está atualizando do branch correto no Zendesk.
Melhore sua central de ajuda além dos temas
Um tema bem projetado faz com que sua central de ajuda pareça profissional, mas o impacto real na experiência do cliente vem de como você lida com as interações. Embora os visitantes apreciem uma interface limpa, o que eles realmente querem são respostas rápidas e precisas para suas perguntas.
É aqui que as ferramentas de suporte alimentadas por IA se tornam valiosas. eesel AI se integra diretamente com o Zendesk para automatizar respostas, triar tickets recebidos e fornecer respostas instantâneas da sua base de conhecimento. Em vez de apenas ter uma boa aparência, sua central de ajuda se torna genuinamente mais útil.
A combinação funciona particularmente bem: seu tema personalizado gerenciado pelo GitHub cria a experiência visual, enquanto a IA lida com a camada conversacional. Os clientes obtêm uma experiência de marca, coesa, seja navegando em artigos ou conversando com seu agente de IA.
Se você está investindo esforço na personalização da aparência da sua central de ajuda, considere também melhorar como você lida com as conversas que acontecem dentro dela. Nosso guia para automação de suporte ao cliente explica como a IA pode reduzir os tempos de resposta e liberar sua equipe para se concentrar em questões complexas que realmente precisam de atenção humana.
Compartilhe esta postagem
Article by
