# Workspace settings (https://docs.ctxpipe.ai/docs/workspaces/settings) Open a Workspace and choose the **Settings** tab. Two tags at the top show the [write access](#write-access) and the [hydrate status](#hydrate-and-skipped-files). 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](#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](#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-`, 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](/docs/self-hosting/upgrades#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](#write-access). | | ctxpipe cannot publish the re-ingestion | ctxpipe has no write access. See [Write access](#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`. ```yaml format: 3 upgrades: manual ``` The 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](/docs/workspaces/create-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](/docs/workspaces/create-workspace#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](#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](/docs/workspaces/knowledge-files#skipped-files). ## Sources A source tells the Workspace what to read through a connection. Each source is one Markdown file at `sources//.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](#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//.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//.md` | `repository` (`owner/name`), optional `ref` (a branch or a tag) | | Linear | `sources/linear/.md` | `teams` (team keys), `projects` (project ids), optional `customerRequests` (`exclude` or `limited`). At least one team or project. | | Notion | `sources/notion/.md` | `pages` and `databases`, each a list of `id` and `title`. At least one of them. | | Confluence | `sources/confluence/.md` | `spaces`: a list of `key` and `pages` (`all` or a list of page ids) | | Slack | `sources/slack/.md` | `channels`: a list of channel ids | | PagerDuty | `sources/pagerduty/.md` | `services`: a list of service ids | | Buildkite | `sources/buildkite/.md` | `pipelines`: a list of pipeline slugs | | Plain | `sources/plain/.md` | `helpCenters` (Help Center ids) and `labels` (label type ids). At least one of them. | | Plain git | `sources/git//.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.