Workspace settings
Manage the repositories and sources of a Workspace, and read its status, ingestion, write access, and upgrades.
Open a Workspace and choose the Settings tab. The pane has a summary line at the top, and then one card for each part of the Workspace.
The summary line names the cards that need you, and the cards that work now. Each name is a link to its card. The line has one of these forms:
- Everything is up to date.
- N parts need you: (or 1 part needs you:) and the names of the cards. The line can also say Running: and the names of the cards that work now.
- Nothing needs you. Running: and the names of the cards that work now.
A card that needs you has an amber edge. These are the cards, in the order of the pane:
| Card | What it holds |
|---|---|
| Upgrades | The upgrades that wait or run, the automatic-upgrades switch, the repository format, and the history. See Upgrades. |
| Sources | The code repositories and tools that the Workspace reads, and the live work of each one. See Sources. |
| Knowledge graph | Whether ctxpipe loaded the graph, and the files that ctxpipe skipped. See Hydrate and skipped files. |
| Repository | The Workspace repository, which this page calls the Context repository, the write access, and the Root folder. See Repositories and Write access. |
| Workspace | The Name (stored in AGENTS.md) and the URL name. If you change the URL name, old links stop working. Choose Save to keep a change. |
| Danger zone | Delete Workspace. This removes the Workspace and its conversations from ctxpipe. Your repository and its files stay. |
Each member can read the pane. Only an organization owner or admin can start an upgrade or change a source.
Upgrades
On the Upgrades card, each upgrade that needs you or runs now is a row. The dot of the row shows its kind: amber for an item that needs you, teal for work that runs, and red for a failure. The card header shows Up to date when no row is open and the format is the latest. It shows Checking the format while ctxpipe reads the format file.
A re-ingestion row also shows its spend so far. You can leave the page. The work continues. Applied upgrades show under History. Home shows an alert for each Workspace that has an upgrade to finish. Review upgrade on the alert opens this card.
An owner or admin chooses Start on a row. A member sees Ask an admin in place of the button.
Upgrades move the Workspace repository to the layout that this version of ctxpipe reads. Nothing changes until you merge the pull request. There are two kinds of upgrade:
- Upgrade to format N changes the layout of the repository. ctxpipe opens
one pull request on the branch
ctxpipe/upgrade/format-<N>, with one commit for each step. The last commit writes.ctxpipe/workspace.yaml. Read the notes under the row before you merge. - Fresh re-ingestion of the source repositories reads each linked repository again and publishes the new knowledge. See How extraction works. It needs format 3. For the cost and the restart rules, see Upgrade a Workspace.
| Status | What to do |
|---|---|
| Ready to start | An owner or admin chooses Start. |
| Queued, Preparing the pull request, Waiting | Wait. |
| Waiting for merge | Review and merge the pull request. If the card does not change after a few minutes, choose Check again. |
| Applied | Nothing. The upgrade is done. |
| Failed | Read the reason, fix the cause, then choose Start again. |
| Blocked | Read the reason and remove the cause. See the table below. |
If someone closes the pull request without a merge, the upgrade goes back to Ready to start.
| Blocked title | Cause |
|---|---|
| ctxpipe cannot open the upgrade pull request | ctxpipe has no write access. See Write access. |
| ctxpipe cannot publish the re-ingestion | ctxpipe has no write access. See Write access. |
| Apply the format upgrade first | The repository is below format 3. Merge the format upgrade, then choose Check again. The item then shows Waiting until ctxpipe reads the new format. |
| This deployment cannot run the re-ingestion | The deployment has no ingest sandbox. The operator must configure one. |
Automatic upgrades
By default, nothing starts by itself. To change this, an owner or admin turns
the Automatic upgrades switch on or off, or chooses Always update on the
Home alert. ctxpipe then commits the setting into .ctxpipe/workspace.yaml on
the default branch.
When automatic upgrades are on, ctxpipe starts each upgrade when it finds it. A merge always needs a person.
Repository format
Each Workspace repository holds .ctxpipe/workspace.yaml below its root
folder. The key format is the version of the repository layout. The optional
key upgrades is manual (the default) or automatic.
format: 3
upgrades: manualThe format line of the Upgrades card compares this format with the format that ctxpipe reads.
| Format | Layout |
|---|---|
| 0 | No format file: a repository from before Workspaces. |
| 1 | The knowledge that a fresh ingestion cannot rebuild is exported. Sources are in the older .ctxpipe/sources.yaml. |
| 2 | One Markdown file for each source under sources/. Source changes need format 2. |
| 3 | Ingestion writes ownership front matter in each knowledge file. This is the current format. Ingestion needs format 3. |
Only the setup commit of a new Workspace, an upgrade pull request, and the automatic-upgrades setting write this file. A format that this version of ctxpipe does not know, or a file that does not parse, makes the Workspace Read-only. Reads continue.
Sources
A source tells the Workspace what to read through a connection. Each source is
one Markdown file at sources/<provider>/<name>.md in the Workspace
repository. The front matter holds the provider, the connection, and the scope.
The body is an optional description that people and agents read. The path of
the file is the identity of the source.
The file on the default branch is the live scope. Each change to a source is a
pull request that a person merges. No agent can change sources/ without that
review. The buttons show only when ctxpipe can open a pull request. See
Write access.
The Sources card has one group for each provider that has a connection or a source. Each row shows the source, its file, and its status. Add another connection opens Connectors.
While ctxpipe works on a source, its row shows what ctxpipe does, for example Syncing or Publishing, and how long it has run. A row that has more than one run has a button that opens the stage and the progress of each run. You can leave the page. The work continues. While ingestion runs, the sidebar shows a pulse next to the Workspace.
Add, edit, rename, or remove a source
| Action | How |
|---|---|
| Add | Choose the add button in the group of the provider (Add repositories for GitHub). Select the scope, then choose Open a pull request. |
| Edit | Open the actions menu of the row, then choose Edit. Change the scope, then choose Open a pull request. |
| Rename | Open the actions menu of the row, then choose Rename. ctxpipe moves the file, and updates the knowledge files that name the old path, in the same pull request. |
| Remove | Open the actions menu of the row, then choose Remove. After the merge, the next sync deletes the files that the source wrote. Git history keeps them. Captured Slack threads stay. |
In the add dialog, File name is optional. Without a name, ctxpipe names the
file from the provider, for example linear or linear-2. A GitHub source is
always sources/github/<owner>/<name>.md.
Only an organization owner or admin can list the content of most providers. A member sees Ask an admin to choose what this source syncs. Any member can list Confluence spaces.
A row with an open pull request shows Awaiting merge, Rename awaiting merge, or Removal awaiting merge, with a link to the pull request. After the merge, the row updates in a few seconds.
Source status
| Status | Meaning |
|---|---|
| Connected | The file, the connection, and the scope work. The source syncs. The Workspace creation form shows OK for this status. |
| Not valid | The file does not parse, has a wrong shape, or breaks a rule. The sync skips it. The reason names the problem. |
| Connection missing | The connection of the source was removed. The file stays. |
| Out of access | The connection cannot reach the scope, for example a repository that is not in the GitHub App installation. ctxpipe checks again later. |
These rules apply across files:
- Two sources cannot name the same GitHub repository, or write to the same folder. The second file is Not valid.
- A GitHub source cannot name the Workspace repository.
- A source file larger than 64 KiB, or a file that is not text, is Not valid.
Source file format
Each file has the front matter key provider. Each file except a plain git
source also has connection. An unknown key makes the file Not valid.
| Provider | Path | Scope keys |
|---|---|---|
| GitHub | sources/github/<owner>/<name>.md | repository (owner/name), optional ref (a branch or a tag) |
| Linear | sources/linear/<name>.md | teams (team keys), projects (project ids), optional customerRequests (exclude or limited). At least one team or project. |
| Notion | sources/notion/<name>.md | pages and databases, each a list of id and title. At least one of them. |
| Confluence | sources/confluence/<name>.md | spaces: a list of key and pages (all or a list of page ids) |
| Slack | sources/slack/<name>.md | channels: a list of channel ids |
| PagerDuty | sources/pagerduty/<name>.md | services: a list of service ids |
| Buildkite | sources/buildkite/<name>.md | pipelines: a list of pipeline slugs |
| Plain | sources/plain/<name>.md | helpCenters (Help Center ids) and labels (label type ids). At least one of them. |
| Plain git | sources/git/<host>/<name>.md | url only |
Each path segment after the provider folder matches
[a-z0-9][a-z0-9._-]{0,99}. The keys id and kind are not allowed.
Hydrate and skipped files
Hydrate is the step that reads the files of the repository at one commit and builds the search index and the graph. The Knowledge graph card shows its status:
| The card shows | Meaning |
|---|---|
| The knowledge graph is loaded. | ctxpipe read the latest commit. |
| The knowledge graph waits to load. | ctxpipe did not start yet. |
| ctxpipe loads the knowledge graph now. | ctxpipe reads a commit now. The previous index serves until it is done. |
| The knowledge graph did not load | ctxpipe could not read the repository. The card shows the error. |
While ctxpipe indexes a new commit, the card also shows Indexing the newest commit… and the time since it started.
Before the first hydrate ends, the Workspace page shows Preparing and the name of the Workspace. If the first read fails, it shows Could not prepare the Workspace with the reason and Try again.
When ctxpipe skips files, the card shows ctxpipe skipped N files, with the path and the reason for each file. Chat, MCP, search, and the graph do not use a skipped file. Select a path to open the file in Files. Fix the file and push the fix to the default branch. See Skipped files.
Repositories
- Context repository: choose Change to move the Workspace to a different repository. The dialog has the same options as Create a Workspace. The Workspace and its conversations stay. The files in the old repository stay where they are. Until the new repository is loaded, answers come from the old one.
- Root folder: the folder of the repository that holds the Workspace. See Root folder.
Write access
ctxpipe writes to the Workspace repository through the ctxpipe GitHub App. The Repository card shows the result of the last check in one line. The header of a conversation also shows a tag, but not when ctxpipe can push. The tag has the same title as the line.
| The UI shows | Meaning |
|---|---|
| ctxpipe can push to this repository. | The GitHub App can push to the repository. The state is writable. |
| Changes by pull request | The default branch is protected. Conversations and source changes use pull requests. Connector mirrors and extracted knowledge cannot push to the default branch, so they stop. |
| Checking write access | ctxpipe is checking. The pane checks again by itself. On the card, the line says "ctxpipe checks write access now." If the check takes longer than usual, the card shows Still checking write access. |
| Could not check write access | GitHub returned an error or a rate limit. Choose Check again. |
| Read-only | ctxpipe cannot write. Search, chat, and the graph continue to work on the latest commit. |
A Read-only Workspace shows the reason:
| Reason | What to do |
|---|---|
| The remote is not GitHub. | Select a GitHub repository as the context repository. |
| GitHub is not connected for this organization. | An owner or admin connects GitHub on Connectors. Then choose Select the repository again. |
| The repository is not in the GitHub App installation. | Add the repository to the installation in GitHub. |
| The GitHub App cannot write to this repository. | Give the GitHub App Contents: Read and write. |
| The Workspace needs a newer ctxpipe version. | The repository format is newer than this ctxpipe version. Upgrade ctxpipe. See Repository format. |
The file .ctxpipe/workspace.yaml is not valid. | Repair the file in the repository. |
After you fix the cause, reload the page. ctxpipe checks again at most once a minute.