Publish articles to GitLab

Connect GitLab once and you can publish any Clevera article to a GitLab project as a Markdown file, ready for a docs site, a docs/ folder or a project handbook. This article covers connecting, choosing the project and folder, what the file looks like and how updates work.

Before you start#

• Plan: publishing to GitLab is part of the Pro and Custom plans. On Free and Starter the Publish tab shows "Publishing to your tools is included in Pro". See Choose a plan.
• Role in Clevera: only the workspace owner or an Administrator can connect or disconnect GitLab. Everyone else who can open the article can publish once it's connected.
• GitLab.com only: Clevera connects to GitLab.com. Self-managed GitLab servers aren't supported.
• Role in GitLab: Clevera lists projects where the connecting account has the Developer role or higher. To commit to a protected default branch, that account usually needs Maintainer (see Protected branches).
• An article: you publish the article that belongs to a video or recording. Generate it first; see Turn a recording into an article.

Publishing uses no credits.

Connect GitLab#

1. Open Integrations#

   In the sidebar, open the workspace menu and choose Integrations. Find GitLab under Available integrations (or the Development tab) and click Connect.

2. Sign in to GitLab and authorize#

   Sign in to GitLab.com if you aren't already. GitLab asks you to authorize Clevera with these scopes:

   GitLab scope	Why
   api	GitLab's file API needs it to create and update files
   read_user	To show your GitLab username in Clevera
   read_repository	To check whether a file already exists
   write_repository	To commit the Markdown file

   Click Authorize.

3. Check the connection#

   You return to Integrations with "GitLab connected successfully to" followed by your GitLab username. GitLab moves to the Connected list with a Connected badge. Before you publish anything it reads "Nothing published yet".

Publish an article#

1. Open the Publish tab#

   In the editor, click Share and open the Publish tab. Under Publish the article, GitLab shows Connected and a Publish button.

   The article is published in the language you have open in the editor. Switch language in the top bar first to publish a translation.

2. Choose the project and folder#

   Click Publish next to GitLab, then choose where the article goes:

   Field	What to pick	Notes
   Repository	The GitLab project for the file	Lists up to 100 projects where you're Developer or higher, most recently updated first. The first one is selected for you
   Folder	A path such as docs or articles/guides	Starts as docs. Leave it empty for the project root. Folders that don't exist yet are created

   

3. Publish#

   Click Publish. You see "Checking for an existing article…", then "Publishing…". When it's done you see "Published to GitLab." and the file opens in GitLab in a new tab.

Where the file goes#

• Branch: the project's default branch (usually main). Clevera commits straight to it; it doesn't open a merge request and you can't pick another branch.
• File name: the title in lowercase, with spaces turned into hyphens, ending in .md. "Create your first invoice" becomes create-your-first-invoice.md.
• Commit message: Add article: <title>, or Update article: <title> when you replace an existing file.
• Commit author: the GitLab account that connected the integration.

Protected branches#

GitLab protects the default branch by default, and usually only Maintainers can push to it. If the connected account is a Developer, the commit is refused with "Failed to create file in GitLab." Either give that account the Maintainer role, or allow Developers to push under Settings → Repository → Protected branches in the project.

What the file looks like#

Clevera writes GitHub-flavored Markdown, which GitLab renders, with a short front matter block at the top:

---
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"
---

If the video's share link is on, the file starts with a quoted line, Watch the video tutorial, that links to the video player. Markdown files can't hold a player, so it's a link. If the share link is off, there's no video line, and turning the link off later makes an existing one stop working.

Images#

Screenshots aren't copied into your project. Each image links to the file on Clevera's servers through a signed address that works for one year from when you publish. To keep images working, publish the article again (choose Replace the existing article) within the year; each publish renews the links.

Anyone who has the image address can open the image, even if the project is private.

Use it with a docs site#

If GitLab Pages or another static-site generator (such as MkDocs, Docusaurus or Hugo) builds your docs from the project, point Folder at the folder it reads. Each publish is a normal commit, so your pipeline runs as usual. Most generators read title from the front matter and ignore fields they don't know.

Update an article you already published#

Publishing only goes one way. Edits you make in Clevera stay in Clevera until you publish again, and changes made to the file in GitLab never come back to Clevera.

When you publish to the same project and folder, Clevera finds the file with the same name and asks what to do: "An article with this title already exists in GitLab." Click View it to open the existing file, then choose:

If the title changed in Clevera, the file name changes too, so publishing creates a new file next to the old one. Delete or rename the old file in GitLab yourself. Nothing in Clevera deletes files from your project.

Disconnect GitLab#

1. Open Integrations, click the ⋯ menu on the GitLab row and choose Disconnect (or click GitLab and then Disconnect).
2. Confirm. "You can no longer publish to it from the editor. Content you already published stays in GitLab."

Disconnecting deletes Clevera's tokens. To revoke Clevera's access on GitLab too, open your GitLab avatar menu → Edit profile → Applications, find Clevera under Authorized applications and click Revoke.

Troubleshooting#

Related#