Sources & sync
A source is a place Workstate reads from: a GitHub installation, a Confluence site, a Jira site, or a set of files you upload. A sync is one pass in which Workstate reads a source and brings the search index up to date with it.
Each source belongs to one namespace. Workstate only reads your sources, and never changes them.
Kinds of source
| Source | What Workstate reads | Corpus |
|---|---|---|
| GitHub | The default branch of each repository you share with the Workstate GitHub App. No history, pull requests or issues. | code, for every file, Markdown included |
| Confluence | The current pages of up to 50 spaces, on a *.atlassian.net site. | wiki |
| Jira | The issues of up to 50 projects, on a *.atlassian.net site, each with up to 500 comments. | wiki |
| Upload files | Markdown, text and code, PDF, and Word, Excel and PowerPoint files that you upload. | code for code files, wiki for everything else |
The corpus decides which search filter finds the content. See Search & citations.
What a sync does
A sync reads the source, compares what it finds with the last sync, and indexes only new and changed files. Files that are gone from the source are removed from the index. So is a GitHub repository that you stop sharing with the App.
Workstate protects the index when it cannot read a source in full. If GitHub refuses access to a repository, or Confluence or Jira returns only part of a listing, that sync removes nothing. If the GitHub App is uninstalled, syncs fail, and the content already indexed stays until you delete the source.
The source's page shows the progress of a running sync, repository by repository, and a history of past syncs.
When syncs run
- On a schedule. GitHub, Confluence and Jira sources sync once a day by default. An owner or admin can change this on the source's page to every 5 minutes, 15 minutes, hour, 6 hours, day or week. Five minutes is the shortest interval.
- When someone asks. Anyone who can reach the namespace can select Sync now. An agent can call
reindex_corpus, which queues a sync of every GitHub, Confluence and Jira source in its namespace, except paused ones. - When files change. An upload source changes only when someone uploads or deletes files, and each change starts a sync.
Asking for a sync while one is queued or running does not stack syncs. One more sync runs after the current one, so no change is missed.
Sync status
| Status | Meaning |
|---|---|
| Queued | The sync is waiting for its turn. |
| Syncing | Workstate is reading and indexing the source now. |
| Up to date | The last sync finished. |
| Failed | The last sync failed, and the source's page shows the error. Content from earlier syncs stays in the index. |
| Paused | An owner or admin paused the source, so it does not sync on its schedule. |
| Stopping | An owner or admin stopped a running sync. It ends within seconds and keeps what it indexed. The source then stays paused until someone resumes it. |
| Deleting | The source and everything indexed from it are being removed. |
Who can do what
Owners and admins add sources, change their schedule, pause and resume them, stop syncs, upload and delete files, and delete sources. Everyone who can reach the namespace can select Sync now.
Deleting a source removes everything indexed from it, its uploaded files and its sync history. Deletion cannot be undone.
Limits
GitHub sources are not filtered for secrets
Workstate skips hidden files such as .env, but it does not look for secrets inside other files. A password, token or key committed to a shared repository is indexed, and everyone in the namespace can find it. Remove secrets from a repository before you share it. Uploads refuse private keys and .env files.
- Changes appear at the next sync. Syncing when you push to GitHub, or when a page changes, is not built yet Coming soon.
- For GitHub, Workstate reads only the latest commit on the default branch.
- More sources, such as Slack and Google Drive, are planned. See Coming soon.