GitHub

Connect a GitHub account to a workspace and edit the markdown that lives in your repositories directly from MDflow, committing changes straight back to the repo.

GitHub integration is available on every plan.

The mental model

This is the part to understand first, because it explains everything else.

GitHub files are not MDflow documents. They are read and written live through the GitHub API and are never copied into your workspace. The repository and its git history remain the single source of truth.

MDflow is acting as an editor for your repo — not as a place your repo now lives.

Connecting

Connect a GitHub account to any workspace from the workspace menu, and disconnect again at any time.

Connecting uses GitHub's OAuth sign-in and grants MDflow access to the repositories your account can reach.

The connection is per workspace. Different workspaces can connect to different accounts, or to none.

Browsing

A GitHub section appears in the sidebar for any workspace that has a connection.

• Browse your repositories, their branches, and their folders.
• Filter a long repository list by name.
• Pick any existing branch per repository.
• You see only markdown files (.md and .markdown) and the folders that contain them. Everything else is hidden.
• Folders and file trees load on demand as you expand them, so a huge monorepo does not have to be enumerated up front.

Editing and committing

Open any markdown file in the same editor used for MDflow documents, with the Edit, Split and Preview views. See 01 The Editor.

Save opens an inline commit bar with a prefilled, editable commit message. The change is written back as an ordinary git commit, attributed to your own GitHub account.

You can also create, rename and delete markdown files straight from the sidebar. Each is recorded as its own commit.

Returning to the GitHub section reopens the last file you had open in that workspace.

Conflicts

If the file changed on GitHub since you opened it, MDflow shows a conflict notice and never overwrites silently. You decide whether to reload the latest version from GitHub.

MDflow does not attempt a merge. It tells you, and lets you choose.

What GitHub files do not get

Because they are not MDflow documents, GitHub files sit outside:

• workspace search (see 04 Search),
• version history (see 06 Version History),
• sharing and comments,
• favorites,
• offline drafts.

Their history is the repository's own git history, which is the point. You do not want two competing histories for the same file.

Security

• The access token is encrypted at rest, stays on the server, and is never sent to the browser.
• It is revoked when you disconnect.
• MDflow only lists your repositories, branches and files, and writes the files you edit.

When to use it

Good for: editing a project's README, docs folder, or a markdown-based site, from a comfortable editor, without cloning anything.

Not for: using GitHub as your MDflow storage backend. If you want MDflow's search, sharing, history and agent access, the content needs to be MDflow documents.