Skip to main content
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.
Available on the Starter, Growth, and Custom plans. It requires the organization’s GitHub connection, and the repository must be one the workspace may use.
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:
  • 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. 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

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

Platform API

Writes to a connected folder answer whether the change was applied or is waiting for a pull request.

MCP tools

Connect the Context Layer, follow pull requests, and read or restore the history.