Temas e CLI › Temas

O tema no GitHub

Um tema com o código da loja pode ficar ligado a uma branch de um repositório do GitHub. A cada push nessa branch, o código do tema passa a ser o do commit, e o verificador anota o commit e os pull requests para a branch, linha a linha, na aba Checks. Cada pull request ganha também uma prévia na loja, com o link num comentário. Quem manda no código é o GitHub: enquanto o tema está conectado, o código não muda pelo painel nem pela API, e o histórico fica no Git.

O conteúdo que o lojista monta no editor visual (as seções, os textos, as imagens, os ajustes) continua na loja, livre, e nunca vira commit. O push da agência troca só o código.

O App da Denaryx

A ligação é feita pelo App da Denaryx no GitHub, instalado na conta onde fica o repositório (a sua ou a da organização da agência). Ele pede o mínimo:

Conteúdo, só leitura: para baixar o código do commit.
Pull requests, leitura e escrita: para saber a branch de base de cada pull request e escrever nele o comentário com o link da prévia.
Verificações, leitura e escrita: para a verificação "Denaryx · Tema" com as anotações.

O App nunca grava no código do repositório: nem commit, nem branch. O único texto que ele escreve é o comentário da prévia em cada pull request, que ele mesmo atualiza e apaga. Na instalação, você escolhe quais repositórios ele alcança, e pode mudar isso depois, nas configurações da instalação no GitHub.

Se o App pedir uma permissão nova, o GitHub mostra o pedido nas configurações da instalação, e quem a administra decide. Enquanto a escrita em pull requests não for aceita, a prévia de cada pull request existe na loja, mas o comentário com o link não aparece.

Ligar um tema

O tema precisa ter o código da loja: uma cópia de um tema da plataforma ("Copiar o código", na página Temas) ou um tema enviado pela agência. O tema de desenvolvimento do CLI não se conecta.
Na página Temas, no tema, clique em GitHub e depois em Instalar o App no GitHub. No GitHub, escolha a conta e os repositórios e confirme. Se o App já está instalado na conta (a agência que atende várias lojas instala uma vez só), clique em O App já está na minha conta.
De volta ao painel, escolha a conta, o repositório, a branch e a pasta do tema no repositório, e clique em Conectar o tema.

A volta do GitHub só liga à loja uma instalação que aparece na conta de quem voltou: a plataforma confere com o próprio GitHub, pela autorização dessa pessoa, que é jogada fora em seguida. Um endereço de volta forjado não liga a loja ao repositório de outra pessoa.

Quem liga precisa ter o código dos temas na loja (dono, gerente ou Catálogo e vitrine).

A pasta do tema

O repositório pode ter mais coisas além do tema: o README, o package.json, o código-fonte de quem usa Sass, TypeScript ou Tailwind. A plataforma lê só as oito pastas do tema (layout, templates, sections, blocks, snippets, assets, config e locales) dentro da pasta escolhida na conexão; vazia, é a raiz do repositório. O resto do repositório não sai do GitHub.

Quem gera o tema num build aponta a pasta de saída e faz o commit dela: a plataforma lê o que está no commit, e não roda o build.

A cada push

O GitHub avisa a plataforma do push. A plataforma lê a ponta da branch naquele momento (e não o commit do aviso): vários pushes seguidos acabam no último, e a ordem dos avisos não importa.
O código do commit vira o código do tema. Mudou alguma coisa, nasce uma versão do código com a nota abc1234: primeira linha da mensagem do commit (na API Admin, a versão tem reason: import). O código igual ao que o tema já tem não muda nada.
A verificação Denaryx · Tema aparece no commit: os erros como failure e os avisos como warning, cada um na linha do arquivo (os 200 primeiros, os erros antes), e o resumo com as contagens, o que o código novo tira do conteúdo montado no editor visual e o link do tema no painel. Com erro, a verificação falha, e o tema não pode ser publicado.

As regras são as do verificador de temas, as mesmas do denaryx tema check e do "Antes de publicar". Um Re-run na aba Checks refaz a sincronização e a verificação.

Os pull requests

Num pull request cuja base é a branch conectada, a plataforma verifica a ponta do pull request a cada push nele e anota as linhas, na mesma verificação. O tema conectado não muda: só o merge na branch conectada muda o código dele.

A prévia por pull request

Cada pull request aberto para a branch conectada, a partir de uma branch do mesmo repositório, ganha a sua prévia: um tema de desenvolvimento com o código do pull request e o conteúdo do tema conectado, para ver a mudança na loja de verdade antes do merge.

O comentário fixo: o App escreve no pull request um comentário com o link da prévia, o commit, o nome do tema e o resumo da verificação. A cada push no pull request, o código do tema muda e o mesmo comentário é atualizado; o link continua o mesmo, e a página aberta se atualiza sozinha.
O link acompanha o trabalho e vale por 30 dias; depois disso, o push seguinte cria outro. Ele aparece em Temas › Links de prévia no painel, com o nome "Pull request #12", e conta no limite de 20 links ativos da loja. Quem lê o pull request abre a prévia: num repositório público, isso é qualquer pessoa.
O tema fica em Temas › Em desenvolvimento, com o link do pull request. Ele não vai ao ar, o código dele muda só pelo push no pull request (o painel e a API respondem 409 theme_connected), e o editor visual funciona nele como em qualquer tema de desenvolvimento.
Ao fechar o pull request (com ou sem merge), ou quando a base dele deixa de ser a branch conectada, o tema, o link e o comentário saem. Reabrir o pull request cria outra prévia.
Sete dias sem push no pull request, o tema vence e sai, como todo tema de desenvolvimento; o push seguinte cria outro.
No painel, a página do GitHub do tema lista os pull requests com prévia: o número, o último commit e o tema de cada um, ou por que ele ficou sem prévia.
Desconectar o tema (ou excluí-lo) tira as prévias dos pull requests dele e apaga os comentários.

O pull request de um fork é verificado, mas não ganha prévia: o código de qualquer pessoa não vai para a loja. Para ver a mudança de um fork, traga a branch para o repositório.

Quando o pull request fica sem prévia, o comentário diz o porquê: o limite de prévias, o código que não entrou no tema (a pasta sem os arquivos do tema, o zip grande demais) ou o limite de links da loja.

O código só para leitura

Enquanto o tema está conectado:

o editor de arquivos do painel abre o código só para leitura, com o aviso e o link do repositório;
a API Admin responde 409 theme_connected à gravação de arquivos, ao envio de assets, à troca pelo zip e à restauração de uma versão;
o editor visual continua como sempre, e a publicação também;
o denaryx tema dev continua valendo: ele trabalha no tema de desenvolvimento de cada pessoa. O caminho para o tema conectado é o git push;
na API Admin, o tema traz a conexão no campo github (o repositório, a branch, a pasta, a situação e o último commit), e o tema da prévia de um pull request traz o pull_request (ver Temas).

Desconectar (na página do GitHub do tema) devolve a edição pelo painel e pela API; o tema fica com o código do último push.

Publicar sozinho

Desligado por padrão. Quem publica tema com código próprio na loja pode ligar, na página do GitHub do tema:

Não (o padrão): o push muda o tema em trabalho, e a publicação é pelo painel, com o "Antes de publicar".
Só sem impacto: publica quando o push não tem erro e não muda o conteúdo montado no editor visual.
Sempre: publica quando o push não tem erro.

A publicação sai em nome de quem a ligou, e só enquanto essa pessoa ainda puder publicar tema com código próprio na loja (conferido a cada push). A nota da publicação é o commit, e a vitrine mostra a mudança em até 60 segundos. Quando o push não é publicado, o motivo aparece no painel e no resumo da verificação.

Quando a sincronização para

A conexão fica pausada, com o motivo no painel, quando o App perde o acesso: o App foi desinstalado ou suspenso na conta, o repositório saiu da instalação, ou a branch foi apagada ou renomeada. Devolvido o acesso, Sincronizar agora retoma (o repositório que volta à instalação retoma sozinho).

Se o GitHub não responde, o painel mostra o último erro, e a plataforma tenta de novo algumas vezes, em alguns minutos.

Limites

O código do tema no commit: até 50 MB e 2.000 arquivos, as mesmas regras do envio do zip.
Um tema, uma conexão. O mesmo repositório e a mesma branch podem servir a temas de lojas diferentes (a homologação e a loja do cliente, por exemplo).
Até 10 pull requests com prévia ao mesmo tempo em cada conexão, dentro dos 30 temas de desenvolvimento da loja. As prévias não contam nos 5 temas de desenvolvimento de cada pessoa.
Sem o App: o mesmo resultado sai do CI, com o CLI e um token de integração (ver o CLI no CI e no GitHub). É o caminho para o GitLab, o Bitbucket e quem não quer instalar o App.