Publicar artigos no GitLab

Conecte o GitLab uma vez e você poderá publicar qualquer artigo do Clevera em um projeto do GitLab como um arquivo Markdown, pronto para um site de documentação, uma pasta docs/ ou um manual de projeto. Este artigo aborda a conexão, a escolha do projeto e da pasta, a aparência do arquivo e como as atualizações funcionam.

Antes de começar#

• Plano: a publicação no GitLab faz parte dos planos Pro e Custom. Nos planos Free e Starter, a aba Publicar exibe "A publicação em suas ferramentas está incluída no plano Pro". Veja Escolher um plano.
• Função no Clevera: apenas o proprietário do workspace ou um Administrador pode conectar ou desconectar o GitLab. Uma vez conectado, qualquer pessoa que possa editar um artigo pode publicá-lo.
• Apenas GitLab.com: o Clevera conecta-se ao GitLab.com. Servidores GitLab autogerenciados não são suportados.
• Função no GitLab: o Clevera lista projetos onde a conta conectada possui a função de Desenvolvedor ou superior. Para fazer commit em uma branch padrão protegida, essa conta geralmente precisa ser Mantenedora (veja Branches protegidas).
• Um artigo: você publica o artigo que pertence a um vídeo ou gravação. Gere-o primeiro; veja Transformar uma gravação em um artigo.

A publicação não utiliza créditos.

Conectar o GitLab#

1. Abrir Integrações#

   Na barra lateral, abra o menu do workspace e escolha Integrações. Encontre o GitLab em Integrações disponíveis (ou na aba Desenvolvimento) e clique em Conectar.

2. Entrar no GitLab e autorizar#

   Entre no GitLab.com se você ainda não estiver conectado. O GitLab solicitará que você autorize o Clevera com estes escopos:

   Escopo do GitLab	Por que
   api	A API de arquivos do GitLab precisa disso para criar e atualizar arquivos
   read_user	Para exibir seu nome de usuário do GitLab no Clevera
   read_repository	Para verificar se um arquivo já existe
   write_repository	Para fazer commit do arquivo Markdown e suas imagens

   Clique em Autorizar.

3. Verificar a conexão#

   Você retornará para Integrações com a mensagem "GitLab conectado com sucesso a" seguida pelo seu nome de usuário do GitLab. O GitLab será movido para a lista Conectado com um selo Conectado. Antes de publicar qualquer coisa, a mensagem será "Nada publicado ainda".

Publicar um artigo#

1. Abrir a aba Publicar#

   No editor, clique em Compartilhar e abra a aba Publicar. Em Publicar o artigo, clique no bloco do GitLab em Pronto para publicar.

   O artigo é publicado no idioma que você tem aberto no editor. Alterne o idioma na barra superior primeiro para publicar uma tradução.

2. Escolher o projeto e a pasta#

   Em Onde será publicado, escolha:

   Campo	O que escolher	Notas
   Repositório	O projeto do GitLab para o arquivo	Projetos onde você é Desenvolvedor ou superior, exibidos do mais recentemente atualizado para o mais antigo. O primeiro é selecionado para você
   Pasta	Um caminho como docs ou articles/guides	"O arquivo Markdown é criado aqui. Deixe vazio para a raiz do repositório." Começa como docs. Pastas que ainda não existem são criadas

   O Clevera lembra o que você escolheu para a próxima vez.

   

3. Publicar#

   Clique em Publicar no GitLab. Você verá "Procurando por uma cópia existente no GitLab", depois Escrevendo a página. Quando terminar, você verá "Publicado no GitLab." Clique em Abrir no GitLab para ver o arquivo.

   Você pode fechar a janela Compartilhar enquanto o processo ocorre; uma notificação avisará quando estiver concluído.

Onde o arquivo vai parar#

• Branch: a branch padrão do projeto (geralmente main). O Clevera faz o commit diretamente nela; ele não abre um merge request e você não pode escolher outra branch.
• Nome do arquivo: o título em letras minúsculas, com espaços transformados em hifens, terminando em .md. "Create your first invoice" torna-se create-your-first-invoice.md. Títulos em outros scripts ou com acentos são escritos primeiro em letras latinas ("Créer une facture" torna-se creer-une-facture.md). Um título sem nada para ser escrito, como um feito apenas de emojis, recebe um código fixo curto (article- mais 8 caracteres). Nomes são cortados em 80 caracteres.
• Imagens: as capturas de tela do artigo vão para assets/<file name>/ dentro da mesma pasta, no mesmo commit.
• Mensagem de commit: Add article: <title>, ou Update article: <title> quando você atualiza um arquivo existente.
• Autor do commit: a conta do GitLab que conectou a integração.

Branches protegidas#

O GitLab protege a branch padrão por padrão, e geralmente apenas Mantenedores podem fazer push nela. Se a conta conectada for um Desenvolvedor, o commit é recusado com "GitLab recusou o commit: você precisa de acesso de Desenvolvedor ou superior, e a branch não deve estar protegida." Dê a essa conta a função de Mantenedor ou permita que Desenvolvedores façam push em Configurações → Repositório → Branches protegidas no projeto.

Como é o arquivo#

O Clevera escreve Markdown que o GitLab renderiza, com um pequeno bloco de front matter no topo:

---
title: "Create your first invoice"
created_at: "2026-10-12T09:30:00+00:00"
updated_at: "2026-10-12T10:05:00+00:00"
source: "Clevera"
---

O vídeo do qual o artigo se originou não é adicionado ao arquivo. Um vídeo do Clevera colocado dentro do artigo torna-se um link para seu player, apenas quando o link de compartilhamento desse vídeo estiver ativado. Veja Exibir um vídeo em um artigo.

Imagens#

As capturas de tela são commitadas no seu projeto ao lado do arquivo, e o Markdown faz link para elas por caminho relativo (assets/<file name>/…). Elas continuam funcionando sem o Clevera e, em um projeto privado, permanecem tão privadas quanto o restante dele.

Um arquivo de vídeo que você carregou no artigo não é commitado. Ele permanece como um link para o Clevera que expira após algum tempo; publique novamente para renová-lo.

Usar com um site de documentação#

Se o GitLab Pages ou outro gerador de site estático (como MkDocs, Docusaurus ou Hugo) constrói sua documentação a partir do projeto, aponte a Pasta para a pasta que ele lê. Cada publicação é um commit normal, então seu pipeline roda como de costume. A maioria dos geradores lê title do front matter e ignora campos que não conhece.

Atualizar um artigo que você já publicou#

A publicação funciona apenas em uma direção. Edições que você faz no Clevera permanecem no Clevera até que você publique novamente, e alterações feitas no arquivo no GitLab nunca retornam ao Clevera.

Ao publicar no mesmo projeto e pasta, o Clevera encontra o arquivo com o mesmo nome e exibe "Este artigo já está no GitLab." Clique em Visualizar para abrir o arquivo existente, então escolha:

Se o título mudou no Clevera, o nome do arquivo também muda, então a publicação cria um novo arquivo ao lado do antigo. Exclua ou renomeie o arquivo antigo no GitLab você mesmo. Nada no Clevera exclui arquivos do seu projeto.

Desconectar o GitLab#

1. Abra Integrações, clique no menu ⋯ na linha do GitLab e escolha Desconectar (ou clique em GitLab e depois em Desconectar).
2. Confirme. "Você não pode mais publicar nele a partir do editor. O conteúdo que você já publicou permanece no GitLab."

Desconectar exclui os tokens do Clevera. Para revogar o acesso do Clevera no GitLab também, abra o menu do seu avatar no GitLab → Editar perfil → Aplicações, encontre o Clevera em Aplicações autorizadas e clique em Revogar.

Solução de problemas#

Relacionado#