---
title: "01 GitHub"
canonical_url: https://mdflow.cz/share/c/h0L7MvX5Cy5sST3qPnApqHOmrQ36JTVy169qJMtDMya9Kc30zm04cg9OuPSSPwvj/62a51527-90fe-45db-b5bb-1f25afa74d89
md_url: https://mdflow.cz/share/c/h0L7MvX5Cy5sST3qPnApqHOmrQ36JTVy169qJMtDMya9Kc30zm04cg9OuPSSPwvj/62a51527-90fe-45db-b5bb-1f25afa74d89.md
visibility: public
---

# 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](/doc/3e67a2af-7882-4ac3-8530-993fe21bf253).

**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](/doc/43588057-54ed-4d26-84b2-d1a625c5e7ff)),
- version history (see [06 Version History](/doc/9c6737c5-cb49-4eb8-83c8-d9a72e36fa3c)),
- 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.