> ## Documentation Index > Fetch the complete documentation index at: https://docs.nekt.com/llms.txt > Use this file to discover all available pages before exploring further. # Context Layer on GitHub > Keep your context documents in a GitHub repository, reviewed through pull requests and synced in both directions. You can connect the Context Layer, or one of its folders, to a GitHub repository. Each context document becomes a Markdown file in the repository, and Nekt keeps both sides in sync: changes made on GitHub reach Nekt, and changes made in Nekt reach GitHub, through a pull request or a direct commit depending on how your workspace writes to GitHub. > [!NOTE] > > Available on the **Starter, Growth, and Custom** plans. It requires the [organization's GitHub connection](https://docs.nekt.com/organizations/github.md), and the repository must be one the workspace may use. > [!WARNING] > > Everyone with access to the repository reads every document of the connected part of the Context Layer, regardless of the permissions set in Nekt. ## Connect the Context Layer or a folder * **The whole Context Layer**: click **Connect to GitHub** at the top of **Context Layer**. Workspace admins can do it. * **One folder**: click **Connect to GitHub** in the folder. Workspace admins can do it and, on Growth and Custom, so can a Manager of the folder who can see every document inside it. **1. Choose the repository and branch** Pick one of the repositories your workspace may use. **Branch** is optional: without it, Nekt uses the repository's default branch. **2. Choose the folder in the repository** **Folder in the repository** is optional. For the whole Context Layer the default is `context-layer`; for a folder, the default is the directory that folder would have if the whole Context Layer were connected, so you can switch between the two without moving files. **3. Confirm** Check **I understand that whoever reads the repository sees these documents** and click **Connect**. Connecting merges both sides: Markdown files already in that folder of the repository become documents in Nekt, and documents that exist only in Nekt are sent to the repository. In a workspace that writes through pull requests, that export is a pull request. Two connections cannot use overlapping folders of the same repository and branch, even from different workspaces. Use a different folder or branch for each one. ## How documents are stored Folders of the Context Layer are directories, and each document is a `.md` file named after it, starting with a short header (front matter) that holds its Nekt id and its name: ```markdown theme={null} --- nekt_id: 7d1c3a52-1f0e-4b7a-9c2d-0a6b1e4f8c31 name: Net revenue --- Net revenue is gross revenue minus refunds and chargebacks... ``` * The `name` in the header is the document's name; the file name does not matter. * Other keys you add to the header are kept when Nekt rewrites the file. * A `.md` file created on GitHub without a header becomes a new document named after the file. Nekt then writes the header into the file. * A `README.md` directly in the connected folder, and files that are not `.md`, are ignored. * Deleting a file on GitHub deletes the document in Nekt. A new directory on GitHub becomes a folder in Nekt; folders are never deleted by the sync, and folder settings such as description and icon stay in Nekt only. ## Editing By default, the connected part of the Context Layer can be edited both in Nekt and on GitHub. ### When your workspace writes through pull requests Every change to a document made in Nekt, by a person or by an agent, becomes a **proposal** in a pull request on a branch Nekt creates: * The document shows **Proposal in PR #N** with the pull request's status, and **View diff** compares the proposal with the published version. * Agents and search keep reading the published version until the pull request is merged. A document whose creation is proposed shows in the tree as **Proposed** and is not visible to agents yet. * Nekt merges the pull request as soon as the checks pass and the branch rules allow, then publishes the change and deletes its branch. * Creating, renaming, moving, and deleting folders apply right away; the new paths of their documents ride the open pull request. From the connection (click its status at the top of the page) or from the document, you can **discard** the proposals, which closes the pull request and keeps the published version. If the pull request conflicts with the branch and GitHub cannot update it, you can **rebuild** the proposals on top of the current branch. A pull request closed on GitHub without a merge can be reopened from Nekt. ### When your workspace commits directly A change made in Nekt is published right away and committed to the branch. If the same document was also changed on GitHub since the last sync, GitHub's version wins: the document shows **Your version was replaced by GitHub**, and your edit stays in the history, where you can view or restore it. ### Edit only on GitHub Turn on **Edit only on GitHub** in the connection to make the connected part read-only in Nekt, for people and for agents through the MCP. Every change then comes through a pull request on GitHub, and the pages show **Managed by GitHub**. ## Connection status The status at the top of the Context Layer, or of a connected folder, shows where the connection stands. Click it to see the repository, branch, folder, the **Edit only on GitHub** toggle, the last sync, and the open pull request. | Status | Meaning | | :- | :- | | In sync | Nekt and GitHub have the same documents. | | Proposal in PR #N | A pull request is waiting: for checks, for a review, or with failed checks. | | Conflict | The pull request conflicts with the branch. Rebuild or discard the proposals. | | Differs from GitHub | The repository differs from Nekt and no pull request is open, for example after the export pull request was closed without a merge. Click **Sync now** to send it again. | | Error | Nekt could not sync. The connection explains why and what to do. | **Sync now** reads the branch again and sends what GitHub is missing. **Disconnect** removes the connection: open proposals are archived and their pull request is closed, and the files stay in the repository. ### Errors and what to do | Error | What to do | | :- | :- | | The branch's protection refused a direct commit | The branch accepts changes only through pull requests or with status checks. Switch how Nekt writes to pull requests in the workspace's **Settings → GitHub**, or relax the branch protection on GitHub. | | The GitHub App needs the new pull request permission | An owner of the GitHub account must accept the App's new permissions on GitHub. | | The repository was removed from the GitHub App installation | Add it back to the installation on GitHub to resume. | | This workspace may no longer use the repository | Ask an organization Owner or Admin to allow it again for the workspace. | | Whoever connected it can no longer manage this folder | Reconnect with someone who can. | | Some files of the repository could not be applied | Fix the listed files (usually an invalid header) and push again. | | Your plan does not include GitHub | Upgrade to Starter or above to sync again; nothing was deleted. | ## Document history Every document keeps its history, on every plan, with or without GitHub. Open it from the document's menu with **History**: * Each change shows what happened (created, edited, moved, deleted), when, and who made it. A change made by an agent shows the person and the MCP token it used, for example *Ana via the MCP token Analytics agent*. * A change that went through a pull request links to it. While a pull request is open, its proposal is listed with its status; once merged, it becomes the edit. * In a connected part of the Context Layer, a version GitHub refused is marked **Not on GitHub**, and one Nekt has not sent yet is marked **Sending to GitHub**. * **View diff** compares a version with the one before it, or a proposal with the published version. * **Restore** brings back an older version. It is an edit like any other: in a workspace that writes through pull requests, it becomes a proposal. * **Show archived** includes proposals that were discarded or closed without a merge. Each document keeps its last 5 versions on Free, 30 on Starter, and 100 on Growth and Custom. Open proposals are always kept. ## API & MCP > [card] [Platform API](https://docs.nekt.com/platform-api/semantic-layer/update.md) > > Writes to a connected folder answer whether the change was applied or is waiting for a pull request. > [card] [MCP tools](https://docs.nekt.com/mcp-server/tools.md#versioning-on-github) > > Connect the Context Layer, follow pull requests, and read or restore the history. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.