Integração com GitLab
Transforme gravações de tela em documentos Markdown no GitLab
Grave um fluxo de trabalho uma vez. O Clevera escreve o guia ilustrado e faz o commit no projeto e na pasta do GitLab que você escolher, como um arquivo Markdown com suas capturas de tela, para que seu pipeline de docs-as-code o processe como qualquer outra alteração.
Markdown do GitLab
Capturas de tela enviadas ao projeto
Funciona com GitLab Pages e MkDocs
Sem créditos para publicar
O que você pode fazer
Docs as code,
sem que ninguém precise escrever a documentação.
Equipes que utilizam o GitLab já tratam a documentação como código: ela reside em um projeto, possui histórico e é publicada por um pipeline. A parte difícil nunca foi o pipeline. Foi escrever os guias. O Clevera os escreve a partir de uma gravação de tela e os coloca na pasta que seu pipeline lê.
Um guia para cada passo a passo
Mostre o recurso uma vez na tela. O Clevera transforma a gravação em um guia escrito com etapas numeradas e capturas de tela, pronto para o manual do projeto ou para a documentação do produto.
Seu pipeline faz o resto
Cada publicação é um commit normal na branch padrão, então o GitLab Pages, MkDocs ou Hugo reconstrói o site exatamente como faria para a alteração de um colega de equipe.
Imagens que residem no projeto
As capturas de tela são enviadas junto com o arquivo Markdown e vinculadas por caminho relativo. Elas não dependem do Clevera, e um projeto privado as mantém privadas.
Atualizações como commits legíveis
Corrija o artigo no Clevera e publique novamente. O mesmo arquivo e suas imagens são sobrescritos em um commit de “Atualizar artigo”, para que o histórico mostre o que mudou e quando.
Qualquer projeto, qualquer pasta
Escolha entre todos os projetos do GitLab onde a conta conectada seja Desenvolvedor ou superior, e digite a pasta: docs, handbook/support ou a raiz do projeto.
Segue as regras da sua branch
O Clevera respeita branches protegidas. Se apenas Maintainers puderem fazer push para main, conecte uma conta de Maintainer ou permita que Desenvolvedores façam push.
Como funciona
Da gravação ao projeto no GitLab
em quatro etapas.
Um proprietário ou administrador conecta o GitLab uma vez. Depois disso, qualquer pessoa que possa editar um artigo pode publicá-lo a partir do editor.
- 1
Conectar GitLab.com
Entre no GitLab e autorize o Clevera. Ele lista os projetos onde sua conta é Desenvolvedor ou superior. - 2
O Clevera escreve o guia
A partir da gravação de tela, o Clevera escreve o artigo de ajuda: títulos, etapas numeradas, avisos e capturas de tela. - 3
Escolha o projeto e a pasta
Em Compartilhar, abra Publicar, escolha o projeto e a pasta do GitLab e clique em Publicar no GitLab. - 4
Um commit é realizado
O arquivo Markdown e suas imagens chegam juntos em um commit na branch padrão, e seu pipeline é executado.
Veja no Clevera
Publicando no GitLab,
a partir da janela Compartilhar do artigo.
Sem exportar, sem copiar Markdown manualmente, sem arrastar capturas de tela para um repositório. A janela Compartilhar que fornece um link e um código de incorporação também faz o commit no GitLab.
Escolha o projeto e a pasta
A lista mostra os projetos onde a conta do GitLab conectada é Desenvolvedor ou superior, com os atualizados mais recentemente primeiro. Digite a pasta onde sua documentação reside, como docs/guides; pastas que ainda não existem são criadas no mesmo commit.
O Clevera memoriza o projeto e a pasta, para que o próximo artigo vá para o mesmo lugar.
Republicar sem arquivos duplicados
Antes de escrever, o Clevera procura um arquivo com o mesmo nome nessa pasta. Se encontrar um, você escolhe: sobrescrevê-lo em um novo commit ou mantê-lo e publicar esta versão com um novo título.
A publicação é unidirecional. Uma edição feita por alguém no arquivo dentro do GitLab nunca retorna para o artigo no Clevera.
GitLab ao lado do restante da sua stack
Algumas equipes mantêm a documentação do produto no GitLab e a wiki interna em outro lugar. Conecte cada ferramenta uma vez e publique o mesmo artigo no GitLab, Confluence ou Notion a partir da mesma aba.
Preenchido para você
O que cada commit contém
e o que você decide.
O Clevera escreve Markdown que o GitLab renderiza na visualização de arquivos e que geradores de sites estáticos compilam perfeitamente. Aqui está exatamente o que uma publicação coloca no seu projeto.
- Projeto e pastaVocê escolhe
- Qualquer projeto do GitLab.com onde a conta conectada seja Desenvolvedor ou superior, e qualquer pasta nele. A pasta começa como
docs; deixe vazio para a raiz do projeto. - Nome do arquivoDefinido para você
- O título do artigo em letras minúsculas com hifens, terminando em
.md. “Reset a customer password” torna-sereset-a-customer-password.md. Títulos com acentos e caracteres não latinos são escritos em letras latinas, e nomes são cortados em 80 caracteres. - Front matterDefinido para você
- Um bloco YAML com
title,created_at,updated_atesource. MkDocs, Hugo e Docusaurus leem o título e ignoram o resto. - Avisos e formataçãoConvertido para você
- Avisos tornam-se alertas do GitLab com o título na mesma linha, como
> [!WARNING] Careful. Tabelas, listas de tarefas, matemática, código formatado com sua linguagem e seções colapsáveis<details>aparecem conforme o GitLab os renderiza. - Capturas de telaDefinido para você
- Enviadas para
assets/<file name>/na mesma pasta, no mesmo commit, com cada legenda em itálico abaixo da imagem. - CommitDefinido para você
- Um commit na branch padrão com a mensagem
Add article: …ouUpdate article: …, de autoria da conta do GitLab que conectou o Clevera. - VídeosDefinido para você
- Um vídeo colocado dentro do artigo torna-se uma imagem de capa que vincula ao seu player, além de um link ▶ com seu título. A gravação original do artigo não é adicionada.
Configuração
Configure a integração com o GitLab
em cerca de dois minutos.
Você precisa de um workspace Clevera no plano Pro ou Custom e uma conta no GitLab.com. O proprietário do workspace ou um Administrador conecta o GitLab; depois disso, qualquer pessoa que possa editar um artigo pode publicá-lo. A publicação não consome créditos.
- 1
Abrir Integrações
No Clevera, abra o menu do workspace, escolha Integrations, encontre o GitLab em Code repositories e clique em Connect. - 2
Autorizar o Clevera no GitLab.com
O GitLab solicita os escopos api, read_user, read_repository e write_repository , que sua API de arquivos precisa para criar e atualizar arquivos. Clique em Authorize. - 3
Verificar a função
Use uma conta que seja Desenvolvedor ou superior em cada projeto. Para fazer commit em uma branch padrão protegida, geralmente é necessário Maintainer; uma conta de bot compartilhada funciona bem. - 4
Publicar um artigo
No editor de artigos, clique em Share, abra Publish, clique no bloco do GitLab, escolha o projeto e a pasta e clique em Publish to GitLab. - 5
Abrir no GitLab
Quando você vir “Published to GitLab.”, clique em Open in GitLab para ver o arquivo e o commit.
Perguntas sobre a integração com GitLab
Não atualmente. O Clevera conecta-se apenas ao GitLab.com. Servidores GitLab self-managed não são suportados, portanto, um projeto em sua própria instância do GitLab não pode ser um destino de publicação.
Não. O Clevera faz commits diretamente na branch padrão do projeto, geralmente main, e você não pode escolher outra branch. Se sua equipe revisa documentação em merge requests, revise o artigo no Clevera antes de publicar, ou publique em um projeto onde commits diretos sejam permitidos.
Quase sempre é uma branch protegida. O GitLab protege a branch padrão e geralmente permite que apenas Maintainers façam push nela. Dê à conta conectada a função de Maintainer ou permita que Desenvolvedores façam push em Settings → Repository → Protected branches.
Sim. Aponte a pasta para aquela a partir da qual seu site é compilado. Cada publicação é um commit normal, então seu pipeline de CI/CD é executado como de costume, e o gerador lê title do front matter. Verifique se seu tema renderiza alertas e seções colapsáveis.
Nada muda no GitLab até que você publique novamente. Então, o Clevera encontra o arquivo existente e permite que você o atualize em um novo commit. Se você renomeou o artigo, o novo título se torna um novo arquivo; exclua o antigo no GitLab manualmente. O Clevera nunca exclui arquivos do seu projeto.
Um workspace comporta uma conexão com o GitLab, e conectar novamente a substitui. Use uma conta que seja membro de todos os projetos para os quais você publica.
Publicar no GitLab faz parte dos planos Pro e Custom, e a publicação não consome créditos. A criação do artigo em si consome créditos normalmente. Veja a precificação.
Sim. Conecte cada ferramenta uma vez e publique o mesmo artigo para quantas desejar. Veja as integrações com GitHub e Bitbucket ou todas as integrações.
Seu próximo guia, já no projeto.
Grave uma vez. O Clevera escreve o guia e faz o commit no GitLab, com capturas de tela e tudo mais.