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. Two tags at the top show the write access and the hydrate status. Below them are these groups:
| Group | What it holds |
|---|---|
| Status | Whether you must do something, the work that runs now, the upgrades, and the repository format. See Status. |
| General | The Name (stored in AGENTS.md) and the URL name. If you change the URL name, old links stop working. |
| Repositories | The Workspace repository, which this page calls the Context repository, and the Root folder. |
| Sources | The code repositories and tools that the Workspace reads. See Sources. |
| Danger zone | Delete Workspace. This removes the Workspace and its conversations from ctxpipe. Your repository and its files stay. |
Status
Status is the first group of the pane. Its headline tells you if you must do something:
| Headline | Meaning |
|---|---|
| Needs you | An item waits for a person: a start, a merge, or a fix. A format file that ctxpipe cannot read is also an item. |
| Working | ctxpipe runs an upgrade, reads a merged pull request, ingests a source, or checks the repository format. No action is needed. |
| Up to date | No item is open. |
The open items are in two lists:
- Needs you: the upgrades that wait for a person.
- Working now: the upgrades that ctxpipe runs, and each ingestion that runs now, with its stage, progress, and time. A re-ingestion also shows its spend so far. You can leave the page. The work continues.
While ingestion runs, the sidebar shows a teal dot next to the Workspace. Items that are done show under History. Home shows an alert for each Workspace that has an upgrade to finish. Review upgrade on the alert opens this group.
Each member can read the group. Only an organization owner or admin can start an item. A member sees Ask an admin in place of the button.
Upgrades
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 on the card before you merge. - Fresh re-ingestion of the source repositories reads each linked repository again and publishes the new knowledge. 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. The group shows Automatic upgrades: Off
or Automatic upgrades: On. An owner or admin chooses Turn on or Turn
off, or 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 health line of the Status group 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.
Repositories
- Context repository: choose the edit button 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 write access tag shows the result of the last check:
| Tag | Meaning |
|---|---|
| Can save changes | The GitHub App can push to the repository. |
| Changes by pull request | The default branch is protected. Conversations and source changes use pull requests. This is a normal state. |
| Checking write access | ctxpipe is checking. The pane checks again by itself. |
| 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.
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 hydrate tag shows its status:
| Tag | Meaning |
|---|---|
| Ready | ctxpipe read the latest commit. |
| Hydrate pending | ctxpipe did not start yet. |
| Hydrating | ctxpipe is reading a commit. The previous index serves until it is done. |
| Loading failed | ctxpipe could not read the repository. The pane shows the error. |
Before the first hydrate ends, the Workspace page shows Preparing. If the first read fails, it shows Could not prepare the Workspace with the reason and Try again.
When ctxpipe skips files, Settings shows Hydrate 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.
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 group has one group for each provider that has a connection or a source. Each row shows the source, the connection, the file, and the status. Add another connection opens Connectors.
Add, edit, rename, or remove a source
| Action | How |
|---|---|
| Add | Choose Add in the group of the provider (Add repositories for GitHub). Select the scope, then choose Open a pull request. |
| Edit | Choose the pencil button of the row. Change the scope, then choose Open a pull request. |
| Rename | Choose the rename button of the row. ctxpipe moves the file, and updates the knowledge files that name the old path, in the same pull request. |
| Remove | Choose the remove button of the row. 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 |
|---|---|
| OK | The file, the connection, and the scope work. The source syncs. |
| 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.