Docs from Git

Keeping a knowledge base space in step with a folder of Markdown in a GitHub or GitLab repository, so documentation written beside the code is read, searched and linked here.

Documentation that lives in a repository beside the code (a docs/ folder, an MkDocs or Docusaurus site, a wiki of Markdown files) can be a space of the knowledge base without being copied by hand. The space reads the folder through the host's API, turns its files into pages the way a documentation import does, and brings every push across for as long as it is connected. It is an integration like GitHub and GitLab linking commits to tickets, not an import: nothing is uploaded, and the repository stays where the pages are written. Here they are read, searched, linked from tickets and published to customers.

What you need

• A space with no pages of its own, which the repository's files will fill: a new workspace space, or a project's space nobody has written in yet.
• The repository on GitHub, GitHub Enterprise, GitLab.com or a GitLab of your own, and the branch and folder to read.
• For a private repository, an access token that can read it, made on the host as the next section says. A public repository needs no token.

Making an access token

The token is made on GitHub or GitLab, by an account that can read the repository, and pasted into the form once. It needs to read the repository's contents and nothing else.

GitHub. Open your profile menu, Settings, then Developer settings at the bottom of the left-hand list, Personal access tokens, Fine-grained tokens, Generate new token. Give it a name and an expiry, choose the repository's owner as the Resource owner (an organisation may have to approve the token, or may allow fine-grained tokens only after an administrator turns them on), and under Repository access pick Only select repositories and the repository. Under Permissions, Repository permissions, set Contents to Read-only; the Metadata permission it adds by itself is all it needs besides. Generate the token and copy it: GitHub shows it once. A classic token (Tokens (classic) on the same page) with the repo scope works too, but reads every repository the account can, so prefer a fine-grained one. On GitHub Enterprise the same pages are under your profile's Settings there.

GitLab. In the project, Settings, Access tokens, Add new token. Give it a name and an expiry, the Reporter role (the lowest that can read a private project's files) and the read_repository scope, then create it and copy it: GitLab shows it once. A personal access token (your avatar, Edit profile, Access tokens) with read_repository or read_api works too, for every project you can read. A group access token, made the same way under the group's settings, covers every project in the group.

The token is kept encrypted with the space, sent to the host you name and nowhere else, never shown again and never included in a workspace export. When it expires, the sync fails and the settings say so; make a new one and paste it into the form, which keeps everything else.

Connecting the space

In the space, Settings, Git repository. An installation administrator can connect any space, and a project's administrator the project's space. Fill in:

• Host: GitHub or GitLab, and for GitHub Enterprise or a GitLab of your own its Address (https://git.example.com).
• Repository: owner/name, or a GitLab project's full path (group/subgroup/name).
• Branch: main unless you give another.
• Folder: docs unless you give another; empty reads the whole repository.
• Access token.

Connect reads the folder at once. The settings then show the commit last read and when; if a sync fails, they say why (a token the host refused, a branch that does not exist, a repository too large to read without a folder).

Connecting an account of your own cannot be tried in the public demo workspace, whose logins are everybody's: see In the demo.

Keeping it in step

Three things bring changes across, and each writes only what changed:

• A push. Add the repository's webhook to the workspace's GitHub or GitLab integration, as GitHub and GitLab describes (the same webhook links commits to tickets). Each push to the space's branch that touches its folder queues a sync, which is done within moments.
• Every night, each space is checked against its branch, in case a delivery was missed. A branch that has not moved costs one request.
• Sync now, in the space's settings, reads the folder again whenever you ask.

A file that changed becomes a new version of its page, a new file a new page, and the page of a file that went is deleted here (those who manage the space still see it in the trash). Images and other files that did not change are not downloaded again.

How files become pages

As in a documentation import:

• the tree comes from the folders or from the tool's own navigation found in the folder (SUMMARY.md, mkdocs.yml, Docusaurus sidebars), in its order;
• titles come from the front matter, the first heading or the file name;
• Markdown is kept as it was written, front matter aside;
• links between files and to images point at the pages and files here, and a link out of the folder, or to a file that is not a page (a script, a configuration file), goes to the file on the host;
• code and configuration files are not read, and neither is any file over 25 MB.

What a git page can and cannot do

A page of a git space is its file's. It shows the file's path and the commit it was read at, and Edit on GitHub (or GitLab) opens the file in the host's editor. Here it cannot be edited, retitled, moved, deleted or restored, nor can pages be added to the space; the API refuses such a change with 422 git_space. It can be read, searched, linked from tickets and other pages, commented on, labelled and published to customers like any other page, and its history lists each version the repository gave it.

Disconnecting

Disconnect in the space's settings stops the syncs and forgets the token. The pages stay, as ordinary pages that anyone who may write in the space can change from then on.