GitHub

Workstate reads GitHub repositories through the Workstate GitHub App. You choose which repositories to share on GitHub's own install page, and you can change that choice on GitHub at any time. The App only reads. It never writes to your repositories.

What Workstate reads

• The default branch of each repository you share. Each sync reads the latest commit on that branch. Workstate does not read other branches, commit history, pull requests or issues.
• Repositories on github.com. GitHub Enterprise Server is not supported yet Coming soon.

Each repository is searchable under its own name, for example search_corpus(repo: "payments-api"). Every file from GitHub goes into the code corpus, Markdown included. To find documentation in a repository, filter by language: "markdown".

Files Workstate skips

• Hidden files and folders, whose names start with a dot, such as .env and .github
• Files that the repository's .gitignore excludes
• Dependency and build folders: node_modules, vendor, target, dist, build, venv and __pycache__
• Lockfiles, such as package-lock.json, yarn.lock, pnpm-lock.yaml, Cargo.lock and any file ending in .lock
• Minified files ending in .min.js or .min.css
• Files larger than 1 MB, empty files, binary files, and files that are not UTF-8 text
• Files with a line longer than 50,000 bytes, which are usually generated

Repositories Workstate skips

• Archived repositories. If you archive a repository on GitHub, the next sync takes it out of the index.
• Empty repositories, which have no commits yet.
• A repository whose name is already indexed in the namespace by another source. Workstate leaves it to that source rather than index it twice.

Committed secrets are indexed

Workstate does not look for secrets inside files. It skips hidden files such as .env, but a password, token or private key committed to any other file is indexed, and everyone who can reach the namespace can find it through search.

Before you share a repository, remove any secrets from its default branch. Workstate reads only the latest commit, so once a new commit removes a secret, the next sync removes it from the index. The secret is still in your Git history on GitHub, so change it anyway. Secret filtering for GitHub sources is on the way Coming soon.

What you need

• The owner or admin role in Workstate.
• On GitHub, to be an owner of the organisation you install the App on, or the owner of the personal account. If you are a member of the organisation but not an owner, GitHub asks the owners to approve the install instead. See If an owner must approve.
• In the console, the namespace you want the repositories in, selected in the switcher at the top of the sidebar.

Connect repositories

1. Open Sources. Under Add a source, select GitHub.
2. In Name, type a name for the source, for example "Our code". The name labels the source in the console. Each repository is still searchable under its own name.
3. Select Install on GitHub. The console sends you to GitHub.
4. On GitHub, choose the organisation or personal account to install the App on. Then choose all repositories, or only the repositories you select, and confirm.
5. GitHub sends you back to the new source's page. It says: "Connected. The first sync is on its way: it reads each repository the installation shares, so a large one can take a few minutes."

Finish on GitHub within 30 minutes of selecting Install on GitHub. After that, the console refuses the install and you start again.

If the App is already installed

When the Workstate GitHub App is already installed on the account, connect that installation instead of installing again:

1. Under Add a source, select GitHub, then Connect an existing installation.
2. Type a Name, and in GitHub account it is installed on, type the account's name, for example your-org.
3. Select Connect on GitHub. GitHub asks you to confirm who you are, then sends you back.

The installation becomes a source when you are an owner of that organisation, or it is your own account, and no other Workstate account has connected it.

If an owner must approve

If you are not an owner of the organisation, GitHub sends its owners a request instead of installing the App. The console tells you so. Once an owner approves the request, an owner of the organisation adds the source with Connect an existing installation.

Change which repositories are shared

The source's page has a Connection panel:

• Installed on names the GitHub account.
• Shares says whether the installation shares all repositories or selected ones, and how many it could read at the last sync.
• Change it links to the installation's settings on GitHub.

Change the selection on GitHub. The next sync follows it. To apply the change now, select Sync now.

A repository you stop sharing is removed from search

At the next sync, Workstate removes every repository the App can no longer read from the index. That includes repositories you deselect on GitHub and repositories you archive. Keep a repository shared for as long as you want it searchable.

Workstate protects the index when GitHub gives an incomplete answer. If GitHub refuses access to a repository, that sync removes nothing, and the repository keeps what it had indexed. If a sync suddenly finds no repositories at all while content is indexed, the sync fails instead of emptying the source.

Check it worked

1. On the source's page, the status reads Up to date, and Sync history shows the sync as Succeeded.
2. While a sync runs, Sync progress shows each repository as Waiting, Reading, Read, Indexing, Done, Skipped or Failed. A skipped or failed repository shows the reason.
3. Open Repositories. Your repositories appear by name.
4. Open Search and search for something you know is in one of the repositories.

Disconnect a GitHub source

To remove the repositories from search, delete the source: on its page, select the trash icon (Delete this source), then Delete source. Deleting the source removes everything indexed from it. You cannot undo it.

If you uninstall the App on GitHub but keep the source, its syncs fail. What was already indexed stays searchable until you delete the source.

Each installation belongs to one Workstate account. To connect an installation to a different Workstate account, first delete the sources that use it in the current account.

Troubleshooting

After an install, the console shows a message when no source was added. Syncs that fail show their error on the source's page.

What you see	What to do
"Installing on that organisation needs an owner's approval…"	Wait for an owner to approve the request on GitHub. Then an owner adds the source with Connect an existing installation.
"That install was already finished, or took longer than 30 minutes."	Start again under Add a source, and finish on GitHub within 30 minutes.
"Only an admin of the organisation the App is installed on, or the owner of a personal account, can add its installation…"	Ask an owner of the GitHub organisation to connect the installation.
"GitHub would not say whether you administer that organisation…"	An owner of the organisation approves the App's permission to read its members in the organisation's GitHub settings. Then try again.
"That installation is already connected to another Workstate account…"	The other account must delete its sources for the installation first.
"The App is not installed on that account…"	Check the spelling of the account name, or select Install the App instead.
"Another source took that name while you were on GitHub."	The App is installed. Add it under another name with Connect an existing installation.
A repository is Skipped: "already indexed from elsewhere in this namespace"	Another source in the namespace already indexes a repository with that name.
A repository is Skipped: "archived on GitHub"	Unarchive the repository on GitHub if you want it searchable.
A repository is Failed: "GitHub refused access to it"	Check the installation's settings on GitHub. Nothing was removed from the index.
The sync fails: "the source listed nothing while … of its files are indexed…"	The App has probably lost access, for example because it was uninstalled or shares no repositories. Check the installation's settings on GitHub.

Related

• Sync schedules
• Sources & sync
• Search & citations
• Security & privacy