Workspaces

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:

CardWhat it holds
UpgradesThe upgrades that wait or run, the automatic-upgrades switch, the repository format, and the history. See Upgrades.
SourcesThe code repositories and tools that the Workspace reads, and the live work of each one. See Sources.
Knowledge graphWhether ctxpipe loaded the graph, and the files that ctxpipe skipped. See Hydrate and skipped files.
RepositoryThe Workspace repository, which this page calls the Context repository, the write access, and the Root folder. See Repositories and Write access.
WorkspaceThe 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 zoneDelete 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.
StatusWhat to do
Ready to startAn owner or admin chooses Start.
Queued, Preparing the pull request, WaitingWait.
Waiting for mergeReview and merge the pull request. If the card does not change after a few minutes, choose Check again.
AppliedNothing. The upgrade is done.
FailedRead the reason, fix the cause, then choose Start again.
BlockedRead 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 titleCause
ctxpipe cannot open the upgrade pull requestctxpipe has no write access. See Write access.
ctxpipe cannot publish the re-ingestionctxpipe has no write access. See Write access.
Apply the format upgrade firstThe 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-ingestionThe 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: manual

The format line of the Upgrades card compares this format with the format that ctxpipe reads.

FormatLayout
0No format file: a repository from before Workspaces.
1The knowledge that a fresh ingestion cannot rebuild is exported. Sources are in the older .ctxpipe/sources.yaml.
2One Markdown file for each source under sources/. Source changes need format 2.
3Ingestion 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

ActionHow
AddChoose the add button in the group of the provider (Add repositories for GitHub). Select the scope, then choose Open a pull request.
EditOpen the actions menu of the row, then choose Edit. Change the scope, then choose Open a pull request.
RenameOpen 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.
RemoveOpen 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

StatusMeaning
ConnectedThe file, the connection, and the scope work. The source syncs. The Workspace creation form shows OK for this status.
Not validThe file does not parse, has a wrong shape, or breaks a rule. The sync skips it. The reason names the problem.
Connection missingThe connection of the source was removed. The file stays.
Out of accessThe 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.

ProviderPathScope keys
GitHubsources/github/<owner>/<name>.mdrepository (owner/name), optional ref (a branch or a tag)
Linearsources/linear/<name>.mdteams (team keys), projects (project ids), optional customerRequests (exclude or limited). At least one team or project.
Notionsources/notion/<name>.mdpages and databases, each a list of id and title. At least one of them.
Confluencesources/confluence/<name>.mdspaces: a list of key and pages (all or a list of page ids)
Slacksources/slack/<name>.mdchannels: a list of channel ids
PagerDutysources/pagerduty/<name>.mdservices: a list of service ids
Buildkitesources/buildkite/<name>.mdpipelines: a list of pipeline slugs
Plainsources/plain/<name>.mdhelpCenters (Help Center ids) and labels (label type ids). At least one of them.
Plain gitsources/git/<host>/<name>.mdurl 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 showsMeaning
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 loadctxpipe 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 showsMeaning
ctxpipe can push to this repository.The GitHub App can push to the repository. The state is writable.
Changes by pull requestThe 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 accessctxpipe 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 accessGitHub returned an error or a rate limit. Choose Check again.
Read-onlyctxpipe cannot write. Search, chat, and the graph continue to work on the latest commit.

A Read-only Workspace shows the reason:

ReasonWhat 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.