Skip to main content
GitHub Versioning keeps the code of your Notebooks and Queries in a GitHub repository. Each resource is linked to a repository and a branch, and Nekt keeps both sides in sync: a push to that branch updates the resource in Nekt, and saving code in Nekt commits it to that branch. You get version control, collaboration through pull requests, and a clear audit trail. This requires a workspace-wide GitHub connection: an owner or admin connects your GitHub organization in Settings → GitHub before you can link repositories to individual Notebooks or Queries.

​
Prerequisite: Connect GitHub (workspace)

Before linking repositories, an owner or admin must connect your GitHub organization in Settings → GitHub. This step is mandatory before you can assign repositories to Notebooks.

​
Prepare your repository

The repository can be empty, and several Notebooks and Queries can share it. Nekt stores each resource in its own folder, named after the resource’s pipeline slug. You don’t choose the folder.
Other files in the repository, such as a README.md or CI configuration, are ignored. You can link a repo when creating a new Notebook or editing an existing one.

​
When creating a new Notebook

During creation, use the GitHub section to select the repository and branch.

​
When editing an existing Notebook

  1. Open the Notebook.
  2. Go to Settings and find the GitHub / versioning section.
  3. Select the repository (and branch) to link.
You can also use the Versioning column in the Notebooks list: click Connect repository and choose the repo.

​
How the sync works

  • Linking uploads the code from Nekt. When you link a resource to a repository, Nekt commits its current code to the resource’s folder on the chosen branch, replacing any notebook.py, query.sql, or requirements.txt already in that folder.
  • Pushes to the branch update Nekt. Nekt reads the files changed in each push to the linked branch and updates only the resources whose files changed. Pushes to other branches are ignored.
  • Saving in Nekt commits to the branch. When you save code or dependencies in Nekt, the change is committed to the linked branch. If GitHub rejects the commit, for example because of a branch protection rule, the save fails.
  • Pushed Notebooks are validated before they apply. Nekt checks that the tables, volumes, and secrets a Notebook uses exist, and that the user who linked it can read its input tables and edit its output tables. If a check fails, the code in Nekt is not changed and the error is shown on the Notebook. Fix the code and push again.
Linking a resource overwrites its folder in the repository with the code currently in Nekt. If the repository already holds the version you want to keep, link the resource first, then push that version again: Nekt imports it from the push.
  • Link the branch you deploy from, typically main, and review changes through pull requests: merging into main is what updates Nekt.
  • Pick one place to edit. If your branch requires pull requests, saves made in Nekt cannot be committed and fail. In that case, edit code only through GitHub.
  • Link resources with a user who keeps the right permissions. Syncs triggered by a push run with the permissions of the user who linked the resource, so use someone with access to its input and output tables who will stay in the workspace.

​
API & MCP

Platform API

Not available in the Platform API yet.

MCP tools

connect_transformations_to_github and list_github_repositories.